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.  A value for this option from  a
              privileged  source  cannot  be overridden by a non-
              privileged user.

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

       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.

              allowing network packets to be  sent  or  received.
              This  option  is  the  default  if the system has a
              default route.  If  neither  this  option  nor  the
              noauth  option  is  specified, pppd will only allow
              the peer to use IP addresses to  which  the  system
              does not already have a route.

       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.  A value
              for this option from a privileged source cannot  be
              overridden by a non-privileged user.

       crtscts
              Use hardware flow control (i.e. RTS/CTS) to control
              the flow of data on the serial  port.   If  neither
              the  crtscts,  the  nocrtscts,  the cdtrcts nor the
              nocdtrcts option is given, the hardware  flow  con­
              trol setting for the serial port is left unchanged.
              Some serial ports (such as Macintosh serial  ports)
              lack  a true RTS output. Such serial ports use this
              mode to implement unidirectional flow control.  The
              serial   port   will   suspend   transmission  when
              requested by the modem (via CTS) but will be unable
              to  request the modem stop sending to the computer.
              This mode retains the ability to use DTR as a modem
              control line.

       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.

       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.

              cannot be overridden by a non-privileged user.

       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.

       init script
              Run  the  executable  or shell command specified by
              script to initialize the serial line.  This  script
              would  typically use the chat(8) program to config­
              ure the modem to enable auto answer.  A  value  for
              this  option  from  a  privileged  source cannot be
              overridden by a non-privileged user.

       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).  (Note that for IPv6 MRU must be at
              least 1280)

       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.   (Note
              that for IPv6 MTU must be at least 1280)

       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



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.

       ipv6 <local_interface_identifier>,<remote_interface_iden­
              tifier>
              Set the local and/or remote 64-bit interface  iden­
              tifier.  Either  one may be omitted. The identifier
              must be specified in  standard  ascii  notation  of
              IPv6  addresses  (e.g. ::dead:beef). If the ipv6cp-
              use-ipaddr option is given, the local identifier is
              the  local  IPv4  address  (see above).  On systems
              which supports a  unique  persistent  id,  such  as
              EUI-48  derived  from  the  Ethernet  MAC  address,
              ipv6cp-use-persistent option can be used to replace
              the  ipv6  <local>,<remote>  option.  Otherwise the
              identifier is randomized.

       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 cur­
              rently only available under NetBSD, and  then  only
              if  both  the  kernel  and  pppd were compiled with
              PPP_FILTER defined.

              Allow peers to use the given IP address  or  subnet
              without  authenticating  themselves.  The parameter
              is parsed as  for  each  element  of  the  list  of
              allowed  IP addresses in the secrets files (see the
              AUTHENTICATION section below).

       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.

       cdtrcts
              Use  a  non-standard  hardware  flow  control (i.e.
              DTR/CTS) to control the flow of data on the  serial
              port.   If  neither the crtscts, the nocrtscts, the
              cdtrcts nor the  nocdtrcts  option  is  given,  the
              hardware  flow  control setting for the serial port
              is left unchanged.  Some serial ports (such as Mac­
              intosh  serial  ports) lack a true RTS output. Such
              serial ports use this mode to  implement  true  bi-
              directional  flow  control.  The  sacrifice is that
              this flow control mode does not permit using DTR as
              a modem control line.

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

       connect-delay n
              Wait for up n milliseconds after the connect script
              finishes  for a valid PPP packet from the peer.  At
              the end of this time, or when a valid PPP packet is
              received from the peer, pppd will commence negotia­
              tion by sending its first LCP packet.  The  default
              value  is  1000  (1 second).  This wait period only
              applies if the connect or pty option is used.

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

              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.

       dryrun With the dryrun option, pppd will print out all the
              option  values  which  have been set and then exit,
              after parsing the command line  and  options  files
              and checking the option values, but before initiat­
              ing the link.  The  option  values  are  logged  at
              level  info,  and  also  printed to standard output
              unless the device on standard output is the  device
              that  pppd  would  be using to communicate with the
              peer.

       dump   With the dump option, pppd will print out  all  the
              option  values which have been set.  This option is
              like the dryrun option except that pppd proceeds as
              normal rather than exiting.

       endpoint <epdisc>
              Sets  the  endpoint discriminator sent by the local
              machine to the peer during multilink negotiation to
              <epdisc>.  The default is to use the MAC address of
              the first ethernet interface on the system, if any,
              otherwise  the  IPv4  address  corresponding to the
              hostname, if any, provided it is not in the  multi­
              cast  or locally-assigned IP address ranges, or the
              localhost address.  The endpoint discriminator  can
              be the string null or of the form type:value, where
              type is a decimal number  or  one  of  the  strings
              local,  IP,  MAC, magic, or phone.  The value is an
              IP address in dotted-decimal notation  for  the  IP
              type,  or  a  string of bytes in hexadecimal, sepa­
              rated by periods or colons  for  the  other  types.
              For the MAC type, the value may also be the name of
              an ethernet or  similar  network  interface.   This
              option is currently only available under Linux.

       hide-password
              When  logging  the  contents  of  PAP packets, this
              option causes pppd to exclude the  password  string
              from the log.  This is the default.

       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

              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.

       ipv6cp-max-configure n
              Set the maximum number of IPv6CP  configure-request
              transmissions to n (default 10).

       ipv6cp-max-failure n
              Set  the  maximum  number  of IPv6CP configure-NAKs
              returned before starting to send  configure-Rejects
              instead to n (default 10).

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

       ipv6cp-restart n
              Set the  IPv6CP  restart  interval  (retransmission
              timeout) to n seconds (default 3).

       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.

       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.

              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.

       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 values depend on the specific
              kernel  driver,  but  in  general a value of 1 will
              enable general kernel debug messages.   (Note  that
              these  messages  are usually only useful for debug­
              ging the kernel  driver  itself.)   For  the  Linux
              2.2.x  kernel driver, the value is a sum of bits: 1
              to enable general debug messages, 2 to request that
              the  contents of received packets be printed, and 4
              to request that the contents of transmitted packets
              be  printed.   On most systems, messages printed by
              the kernel are logged by syslog(1)  to  a  file  as
              directed   in  the  /etc/syslog.conf  configuration
              file.

       ktune  Enables pppd to alter kernel settings as  appropri­
              ate.   Under  Linux, pppd will enable IP forwarding
              (i.e. set /proc/sys/net/ipv4/ip_forward  to  1)  if
              the  proxyarp  option  is used, and will enable the
              dynamic    IP    address    option    (i.e.     set
              /proc/sys/net/ipv4/ip_dynaddr  to 1) in demand mode
              if the local address changes.

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

       linkname name
              Sets  the  logical  name of the link to name.  Pppd
              will create a file named ppp-name.pid  in  /var/run
              (or  /etc/ppp  on some systems) containing its pro­
              cess ID.  This can be useful in  determining  which
              instance  of  pppd is responsible for the link to a
              given peer system.  This is a privileged option.

       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.

       logfd n
              Send log messages to file descriptor n.  Pppd  will
              send  log  messages  to  at  most  one file or file

              syslog),  so this option and the logfile option are
              mutually exclusive.  The default  is  for  pppd  to
              send  log  messages  to stdout (file descriptor 1),
              unless the serial port is already open on stdout.

       logfile filename
              Append log messages to the file filename  (as  well
              as  sending  the log messages to syslog).  The file
              is opened with  the  privileges  of  the  user  who
              invoked pppd, in append mode.

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

       maxfail n
              Terminate  after  n  consecutive  failed connection
              attempts.  A  value  of  0  means  no  limit.   The
              default value is 10.

       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.

       mp     Enables  the use of PPP multilink; this is an alias
              for the `multilink' option.  This  option  is  cur­
              rently only available under Linux.

       mpshortseq
              Enables  the use of short (12-bit) sequence numbers
              in multilink headers, as opposed to 24-bit sequence
              numbers.   This  option  is  only  available  under
              Linux, and only has  any  effect  if  multilink  is
              enabled (see the multilink option).

       mrru n Sets  the  Maximum Reconstructed Receive Unit to n.
              The MRRU is the maximum size for a received  packet
              on  a multilink bundle, and is analogous to the MRU
              for the individual links.  This option is currently
              only available under Linux, and only has any effect


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

       multilink
              Enables the use of the PPP multilink protocol.   If
              the  peer  also  supports multilink, then this link
              can become part of a bundle between the local  sys­
              tem  and  the peer.  If there is an existing bundle
              to the peer, pppd will join this link to that  bun­
              dle,  otherwise pppd will create a new bundle.  See
              the MULTILINK section below.  This option  is  cur­
              rently only available under Linux.

       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.   (Note:  on
              some    platforms,    pppd    will    always    use

              only  appropriate value for a point-to-point inter­
              face.)

       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.

       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.

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

       nocdtrcts
              This  option  is a synonym for nocrtscts. Either of
              these options will disable both forms  of  hardware
              flow control.

       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.

       noendpoint
              Disables  pppd from sending an endpoint discrimina­
              tor to the peer or accepting one from the peer (see
              the  MULTILINK  section below).  This option should


       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.

       noipv6 Disable  IPv6CP negotiation and IPv6 communication.
              This option should only be required if the peer  is
              buggy  and  gets confused by requests from pppd for
              IPv6CP negotiation.

       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.

       noktune
              Opposite  of  the  ktune option; disables pppd from
              changing system settings.

       nolog  Do not send log messages to a file or file descrip­
              tor.   This  option  cancels  the logfd and logfile
              options.

       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.

       nomp   Disables  the use of PPP multilink.  This option is
              currently only available under Linux.

       nompshortseq
              Disables the use of short (12-bit) sequence numbers
              in  the  PPP multilink protocol, forcing the use of
              24-bit sequence numbers.  This option is  currently
              only available under Linux, and only has any effect
              if multilink is enabled.

       nomultilink
              Disables the use of PPP multilink.  This option  is
              currently only available under Linux.

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

       nopersist
              Exit once a connection has  been  made  and  termi­
              nated.   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.

       notty  Normally, pppd requires a  terminal  device.   With
              this option, pppd will allocate itself a pseudo-tty
              master/slave pair and use the slave as its terminal
              device.  Pppd will create a child process to act as
              a `character shunt' to transfer characters  between
              the  pseudo-tty  master  and its standard input and
              output.  Thus pppd will transmit characters on  its
              standard output and receive characters on its stan­
              dard input even if they are not  terminal  devices.
              This  option increases the latency and CPU overhead
              of transferring data over the ppp interface as  all
              of  the  characters  sent  and  received  must flow
              through the character shunt process.   An  explicit
              device  name  may  not  be  given if this option is
              used.

       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.

              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 inappro­
              priate 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  outgoing
              packets using the inbound and outbound  qualifiers.
              This  option  is  currently  only  available  under
              NetBSD, 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.

       plugin filename
              Load the shared library object file filename  as  a
              plugin.  This is a privileged option.

       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.

       privgroup group-name
              Allows  members  of  group group-name to use privi­
              leged options.  This is a privileged  option.   Use
              of this option requires care as there is no guaran­
              tee that members of group-name cannot use  pppd  to

              putting the members of group-name in  the  kmem  or
              disk group.

       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.

       pty script
              Specifies  that the command script is to be used to
              communicate rather than a specific terminal device.
              Pppd will allocate itself a pseudo-tty master/slave
              pair and use the slave as its terminal device.  The
              script  will  be  run  in  a child process with the
              pseudo-tty master as its standard input and output.
              An  explicit  device  name may not be given if this
              option is used.  (Note: if  the  record  option  is
              used  in  conjuction with the pty option, the child
              process will have pipes on its standard  input  and
              output.)

       receive-all
              With  this  option,  pppd  will  accept all control
              characters from the peer, including those marked in
              the  receive  asyncmap.   Without this option, pppd
              will  discard  those  characters  as  specified  in
              RFC1662.   This option should only be needed if the
              peer is buggy.

       record filename
              Specifies that pppd should  record  all  characters
              sent  and  received to a file named filename.  This
              file is opened in append  mode,  using  the  user's
              user-ID  and  permissions.   This  option is imple­
              mented using a pseudo-tty and a process to transfer
              characters  between  the  pseudo-tty  and  the real
              serial device, so it will increase the latency  and
              CPU  overhead  of  transferring  data  over the ppp
              interface.  The characters are stored in  a  tagged
              format  with  timestamps, which can be displayed in
              readable form using the pppdump(8) program.

       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.

              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.

       show-password
              When  logging  the  contents  of  PAP packets, this
              option causes pppd to show the password  string  in
              the log message.

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

       sync   Use synchronous HDLC  serial  encoding  instead  of
              asynchronous.   The  device  used by pppd with this
              option must have sync support.  Currently  supports
              Microgate SyncLink adapters under Linux and FreeBSD
              2.2.8 and later.

       updetach
              With this option, pppd will detach  from  its  con­
              trolling  terminal  once it has successfully estab­
              lished the ppp connection (to the point  where  the
              first network control protocol, usually the IP con­
              trol protocol, has come up).

       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).   This option is not normally needed since
              the name option is privileged.

       usepeerdns
              Ask the peer for up to 2 DNS server addresses.  The
              addresses  supplied by the peer (if any) are passed
              to the /etc/ppp/ip-up  script  in  the  environment
              variables  DNS1  and  DNS2.  In addition, pppd will
              create an /etc/ppp/resolv.conf file containing  one
              or  two  nameserver lines with the address(es) sup­
              plied by the peer.

       user name
              Sets the name used  for  authenticating  the  local


       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.  A value for
              this  option  from  a  privileged  source cannot be
              overridden by a non-privileged user.

       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.  This  con­
       trol   is   provided  through  restrictions  on  which  IP
       addresses the peer may use,  based  on  its  authenticated
       identity  (if  any),  and  through  restrictions  on which
       options a non-privileged user may use.  Several of  pppd's
       options  are  privileged, in particular those which permit
       potentially insecure  configurations;  these  options  are
       only  accepted in files which are under the control of the
       system administrator, or if pppd is being run by root.

       The default behaviour of pppd is to allow  an  unauthenti­
       cated  peer  to  use a given IP address only if the system

       example, a system with a permanent connection to the wider
       internet will normally have a default route, and thus  all
       peers will have to authenticate themselves in order to set
       up a connection.  On such a system, the auth option is the
       default.   On  the other hand, a system where the PPP link
       is the only connection to the internet will  not  normally
       have  a  default  route,  so  the peer will be able to use
       almost any IP address without authenticating itself.

       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.

       When opening the device, pppd  uses  either  the  invoking
       user's  user ID or the root UID (that is, 0), depending on
       whether the device name was specified by the user  or  the
       system  administrator.   If  the  device name comes from a
       privileged source, that is, /etc/ppp/options or an options
       file read using the call option, pppd uses full root priv­
       ileges when opening the  device.   Thus,  by  creating  an
       appropriate file under /etc/ppp/peers, the system adminis­
       trator can allow users to establish a ppp connection via a
       device  which  they  would not normally have permission to
       access.  Otherwise pppd uses the invoking user's real  UID
       when opening the device.


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,

       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
       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.  Note that case is sig­
       nificant 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.

       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

       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  significant  n bits.  In this form, the address
       may be followed by a plus sign ("+") to indicate that  one
       address  from  the  subnet is authorized, based on the ppp
       network interface unit number in use.  In this  case,  the
       host  part  of  the address will be set to the unit number
       plus one.

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

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


       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.


