


PPPD(8)                                                   PPPD(8)


NAME
       pppd - Point to Point Protocol daemon

SYNOPSIS
       pppd [ tty_name ] [ 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
       Protocol  (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
       Internet Protocol (IP) (called the  IP  Control  Protocol,
       IPCP).

FREQUENTLY USED OPTIONS
       <tty_name>
              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 con-
              nected to the standard input is  given,  pppd  will
              use  that terminal, and will not fork to put itself
              in the background.  This option  is  privileged  if
              the noauth option is used.

       <speed>
              Set  the  baud  rate to <speed> (a decimal number).
              On systems such as 4.4BSD and  OpenBSD,  any  speed
              can  be  specified.   Other  systems  (e.g., SunOS)
              allow only a limited set of speeds.

       active-filter filter-expression
              Specifies a packet filter to  be  applied  to  data
              packets  to  determine  which  packets  are  to  be
              regarded as link activity, and therefore reset  the
              idle  timer,  or cause the link to be brought up in
              demand-dialling mode.  This  option  is  useful  in
              conjunction with the idle option if there are pack-
              ets being sent or received regularly over the  link
              (for  example,  routing  information packets) which
              would otherwise prevent the link from ever  appear-
              ing to be idle.  The filter-expression syntax is as
              described for tcpdump(1),  except  that  qualifiers
              which  are  inappropriate  for  a PPP link, such as
              ether and arp, are not  permitted.   Generally  the
              filter  expression  should  be  enclosed in single-
              quotes to prevent whitespace in the expression from
              being  interpreted  by  the  shell.  This option is



                                                                1





PPPD(8)                                                   PPPD(8)


              currently only available under  OpenBSD,  and  then
              only if both the kernel and pppd were compiled with
              PPP_FILTER defined.

       asyncmap <map>
              Set the async character map  to  <map>.   This  map
              describes  which  control characters cannot be suc-
              cessfully 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 num-
              ber  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 should then escape all control characters.  To
              escape   transmitted  characters,  use  the  escape
              option.

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

       call name
              Read  options  from  the  file /etc/ppp/peers/name.
              This file may contain privileged options,  such  as
              noauth, even if pppd is not being run by root.  The
              name string may not begin with / or include .. as a
              pathname component.  The format of the options file
              is described below.

       connect script
              Use the executable or shell  command  specified  by
              script  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.  This
              option is privileged if the noauth option is  used.

       crtscts
              Use  hardware  flow control (i.e., RTS/CTS) to con-
              trol the flow of data on the serial port.  If  nei-
              ther the crtscts nor the nocrtscts option is given,
              the hardware flow control setting  for  the  serial
              port is left unchanged.

       defaultroute
              Add  a  default route to the system routing tables,
              using the peer as the gateway, when  IPCP  negotia-
              tion  is  successfully  completed.   This  entry is
              removed when the PPP connection  is  broken.   This
              option  is  privileged if the nodefaultroute option
              has been specified.




                                                                2





PPPD(8)                                                   PPPD(8)


       disconnect script
              Run the executable or shell  command  specified  by
              script  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 con-
              trol signals were not  available.   The  disconnect
              script is not run if the modem has already hung up.
              This option is privileged if the noauth  option  is
              used.

       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  charac-
              ters to be specified.  The characters which may not
              be escaped are those with hex values 0x20 - 0x3f or
              0x5e.

       file name
              Read   options   from  file  name  (the  format  is
              described below).  The file must be readable by the
              user who has invoked pppd.

       lock   Specifies that pppd should create a UUCP-style lock
              file for the  serial  device  to  ensure  exclusive
              access to the device.

       mru n  Set the MRU [Maximum Receive Unit] value to n. 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).

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

       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.





                                                                3





PPPD(8)                                                   PPPD(8)


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 nota-
              tion  (e.g.,  150.234.56.78).   The  default  local
              address  is  the  (first)  IP address of the system
              (unless the  noipdefault  option  is  given).   The
              remote  address  will  be obtained from the peer if
              not specified  in  any  option.   Thus,  in  simple
              cases,  this  option  is  not required.  If a local
              and/or remote IP address  is  specified  with  this
              option, 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.

       bsdcomp nr,nt
              Request that the  peer  compress  packets  that  it
              sends,  using the BSD-Compress scheme, with a maxi-
              mum code size of nr bits,  and  agree  to  compress
              packets  sent  to the peer with a maximum code size
              of nt bits.  If nt is not specified, it defaults to
              the  value  given for nr.  Values in the range 9 to
              15 may be used for nr and nt;  larger  values  give
              better  compression  but consume more kernel memory
              for  compression  dictionaries.   Alternatively,  a
              value of 0 for nr or nt disables compression in the
              corresponding direction.  Use nobsdcomp or  bsdcomp
              0 to disable BSD-Compress compression entirely.

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

       chap-max-challenge n
              Set the maximum number of CHAP challenge  transmis-
              sions to n (default 10).

       chap-restart n
              Set the CHAP restart interval (retransmission time-
              out for challenges) to n seconds (default 3).

       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 daemon and level debug.  This  information
              can  be  directed to a file by setting up /etc/sys-
              log.conf appropriately (see syslog.conf(5)).

       default-asyncmap
              Disable asyncmap negotiation, forcing  all  control
              characters  to be escaped for both the transmit and



                                                                4





PPPD(8)                                                   PPPD(8)


              the receive direction.

       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.

       deflate nr,nt
              Request  that  the  peer  compress  packets that it
              sends, using the Deflate  scheme,  with  a  maximum
              window  size  of 2**nr bytes, and agree to compress
              packets sent to the peer with a maximum window size
              of  2**nt  bytes.   If  nt  is  not  specified,  it
              defaults to the value given for nr.  Values in  the
              range  8  to  15  may be used for nr and nt; larger
              values give better  compression  but  consume  more
              kernel memory for compression dictionaries.  Alter-
              natively, a value of 0 for nr or nt  disables  com-
              pression in the corresponding direction.  Use node-
              flate or deflate 0 to disable  Deflate  compression
              entirely.  (Note: pppd requests Deflate compression
              in preference to BSD-Compress if the  peer  can  do
              either.)

       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 ini-
              tially configure the interface and enable it for IP
              traffic without connecting to the peer.  When traf-
              fic 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 demand option implies the persist  option.   If
              this  behaviour  is  not desired, use the nopersist
              option after the demand option.  The idle and hold-
              off  options are also useful in conjuction with the
              demand option.

       domain d
              Append the domain name d to the local host name for
              authentication  purposes.  For example, if gethost-
              name() returns the  name  porsche,  but  the  fully
              qualified  domain  name is porsche.Quotron.COM, you
              could specify domain Quotron.COM.  Pppd would  then
              use  the  name  porsche.Quotron.COM  for looking up
              secrets in the secrets file,  and  as  the  default
              name to send to the peer when authenticating itself
              to the peer.  This option is privileged.





                                                                5





PPPD(8)                                                   PPPD(8)


       holdoff n
              Specifies how many seconds to wait before re-initi-
              ating  the  link  after it terminates.  This option
              only has any effect if the persist or demand option
              is  used.  The holdoff period is not applied if the
              link was terminated because it was idle.

       idle n Specifies that pppd should disconnect if  the  link
              is  idle  for  n seconds.  The link is idle when no
              data packets (i.e., IP packets) are being  sent  or
              received.   Note:  it  is not advisable to use this
              option with the persist option without  the  demand
              option.  If the active-filter option is given, data
              packets which are rejected by the specified  activ-
              ity filter also count as the link being idle.

       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.

       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).

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

       ipcp-restart n
              Set the IPCP restart interval (retransmission time-
              out) to n seconds (default 3).

       ipparam string
              Provides an extra parameter to the  ip-up  and  ip-
              down  scripts.  If this option is given, the string
              supplied is given as the  6th  parameter  to  those
              scripts.

       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 sup-
              port.




                                                                6





