*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> pppd (8)              
Title
Content
Arch
Section
 

PPPD(8)

Contents


NAME    [Toc]    [Back]

     pppd - Point-to-Point Protocol daemon

SYNOPSIS    [Toc]    [Back]

     pppd [tty_name] [speed] [options]

DESCRIPTION    [Toc]    [Back]

     PPP is the protocol used  for  establishing  internet  links
over dial-up
     modems,  DSL  connections, and many other types of point-topoint links.
     The pppd daemon works together with the kernel ppp(4) driver
to establish
     and  maintain  a  PPP  link  with another system (called the
peer) and to negotiate
 Internet Protocol (IP) addresses for each end of the
link.  pppd
     can  also authenticate the peer and/or supply authentication
information
     to the peer.  PPP can be used with other  network  protocols
besides IP,
     but such use is becoming increasingly rare.

FREQUENTLY USED OPTIONS    [Toc]    [Back]

     tty_name
             Use  the  serial  port called ttyname to communicate
with the peer.
             The string ``/dev/'' is prepended to ttyname to form
the name of
             the  device to open.  If no device name is given, or
if the name
             of the terminal connected 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    An  option that is a decimal number is taken as the
desired baud
             rate for the serial  device.   On  systems  such  as
4.4BSD and OpenBSD,
  any  speed  can  be  specified.   Other systems
(e.g., Linux,
             SunOS) only support the commonly used baud-rates.

     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 packets being sent
or received
             regularly over the link (for example, routing information packets)
 which would otherwise prevent the link from ever appearing
             to  be idle.  The filter-expression syntax is as described for
             tcpdump(8), 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 currently only available  under OpenBSD,
             and  then only if both the kernel and pppd were compiled with
             PPP_FILTER defined.

     asyncmap map
             This  option  sets  the  Async-Control-Character-Map
(ACCM) for this
             end  of the link.  The ACCM is a set of 32 bits, one
for each of
             the ASCII control characters with values from  0  to
31, where a 1
             bit indicates that the corresponding control character should not
             be used in PPP packets sent to this system.  The map
is encoded
             as a hexadecimal number (without a leading 0x) where
the least
             significant bit (00000001)  represents  character  0
and the most
             significant  bit (80000000) represents character 31.
pppd will
             ask the peer to send these characters  as  a  2-byte
escape sequence.
  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
             Usually there is something which needs to be done to
prepare the
             link before the PPP protocol can be started; for instance, with a
             dial-up modem, commands need to be sent to the modem
to dial the
             appropriate  phone number.  This option specifies an
command for
             pppd to execute (by passing it to  a  shell)  before
attempting to
             start PPP negotiation.  The chat(8) program is often
useful here,
             as it provides a way to send arbitrary strings to  a
modem and respond
 to received characters.  This option is privileged if the
             noauth option is used.

     crtscts
             Specifies that pppd should set the  serial  port  to
use hardware
             flow  control  using  the RTS and CTS signals in the
RS-232 interface.
  If neither 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 negotiation 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
             Execute the command specified by script, by  passing
it to a
             shell,  after  pppd  has  terminated the link.  This
command could,
             for example, issue commands to the modem to cause it
to hang up
             if  hardware  modem  control 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
             characters  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
value of n
             must  be between 128 and 16384; the default is 1500.
A value of
             296 works well on very  slow  links  (40  bytes  for
TCP/IP header +
             256  bytes  of data).  Note that for the IPv6 protocol, the 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 networking code send data packets of
no more than
             n  bytes  through  the  PPP network interface.  Note
that for the
             IPv6 protocol, the 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 without
             this option.

OPTIONS    [Toc]    [Back]

     [local_IP_address]:[remote_IP_address]
             Set the local and/or remote interface IP  addresses.
Either one
             may  be  omitted.  The IP addresses can be specified
with a host
             name   or   in   decimal   dot    notation    (e.g.,
150.234.56.78).  The default
 local address is the (first) IP address of the