MULTILINK

       Multilink  PPP  provides  the capability to combine two or
       more PPP links between a pair of machines  into  a  single
       `bundle', which appears as a single virtual PPP link which
       has the combined bandwidth of the individual links.   Cur­
       rently, multilink PPP is only supported under Linux.

       Pppd  detects that the link it is controlling is connected
       to the same peer as another link using the peer's endpoint
       discriminator  and  the authenticated identity of the peer
       (if it authenticates itself).  The endpoint  discriminator
       is  a  block  of  data  which is hopefully unique for each
       peer.  Several  types  of  data  can  be  used,  including
       locally-assigned  strings  of  bytes,  IP  addresses,  MAC
       addresses, randomly strings of bytes, or E-164 phone  num­
       bers.  The endpoint discriminator sent to the peer by pppd
       can be set using the endpoint option.

       In circumstances the peer may send no endpoint discrimina­
       tor  or  a  non-unique  value.  The optional bundle option
       adds an extra string which is added to the peer's endpoint
       discriminator  and authenticated identity when matching up
       links to be joined  together  in  a  bundle.   The  bundle
       option can also be used to allow the establishment of mul­
       tiple bundles between the local system and the peer.  Pppd
       uses  a  TDB  database  in  /var/run/pppd.tdb  to match up
       links.

       Assuming that multilink is enabled and the peer is willing
       to negotiate multilink, then when pppd is invoked to bring
       up the first link to the peer,  it  will  detect  that  no
       other  link is connected to the peer and create a new bun­
       dle, that is, another ppp network  interface  unit.   When
       another  pppd  is  invoked to bring up another link to the
       peer, it will detect the existing bundle and join its link
       to it.  Currently, if the first pppd terminates (for exam­
       ple, because of a hangup or a received signal) the  bundle
       is destroyed.


EXAMPLES

       The  following  examples  assume that the /etc/ppp/options
       file  contains  the  auth  option  (as  in   the   default


       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:


       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.


EXIT STATUS

       The exit status of pppd is set  to  indicate  whether  any
       error  was detected, or the reason for the link being ter­
       minated.  The values used are:

       0      Pppd has detached, or otherwise the connection  was
              successfully  established  and  terminated  at  the
              peer's request.

       1      An immediately fatal error of some  kind  occurred,
              such  as  an essential system call failing, or run­
              ning out of virtual memory.

       2      An error was detected  in  processing  the  options
              given, such as two mutually exclusive options being
              used.

              not root.

       4      The  kernel  does not support PPP, for example, the
              PPP kernel driver is  not  included  or  cannot  be
              loaded.

       5      Pppd  terminated  because  it  was  sent  a SIGINT,
              SIGTERM or SIGHUP signal.

       6      The serial port could not be locked.

       7      The serial port could not be opened.

       8      The connect script failed (returned a non-zero exit
              status).

       9      The  command  specified  as the argument to the pty
              option could not be run.

       10     The PPP negotiation  failed,  that  is,  it  didn't
              reach the point where at least one network protocol
              (e.g. IP) was running.

       11     The peer system failed (or refused) to authenticate
              itself.

       12     The  link  was  established successfully and termi­
              nated because it was idle.

       13     The link was established  successfully  and  termi­
              nated because the connect time limit was reached.

       14     Callback was negotiated and an incoming call should
              arrive shortly.

       15     The link was terminated because  the  peer  is  not
              responding to echo requests.

       16     The link was terminated by the modem hanging up.

       17     The  PPP negotiation failed because serial loopback
              was detected.

       18     The init script failed (returned  a  non-zero  exit
              status).

       19     We failed to authenticate ourselves to the peer.


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

       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:

       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.

       ORIG_UID
              The real user-id of the user who invoked pppd.

       PPPLOGNAME
              The username of the real user-id that invoked pppd.
              This is always set.

       For the ip-down and auth-down scripts, pppd also sets  the
       following variables giving statistics for the connection:

       CONNECT_TIME
              The number of seconds from when the PPP negotiation
              started until the connection was terminated.

       BYTES_SENT
              The number of bytes  sent  (at  the  level  of  the
              serial port) during the connection.

       BYTES_RCVD
              The  number  of bytes received (at the level of the
              serial port) during the connection.

       LINKNAME
              The logical name of the link, set with the linkname
              option.

       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
              invoked in the same manner and with the same param­
              eters as the ip-up script.

       /etc/ppp/ipv6-up
              Like  /etc/ppp/ip-up,  except  that  it is executed
              when the link is available for sending and  receiv­
              ing  IPv6  packets. It is executed with the parame­
              ters

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

       /etc/ppp/ipv6-down
              Similar  to  /etc/ppp/ip-down,  but  it is executed
              when IPv6 packets can no longer be  transmitted  on
              the  link.  It is executed with the same parameters
              as the ipv6-up script.

       /etc/ppp/ipx-up
              A program or script which is executed when the link

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

       /var/run/ppp-name.pid (BSD or Linux),
              /etc/ppp/ppp-name.pid (oth­ ers)
              Process-ID for pppd process for logical  link  name
              (see the linkname option).

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

              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.

       RFC2472
              Haskin, D.  IP Version 6 over PPP December 1998.


NOTES

       The following signals have the specified effect when  sent


       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.


Man(1) output converted with man2html