PPPD(8)                                                   PPPD(8)


       ipx-network n
              Set the IPX network number in the  IPXCP  configure
              request frame to n, 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.

       ipx-node n:m
              Set the IPX node numbers. The two node numbers  are
              separated  from  each other with a colon character.
              The first number n is the local  node  number.  The
              second  number  m  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.

       ipx-router-name <string>
              Set the name of the router. This is a string and is
              sent to the peer as information data.

       ipx-routing n
              Set  the  routing  protocol  to be received by this
              option. More than one instance of  ipx-routing  may
              be  specified.  The 'none' option (0) may be speci-
              fied as the only instance of ipx-routing. The  val-
              ues  may  be  0  for NONE, 2 for RIP/SAP, and 4 for
              NLSP.

       ipxcp-accept-local
              Accept the peer's NAK for the node number specified
              in the ipx-node option. If a node number was speci-
              fied, 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.

       ipxcp-accept-network
              Accept the peer's NAK for the network number speci-
              fied 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.

       ipxcp-accept-remote
              Use the peer's network number specified in the con-
              figure  request  frame. If a node number was speci-
              fied for the peer and this option  was  not  speci-
              fied,  the  peer  will  be  forced to use the value
              which you have specified.



                                                                7





PPPD(8)                                                   PPPD(8)


       ipxcp-max-configure n
              Set the maximum number of IPXCP  configure  request
              frames which the system will send to n. The default
              is 10.

       ipxcp-max-failure n
              Set the maximum number of IPXCP  NAK  frames  which
              the  local  system  will send before it rejects the
              options. The default value is 3.

       ipxcp-max-terminate n
              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.

       kdebug n
              Enable  debugging  code  in  the  kernel-level  PPP
              driver.  The argument n is a number  which  is  the
              sum  of  the  following values: 1 to enable general
              debug messages, 2 to request that the  contents  of
              received  packets be printed, and 4 to request that
              the contents of transmitted packets be printed.  On
              most  systems,  messages  printed by the kernel are
              logged by syslog(1) to a file as  directed  in  the
              /etc/syslog.conf configuration file.

       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
              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 lcp-echo-
              interval parameter.  This option  can  be  used  to
              enable pppd to terminate after the physical connec-
              tion has been broken (e.g., the modem has hung  up)
              in situations where no hardware modem control lines
              are available.

       lcp-echo-interval n
              If this option is given,  pppd  will  send  an  LCP
              echo-request  frame  to  the  peer every 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-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



                                                                8