system (unless
 the 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 maximum 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.  nobsdcomp or bsdcomp 0 disables 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  transmissions to n (default
 10).

     chap-restart n
             Set  the CHAP restart interval (retransmission timeout 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
             syslogd(8)  with  facility  daemon  and level debug.
This information
 can  be  directed  to  a  file  by  setting  up
/etc/syslog.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 8 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  nodeflate  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
             initially  configure the interface and enable it for
IP traffic
             without connecting to the  peer.   When  traffic  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 holdoff options are also useful in conjunction with
             the demand option.

     domain d
             Append the domain name d to the local host name  for
authentication
  purposes.   For example, if gethostname(3) 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.

     holdoff n
             Specifies how many seconds to wait before  re-initiating 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 activity 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  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  timeout) 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 support.

     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 specified as the only instance of
ipx-routing.
             The values 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 ipxnode
 option.  If a node 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-network
             Accept  the peer's NAK for the network number specified in the
             ipx-network option.  If a network number was  specified, and nonzero,
  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 configure request
             frame.  If a node number was specified for the  peer
and this option
  was  not specified, 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  number 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 syslogd(8) 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 echoreply.
   If  this  happens,  pppd will terminate the
connection.  Use
             of this option requires a  non-zero  value  for  the
lcp-echo-
             interval  parameter.  This option can be used to enable pppd to
             terminate after the  physical  connection  has  been
broken (e.g.,
             the  modem has hung up) in situations where no hardware modem control
 lines are available.

     lcp-echo-interval n
             If this option is given, pppd will send an LCP echorequest 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  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  timeout) to n seconds
 (default 3).

     local    Don't  use  the modem control lines.  With this option, pppd will
             ignore the state of the CD (Carrier  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 system 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  (Carrier  Detect)
signal from the
             modem  during  the  chat script.  If you are using a
cua(4) device
             (as opposed to a tty(4) 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
             specifies  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 supply one or
two WINS (Windows
 Internet Name Services) 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-topoint
 network interfaces in the system which are  on
the same network.
   (Note:  on  some platforms, pppd will always
use
             255.255.255.255 for the netmask, if that is the only
appropriate
             value for a point-to-point interface.)

     noaccomp
             Disable  Address/Control  compression in both directions (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) negotiation.  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  option  is
given, the
             hardware flow control setting for the serial port is
left unchanged.


     nodefaultroute
             Disable the defaultroute option.  The system  administrator 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.  Without
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 was
             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 negotiation.

     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 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 administrator 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 compression
in both the
             transmit and the receive direction.

     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 identity of the peer are
encrypted, and
             thus pppd should not accept a password which, before
encryption,
             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 timeout) 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 apply to  data  packets
being sent or
             received  to  determine  which packets 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(8)) using up link bandwidth, or to provide
a basic
             firewall  capability.   The filter-expression syntax
is as described
 for tcpdump(8), 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.  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  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 compress 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  Resolution 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  authenticate itself to
             the peer using CHAP.

     refuse-pap
             With  this  option, pppd will not agree to authenticate 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 packets
to initiate
             a  connection  until  a valid LCP packet is received