PPPD(8)                                                   PPPD(8)


              instead to n (default 10).

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

       lcp-restart n
              Set  the LCP restart interval (retransmission time-
              out) to n seconds (default 3).

       local  Don't use  the  modem  control  lines.   With  this
              option,  pppd will ignore the state of the CD (Car-
              rier Detect) signal from the  modem  and  will  not
              change  the  state of the DTR (Data Terminal Ready)
              signal.

       login  Use the system password database for authenticating
              the peer using PAP, and record the user in the sys-
              tem 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.

       maxconnect n
              Terminate the connection when it has been available
              for network traffic for n seconds (i.e., n  seconds
              after the first network control protocol comes up).

       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 crtscts option.

       modem_chat
              Use the modem control lines during the chat script.
              The  default is to ignore the state of the CD (Car-
              rier Detect) signal from the modem during the  chat
              script.   If you are using a cua device (as opposed
              to a tty device) you should set this  option.   You
              should not use this option with a dialback setup as
              it will cause the chat script to exit when  carrier
              drops.

       ms-dns <addr>
              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  speci-
              fies  the  primary DNS address; the second instance
              (if given) specifies  the  secondary  DNS  address.



                                                                9





PPPD(8)                                                   PPPD(8)


              (This  option was present in some older versions of
              pppd under the name dns-addr.)

       ms-wins <addr>
              If pppd is acting as a server for Microsoft Windows
              or "Samba" clients, this option allows pppd to sup-
              ply one or two WINS  (Windows  Internet  Name  Ser-
              vices)  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.

       name name
              Set the name of the local system for authentication
              purposes  to  name.   This  is a privileged option.
              With this  option,  pppd  will  use  lines  in  the
              secrets  files  which have name as the second field
              when looking for a secret to use in  authenticating
              the  peer.  In addition, unless overridden with the
              user option, name 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 name.)

       netmask n
              Set the interface netmask to n, 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.

       noaccomp
              Disable  Address/Control compression in both direc-
              tions (send and receive).

       noauth Do not require the  peer  to  authenticate  itself.
              This  option  is  privileged  if the auth option is
              specified in /etc/ppp/options.

       nobsdcomp
              Disables BSD-Compress compression;  pppd  will  not
              request or agree to compress packets using the BSD-
              Compress scheme.

       noccp  Disable CCP (Compression Control Protocol) negotia-
              tion.   This  option should only be required if the
              peer is buggy and gets confused  by  requests  from
              pppd for CCP negotiation.





                                                               10





PPPD(8)                                                   PPPD(8)


       nocrtscts
              Disable  hardware  flow  control (i.e., RTS/CTS) on
              the serial port.  If neither the  crtscts  nor  the
              nocrtscts  option  is given, the hardware flow con-
              trol setting for the serial port is left unchanged.

       nodefaultroute
              Disable the defaultroute option.  The system admin-
              istrator who wishes to prevent users from  creating
              default  routes with pppd can do so by placing this
              option in the /etc/ppp/options file.

       nodeflate
              Disables Deflate compression; pppd will not request
              or  agree  to  compress  packets  using the Deflate
              scheme.

       nodetach
              Don't detach from the controlling terminal.   With-
              out  this option, if a serial device other than the
              terminal on the standard input is  specified,  pppd
              will fork to become a background process.

       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.

       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).

       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 nego-
              tiation.

       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.

       nopcomp
              Disable protocol field compression  negotiation  in
              both the receive and the transmit direction.

       nopersist
              Exit   once   a   connection   has  been  made  and



                                                               11





PPPD(8)                                                   PPPD(8)


              terminated.  This is the default unless the persist
              or demand option has been specified.

       nopredictor1
              Do  not accept or agree to Predictor-1 compression.

       noproxyarp
              Disable the proxyarp option.  The  system  adminis-
              trator  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.

       novj   Disable  Van  Jacobson style TCP/IP header compres-
              sion in both the transmit and  the  receive  direc-
              tion.

       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.

       papcrypt
              Indicates  that  all  secrets  in the /etc/ppp/pap-
              secrets file which are used for checking the  iden-
              tity  of  the  peer  are  encrypted,  and thus pppd
              should not accept a password which, before  encryp-
              tion,   is   identical   to  the  secret  from  the
              /etc/ppp/pap-secrets file.

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

       pap-restart n
              Set  the PAP restart interval (retransmission time-
              out) to n seconds (default 3).

       pap-timeout n
              Set the maximum time that pppd will  wait  for  the
              peer  to  authenticate itself with PAP to n seconds
              (0 means no limit).

       pass-filter filter-expression
              Specifies a packet filter to applied to data  pack-
              ets being sent or received to determine which pack-
              ets 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
              filter-expression  syntax  is as described for tcp-
              dump(1),   except   that   qualifiers   which   are



                                                               12