from the peer
             (as for the `passive' option with  ancient  versions
of pppd).

     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 control the flow of
             data on the serial port.

OPTIONS FILES    [Toc]    [Back]

     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 initial  /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,  delimited
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    [Toc]    [Back]

     Users must be in group "network" to be able to use pppd.

     pppd  provides  system administrators with sufficient access
control that
     PPP access to a server machine can be provided to legitimate
users without
  fear  of compromising the 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 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
     connect 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.  Privileged
 options may be used in the /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    [Toc]    [Back]

     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 authentication 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 Challenge Handshake Authentication
     Protocol (CHAP).  PAP involves the client sending  its  name
and a cleartext
  password 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
require the
     other  to  authenticate  itself.  In that case, two separate
and independent
     authentication exchanges  will  occur.   The  two  exchanges
could use different
  authentication  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.   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  significant  n  bits.  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  authenticating 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 password
is first
     compared with the secret from  the  secrets  file.   If  the
password doesn't
     match  the  secret, the password is encrypted using crypt(3)
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) comparison is  omitted,  for  better
security.

     Furthermore, if the login option was specified, the username
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
     certain 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  terminate
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  papsecrets file
     which  specifies  the  empty string for the client and password, it is possible
 to allow restricted access to hosts  which  refuse  to
authenticate
     themselves.

ROUTING    [Toc]    [Back]

     When  IPCP  negotiation is completed successfully, pppd will
inform the
     kernel of the local and remote IP addresses for the PPP  interface.  This
     is  sufficient  to  create a host route to the remote end of
the link, which
     will enable the peers to exchange IP packets.  Communication
with other
     machines  generally requires further modification to routing
tables and/or
     ARP (Address Resolution Protocol) tables.  In 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 example
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 interface supporting
  broadcast  and ARP, which is up and not a point-topoint 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
assignment),
     pppd has to change the interface IP addresses to the negotiated addresses.
   This  may disrupt existing connections, and the use of
demand dialling
 with peers that do dynamic IP address  assignment  is
not recommended.

EXAMPLES    [Toc]    [Back]

     The following examples assume that the /etc/ppp/options 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 simplest 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 implementation 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:

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

     Alternatively, you can create a username called  (for  example) "ppp",
     whose  login  shell  is  pppd  and  whose  home directory is
/etc/ppp.  Options
     to be used  when  pppd  is  run  this  way  can  be  put  in
/etc/ppp/.ppprc.

     If  your  serial  connection  is any more complicated than a
piece of wire,
     you may need to arrange for some control  characters  to  be
escaped.  In
     particular,  it  is often useful to escape XON (^Q) and XOFF
(^S), using
     asyncmap a0000.  If 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    [Toc]    [Back]

     Messages  are  sent  to the syslogd(8) daemon using facility
LOG_DAEMON.
     (This can be overriden by recompiling pppd  with  the  macro
LOG_PPP defined
     as  the desired facility.)  See the syslogd(8) documentation
for details
     of where the syslog daemon will write the messages.  On most
systems, the
     syslog  daemon uses the /etc/syslog.conf file to specify the
destination(s)
 for syslog messages.  You may need to edit that file
to suit.

     The  debug option causes the contents of all control packets
sent or received
 to be logged, that is, all LCP,  PAP,  CHAP  or  IPCP
packets.  This
     can  be useful if the PPP negotiation does not succeed or 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    [Toc]    [Back]

     pppd invokes scripts at various  stages  in  its  processing
which can be
     used  to  perform site-specific ancillary processing.  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
 variables 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.

     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 executed.  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 parameters 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-protocol    local-IPX-router-name
remote-IPX-
             router-name ipparam pppd-pid

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

             NONE      to indicate that there is no routing  protocol

             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
parameters as
             the ipx-up script.

FILES    [Toc]    [Back]

     /var/run/pppn.pid
             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 authentication.  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 warning
             if this is not the case.

     /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  contain privileged
             options,  even  if  pppd was invoked by a user other
than root.  The
             system administrator 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    [Toc]    [Back]

      
      
     Jacobson,  V., "Compressing TCP/IP headers for low-speed serial links",
     RFC 1144, February 1990.

     Rivest, R., "The MD5 Message-Digest  Algorithm",  RFC  1321,
April 1992.

     McGregor,   G.,  "PPP  Internet  Protocol  Control  Protocol
(IPCP)", RFC 1332,
     May 1992.

     Lloyd, B. and Simpson, W.A., "PPP authentication protocols",
RFC 1334,
     October 1992.

     Simpson,  W.A.,  "The  Point-to-Point  Protocol  (PPP)", RFC
1661, July 1994.

     Simpson, W.A., "PPP in HDLC-like Framing",  RFC  1662,  July
1994.

NOTES    [Toc]    [Back]

     Some  limited degree of control can be exercised over a running pppd process
 by sending it a signal from the list below.

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

     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 decompression error.  (Fatal decompression errors
 generally indicate a bug in one or other implementation.)

AUTHORS    [Toc]    [Back]

     Paul  Mackerras <Paul.Mackerras@samba.org>, based on earlier
work by Drew
     Perkins, Brad Clements, Karl Fox,  Greg  Christy,  and  Brad
Parker.

OpenBSD      3.6                          March      31,     1998
[ Back ]
 Similar pages
Name OS Title
pppoesd HP-UX PPPoE (Point-to-Point Protocol over Ethernet) server daemon
pppd FreeBSD Point to Point Protocol daemon
pppd Tru64 Point-to-Point Protocol (PPP) daemon
pppd Linux Point to Point Protocol daemon
pppoesd.conf HP-UX PPPoE (Point to Point Protocol over Ethernet) server configuration file
pppoec.conf HP-UX PPPoE (Point to Point Protocol over Ethernet) client configuration file
pppoerd.conf HP-UX PPPoE (Point to Point Protocol over Ethernet) relay configuration file
sppp OpenBSD point to point protocol network layer for synchronous lines
sppp FreeBSD point to point protocol network layer for synchronous lines
pppoerd HP-UX PPPoE (Point to Point Protocol over Ethernet) relay
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service