PPPD(8)                                                   PPPD(8)


              inappropriate  for  a  PPP  link, such as ether and
              arp,  are  not  permitted.   Generally  the  filter
              expression  should  be enclosed in single-quotes to
              prevent whitespace in  the  expression  from  being
              interpreted by the shell.  Note that it is possible
              to apply different constraints to incoming and out-
              going packets using the inbound and outbound quali-
              fiers. This  option  is  currently  only  available
              under OpenBSD, and then only if both the kernel and
              pppd were compiled with PPP_FILTER defined.

       persist
              Do not  exit  after  a  connection  is  terminated;
              instead try to reopen the connection.

       predictor1
              Request that the peer compress frames that it sends
              using Predictor-1 compression, and  agree  to  com-
              press   transmitted   frames  with  Predictor-1  if
              requested.  This option has no  effect  unless  the
              kernel driver supports Predictor-1 compression.

       proxyarp
              Add  an entry to this system's ARP [Address Resolu-
              tion 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.

       remotename name
              Set  the  assumed  name  of  the  remote system for
              authentication purposes to name.

       refuse-chap
              With this option, pppd will not agree to  authenti-
              cate itself to the peer using CHAP.

       refuse-pap
              With  this option, pppd will not agree to authenti-
              cate itself to the peer using PAP.

       require-chap
              Require the peer to authenticate itself using  CHAP
              [Challenge   Handshake   Authentication   Protocol]
              authentication.

       require-pap
              Require the peer to authenticate itself  using  PAP
              [Password  Authentication Protocol] authentication.

       silent With this option, pppd will not transmit LCP  pack-
              ets  to  initiate  a  connection  until a valid LCP
              packet is received from the peer (as for the  `pas-
              sive' option with ancient versions of pppd).



                                                               13





PPPD(8)                                                   PPPD(8)


       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 name
              option).

       user name
              Sets the name used  for  authenticating  the  local
              system to the peer to name.

       vj-max-slots n
              Sets  the  number of connection slots to be used by
              the Van  Jacobson  TCP/IP  header  compression  and
              decompression  code  to  n, which must be between 2
              and 16 (inclusive).

       welcome script
              Run the executable or shell  command  specified  by
              script before initiating PPP negotiation, after the
              connect script (if any) has completed.  This option
              is privileged if the noauth option is used.

       xonxoff
              Use  software flow control (i.e., XON/XOFF) to con-
              trol the flow of data on the serial port.

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.ttyname  (in  that  order)
       before  processing  the  options on the command line.  (In
       fact, the command-line options are  scanned  to  find  the
       terminal  name  before  the options.ttyname file is read.)
       In forming the name of the options.ttyname file, the  ini-
       tial  /dev/  is  removed  from  the terminal name, and any
       remaining / characters are replaced with dots.

       An options file is parsed into a series of  words,  delim-
       ited  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 file or call options within
       an options file.

SECURITY
       pppd provides system administrators with sufficient access
       control  that  PPP  access to a server machine can be pro-
       vided to legitimate users without fear of compromising the
       security  of  the  server or the network it's on.  In part
       this is provided by the /etc/ppp/options file,  where  the
       administrator  can  place  options to restrict the ways in
       which pppd can be used, and in part by the  PAP  and  CHAP
       secrets  files,  where  the administrator can restrict the



                                                               14





PPPD(8)                                                   PPPD(8)


       set of IP addresses which individual users may use.

       The normal way that pppd should be set up is to  have  the
       auth  option  in  the  /etc/ppp/options  file.   (This may
       become the default in later releases.)  If users  wish  to
       use  pppd  to  dial  out  to  a  peer which will refuse to
       authenticate  itself  (such   as   an   internet   service
       provider),  the  system  administrator  should  create  an
       options file under /etc/ppp/peers  containing  the  noauth
       option,  the  name of the serial port to use, and the con-
       nect option (if  required),  plus  any  other  appropriate
       options.   In  this  way, pppd can be set up to allow non-
       privileged users to make unauthenticated connections  only
       to trusted peers.

       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 file option.  Privi-
       leged options may be used in /etc/ppp/options file  or  in
       an  options  file  read using the call option.  If pppd is
       being run by the root user, privileged options can be used
       without restriction.

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  authentica-
       tion  correspond  to  the internet hostnames of the peers,
       but this is not essential.

       At present, pppd supports  two  authentication  protocols:
       the  Password  Authentication Protocol (PAP) and the Chal-
       lenge  Handshake  Authentication  Protocol  (CHAP).    PAP
       involves the client sending its name and a cleartext pass-
       word 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.

       The PPP protocol, being symmetrical, allows both peers  to



                                                               15





PPPD(8)                                                   PPPD(8)


       require  the  other to authenticate itself.  In that case,
       two separate and independent authentication exchanges will
       occur.   The two exchanges could use different authentica-
       tion protocols, and in principle, different names could be
       used in the two exchanges.

       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.

       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.

       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 authen-
       ticate 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.

       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  spe-
       cial characters quoted or escaped.  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 not acceptable.  An address may be followed by
       "/" and a number n, to indicate a whole subnet, i.e.,  all
       addresses  which  have the same value in the most signifi-
       cant n bits.  Note that case is significant in the  client
       and server names and in the secret.

       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
       authenticating other hosts, plus secrets which we use  for
       authenticating  ourselves to others.  When pppd is authen-
       ticating the  peer  (checking  the  peer's  identity),  it



                                                               16





PPPD(8)                                                   PPPD(8)


       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  domain  option  is  used.
       This  default  can  be  overridden  with  the name option,
       except when the usehostname option is used.

       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 user option.  If
       this option is not used, the name defaults to the name  of
       the  local system, determined as described in the previous
       paragraph.  Then 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 remotename option.  Otherwise, if
       the remote IP address was specified by a name (rather than
       in  numeric  form),  that  name will be used as the peer's
       name.  Failing that, pppd will use the null string as  the
       peer's name.

       When  authenticating the peer with PAP, the supplied pass-
       word is first compared with the secret  from  the  secrets
       file.  If the password doesn't match the secret, the pass-
       word 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
       papcrypt option is given, the first (unencrypted) compari-
       son is omitted, for better security.

       Furthermore, if the login option was specified, the  user-
       name  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 cer-
       tain users, and to restrict the set of IP  addresses  that
       each  user  can  use.   Typically,  when  using  the login
       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.

       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.

       In some cases it is desirable to allow  some  hosts  which



                                                               17





PPPD(8)                                                   PPPD(8)


       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 authenti-
       cate 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 rout-
       ing  tables  and/or  ARP  (Address  Resolution   Protocol)
       tables.   In  most  cases the defaultroute and/or proxyarp
       options are sufficient for this, but in some cases further
       intervention  is  required.  The /etc/ppp/ip-up script can
       be used for this.

       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  defaultroute  option  causes  pppd  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 exam-
       ple on a server machine connected to a LAN,  in  order  to
       allow  other  hosts  to  communicate with the remote host.
       The proxyarp option causes pppd  to  look  for  a  network
       interface on the same subnet as the remote host (an inter-
       face 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.

       When the demand 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  assign-
       ment),  pppd  has  to change the interface IP addresses to
       the negotiated addresses.  This may disrupt existing  con-
       nections,  and  the use of demand dialling with peers that
       do dynamic IP address assignment is not recommended.

EXAMPLES
       The following examples assume  that  the  /etc/ppp/options



                                                               18





PPPD(8)                                                   PPPD(8)


       file   contains   the  auth  option  (as  in  the  default
       /etc/ppp/options file in the ppp distribution).

       Probably the most common use of pppd is to dial out to  an
       ISP.  This can be done with a command such as

              pppd call isp

       where  the /etc/ppp/peers/isp file is set up by the system
       administrator to contain something like this:

              ttyS0 19200 crtscts
              connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp'
              noauth

       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:

              ABORT "NO CARRIER"
              ABORT "NO DIALTONE"
              ABORT "ERROR"
              ABORT "NO ANSWER"
              ABORT "BUSY"
              ABORT "Username/Password Incorrect"
              "" "at"
              OK "at&d0&c1"
              OK "atdt2468135"
              "name:" "^Umyuserid"
              "word:" "\qmypassword"
              "ispts" "\q^Uppp"
              "~-^Uppp-~"

       See the chat(8) man page for details of chat scripts.

       Pppd can also be used to provide a dial-in ppp service for
       users.  If the users already have login accounts, the sim-
       plest  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

              pppd proxyarp

       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  imple-
       mentation  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:



                                                               19





PPPD(8)                                                   PPPD(8)


              joespc    server    "joe's secret" joespc.my.net

       Alternatively, you can create a username called (for exam-
       ple)  "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.

       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 use-
       ful to escape XON  (^Q)  and  XOFF  (^S),  using  asyncmap
       a0000.  If the path includes a telnet, you probably should
       escape ^]  as  well  (asyncmap  200a0000).   If  the  path
       includes  an  rlogin,  you  will need to use the escape ff
       option on the end which  is  running  the  rlogin  client,
       since  many  rlogin  implementations  are not transparent;
       they will remove the sequence  [0xff,  0xff,  0x73,  0x73,
       followed by any 8 bytes] from the stream.

DIAGNOSTICS
       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 mes-
       sages to the desired output device or file.

       The debug option causes the contents of all control  pack-
       ets  sent or received to be logged, that is, all LCP, PAP,
       CHAP or IPCP packets.  This can be useful if the PPP nego-
       tiation  does  not succeed or if authentication fails.  If
       debugging is enabled at compile  time,  the  debug  option
       also causes other debugging messages to be logged.

       Debugging  can  also  be  enabled or disabled by sending a
       SIGUSR1 signal to the pppd process.  This signal acts as a
       toggle.

SCRIPTS
       Pppd  invokes  scripts at various stages in its processing
       which can be used to perform site-specific ancillary  pro-
       cessing.   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 vari-
       ables that pppd sets are:




                                                               20





PPPD(8)                                                   PPPD(8)


       DEVICE The name of the serial tty device being used.

       IFNAME The name of the network interface being used.

       IPLOCAL
              The IP address for the local end of the link.  This
              is only set when IPCP has come up.

       IPREMOTE
              The  IP  address  for  the  remote end of the link.
              This is only set when IPCP has come up.

       PEERNAME
              The authenticated name of the peer.  This  is  only
              set if the peer authenticates itself.

       SPEED  The baud rate of the tty device.

       UID    The real user ID of the user who invoked pppd.

       Pppd  invokes the following scripts, if they exist.  It is
       not an error if they don't exist.

       /etc/ppp/auth-up
              A program or script which  is  executed  after  the
              remote  system  successfully  authenticates itself.
              It is executed with the parameters

              interface-name peer-name user-name tty-device speed

              Note  that  this script is not executed if the peer
              doesn't authenticate itself, for example  when  the
              noauth option is used.

       /etc/ppp/auth-down
              A program or script which is executed when the link
              goes down, if /etc/ppp/auth-up was previously  exe-
              cuted.   It is executed in the same manner with the
              same parameters as /etc/ppp/auth-up.

       /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

              interface-name  tty-device  speed  local-IP-address
              remote-IP-address ipparam

       /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



                                                               21





PPPD(8)                                                   PPPD(8)


              invoked in the same manner and with the same param-
              eters as the ip-up script.

       /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

              interface-name  tty-device   speed   network-number
              local-IPX-node-address      remote-IPX-node-address
              local-IPX-routing-protocol  remote-IPX-routing-pro-
              tocol  local-IPX-router-name remote-IPX-router-name
              ipparam pppd-pid

              The local-IPX-routing-protocol and remote-IPX-rout-
              ing-protocol field may be one of the following:

              NONE      to indicate that there is no routing pro-
              tocol
              RIP       to indicate that RIP/SAP should be used
              NLSP      to indicate that Novell  NLSP  should  be
              used
              RIP  NLSP   to  indicate that both RIP/SAP and NLSP
              should be used

       /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 param-
              eters as the ipx-up script.

FILES
       /var/run/pppn.pid (BSD or Linux), /etc/ppp/pppn.pid (oth-
       ers)
              Process-ID for pppd process on ppp  interface  unit
              n.

       /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.

       /etc/ppp/chap-secrets
              Names, secrets and IP addresses for CHAP  authenti-
              cation.   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 warn-
              ing if this is not the case.





                                                               22





PPPD(8)                                                   PPPD(8)


       /etc/ppp/options
              System default options for pppd, read  before  user
              default options or command-line options.

       ~/.ppprc
              User      default      options,     read     before
              /etc/ppp/options.ttyname.

       /etc/ppp/options.ttyname
              System default options for the  serial  port  being
              used,  read after ~/.ppprc.  In forming the ttyname
              part of this filename, an initial /dev/ is stripped
              from the port name (if present), and any slashes in
              the remaining part are converted to dots.

       /etc/ppp/peers
              A directory containing options files which may con-
              tain  privileged  options, even if pppd was invoked
              by a user other than root.  The system  administra-
              tor  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.

SEE ALSO
       RFC1144
              Jacobson, V.  Compressing TCP/IP headers  for  low-
              speed serial links.  February 1990.

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

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

       RFC1334
              Lloyd, B.; Simpson, W.A.  PPP authentication proto-
              cols.  October 1992.

       RFC1661
              Simpson, W.A.  The Point-to-Point  Protocol  (PPP).
              July 1994.

       RFC1662
              Simpson,  W.A.   PPP  in  HDLC-like  Framing.  July
              1994.

NOTES
       The following signals have the specified effect when  sent
       to pppd.





                                                               23





PPPD(8)                                                   PPPD(8)


       SIGINT, SIGTERM
              These  signals cause pppd to terminate the link (by
              closing LCP), restore the serial  device  settings,
              and exit.

       SIGHUP This  signal  causes  pppd  to  terminate the link,
              restore the serial device settings, and  close  the
              serial device.  If the persist or demand 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  immedi-
              ately.

       SIGUSR1
              This  signal toggles the state of the debug option.

       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  decom-
              pression error.  (Fatal decompression errors gener-
              ally indicate a bug in  one  or  other  implementa-
              tion.)


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.


























                                                               24


