1PPPD(8)                     System Manager's Manual                    PPPD(8)
2
3
4

NAME

6       pppd - Point-to-Point Protocol Daemon
7

SYNOPSIS

9       pppd [ options ]
10

DESCRIPTION

12       PPP  is  the protocol used for establishing internet links over dial-up
13       modems, DSL connections, and many other types of point-to-point  links.
14       The  pppd daemon works together with the kernel PPP driver to establish
15       and maintain a PPP link with another system (called the  peer)  and  to
16       negotiate  Internet  Protocol  (IP) addresses for each end of the link.
17       Pppd can also authenticate the peer and/or supply authentication infor‐
18       mation  to  the  peer.   PPP  can  be used with other network protocols
19       besides IP, but such use is becoming increasingly rare.
20

FREQUENTLY USED OPTIONS

22       ttyname
23              Use the serial port called ttyname to communicate with the peer.
24              If  ttyname  does not begin with a slash (/), the string "/dev/"
25              is prepended to ttyname to form the name of the device to  open.
26              If  no device name is given, or if the name of the terminal con‐
27              nected to the standard input is given, pppd will use that termi‐
28              nal, and will not fork to put itself in the background.  A value
29              for this option from a privileged source cannot be overridden by
30              a non-privileged user.
31
32       speed  An  option that is a decimal number is taken as the desired baud
33              rate for the serial device.  On systems such as 4.4BSD and  Net‐
34              BSD,  any  speed  can  be specified.  Other systems (e.g. Linux,
35              SunOS) only support the commonly-used baud rates.
36
37       asyncmap map
38              This option sets the Async-Control-Character-Map (ACCM) for this
39              end  of the link.  The ACCM is a set of 32 bits, one for each of
40              the ASCII control characters with values from 0 to 31, where a 1
41              bit  indicates  that  the corresponding control character should
42              not be used in PPP packets sent to  this  system.   The  map  is
43              encoded as a hexadecimal number (without a leading 0x) where the
44              least significant bit (00000001) represents character 0 and  the
45              most  significant  bit (80000000) represents character 31.  Pppd
46              will ask the peer to send these characters as  a  2-byte  escape
47              sequence.   If  multiple  asyncmap options are given, the values
48              are ORed together.  If no asyncmap option is given, the  default
49              is  zero,  so  pppd  will ask the peer not to escape any control
50              characters.  To escape transmitted characters,  use  the  escape
51              option.
52
53       auth   Require  the peer to authenticate itself before allowing network
54              packets to be sent or received.  This option is the  default  if
55              the  system has a default route.  If neither this option nor the
56              noauth option is specified, pppd will only allow the peer to use
57              IP addresses to which the system does not already have a route.
58
59       call name
60              Read additional options from the file /etc/ppp/peers/name.  This
61              file may contain privileged options, such  as  noauth,  even  if
62              pppd  is  not  being run by root.  The name string may not begin
63              with / or include .. as a pathname component.  The format of the
64              options file is described below.
65
66       connect script
67              Usually there is something which needs to be done to prepare the
68              link before the PPP protocol can be started; for instance,  with
69              a  dial-up  modem, commands need to be sent to the modem to dial
70              the appropriate phone number.  This option specifies an  command
71              for pppd to execute (by passing it to a shell) before attempting
72              to start PPP negotiation.  The chat (8) program is often  useful
73              here,  as it provides a way to send arbitrary strings to a modem
74              and respond to received characters.  A  value  for  this  option
75              from  a  privileged  source cannot be overridden by a non-privi‐
76              leged user.
77
78       crtscts
79              Specifies that pppd should set the serial port to  use  hardware
80              flow  control using the RTS and CTS signals in the RS-232 inter‐
81              face.  If neither the crtscts, the nocrtscts,  the  cdtrcts  nor
82              the nocdtrcts option is given, the hardware flow control setting
83              for the serial port is left unchanged.  Some serial ports  (such
84              as  Macintosh  serial ports) lack a true RTS output. Such serial
85              ports use this mode to implement  unidirectional  flow  control.
86              The  serial port will suspend transmission when requested by the
87              modem (via CTS) but will be unable to request the modem to  stop
88              sending  to  the  computer. This mode retains the ability to use
89              DTR as a modem control line.
90
91       defaultroute
92              Add a default route to the system routing tables, using the peer
93              as the gateway, when IPCP negotiation is successfully completed.
94              This entry is removed when the PPP connection is  broken.   This
95              option is privileged if the nodefaultroute option has been spec‐
96              ified.
97
98       defaultroute-metric
99              Define the metric of the defaultroute and only add it  if  there
100              is  no  other  default  route  with  the  same metric.  With the
101              default value of -1, the route is only  added  if  there  is  no
102              default route at all.
103
104       defaultroute6
105              Add a default IPv6 route to the system routing tables, using the
106              peer as the gateway, when  IPv6CP  negotiation  is  successfully
107              completed.   This  entry  is  removed when the PPP connection is
108              broken.  This option is privileged if the nodefaultroute6 option
109              has been specified.
110
111       disconnect script
112              Execute  the  command  specified  by  script, by passing it to a
113              shell, after pppd has terminated the link.  This command  could,
114              for  example, issue commands to the modem to cause it to hang up
115              if hardware modem control signals were not available.  The  dis‐
116              connect  script  is not run if the modem has already hung up.  A
117              value for this option from a privileged source cannot  be  over‐
118              ridden by a non-privileged user.
119
120       escape xx,yy,...
121              Specifies that certain characters should be escaped on transmis‐
122              sion (regardless of whether the peer requests them to be escaped
123              with  its  async  control  character map).  The characters to be
124              escaped are specified as a list of hex numbers separated by com‐
125              mas.   Note  that  almost any character can be specified for the
126              escape option, unlike the asyncmap option which only allows con‐
127              trol  characters  to be specified.  The characters which may not
128              be escaped are those with hex values 0x20 - 0x3f or 0x5e.
129
130       file name
131              Read options from file name (the  format  is  described  below).
132              The file must be readable by the user who has invoked pppd.
133
134       init script
135              Execute  the  command  specified  by  script, by passing it to a
136              shell, to initialize the serial line.  This script  would  typi‐
137              cally  use  the chat(8) program to configure the modem to enable
138              auto answer.  A value for this option from a  privileged  source
139              cannot be overridden by a non-privileged user.
140
141       lock   Specifies that pppd should create a UUCP-style lock file for the
142              serial device to ensure exclusive  access  to  the  device.   By
143              default, pppd will not create a lock file.
144
145       mru n  Set the MRU [Maximum Receive Unit] value to n. Pppd will ask the
146              peer to send packets of no more than n bytes.  The  value  of  n
147              must  be between 128 and 16384; the default is 1500.  A value of
148              296 works well on very slow links (40 bytes for TCP/IP header  +
149              256  bytes  of  data).  Note that for the IPv6 protocol, the MRU
150              must be at least 1280.
151
152       mtu n  Set the MTU [Maximum Transmit Unit] value to n.  Unless the peer
153              requests  a smaller value via MRU negotiation, pppd will request
154              that the kernel networking code send data  packets  of  no  more
155              than  n  bytes through the PPP network interface.  Note that for
156              the IPv6 protocol, the MTU must be at least 1280.
157
158       passive
159              Enables the "passive" option in the LCP.  With this option, pppd
160              will  attempt  to initiate a connection; if no reply is received
161              from the peer, pppd will then just wait passively  for  a  valid
162              LCP  packet from the peer, instead of exiting, as it would with‐
163              out this option.
164

OPTIONS

166       <local_IP_address>:<remote_IP_address>
167              Set the local and/or remote interface IP addresses.  Either  one
168              may  be  omitted.  The IP addresses can be specified with a host
169              name or in  decimal  dot  notation  (e.g.  150.234.56.78).   The
170              default  local  address  is the (first) IP address of the system
171              (unless the noipdefault option is given).   The  remote  address
172              will  be  obtained from the peer if not specified in any option.
173              Thus, in simple cases, this option is not required.  If a  local
174              and/or  remote  IP  address  is specified with this option, pppd
175              will not accept a different value from  the  peer  in  the  IPCP
176              negotiation,     unless     the     ipcp-accept-local     and/or
177              ipcp-accept-remote options are given, respectively.
178
179       +ipv6  Enable the IPv6CP and IPv6 protocols.
180
181       ipv6 <local_interface_identifier>,<remote_interface_identifier>
182              Set the local and/or remote 64-bit interface identifier.  Either
183              one may be omitted. The identifier must be specified in standard
184              ASCII notation of IPv6  addresses  (e.g.  ::dead:beef).  If  the
185              ipv6cp-use-ipaddr  option  is given, the local identifier is the
186              local IPv4 address (see above).  On  systems  which  supports  a
187              unique  persistent  id, such as EUI-48 derived from the Ethernet
188              MAC address, ipv6cp-use-persistent option can be used to replace
189              the  ipv6  <local>,<remote>  option. Otherwise the identifier is
190              randomized.
191
192       active-filter filter-expression
193              Specifies a packet filter to  be  applied  to  data  packets  to
194              determine which packets are to be regarded as link activity, and
195              therefore reset the idle timer, or cause the link to be  brought
196              up  in  demand-dialling mode.  This option is useful in conjunc‐
197              tion with the idle option if there are  packets  being  sent  or
198              received  regularly over the link (for example, routing informa‐
199              tion packets) which would otherwise prevent the link  from  ever
200              appearing  to  be  idle.   The  filter-expression  syntax  is as
201              described for tcpdump(1), except that qualifiers which are inap‐
202              propriate for a PPP link, such as ether and arp, are not permit‐
203              ted.  Generally the filter expression should be enclosed in sin‐
204              gle-quotes  to  prevent  whitespace in the expression from being
205              interpreted by the shell. This option is currently  only  avail‐
206              able under Linux, and requires that the kernel was configured to
207              include PPP filtering support (CONFIG_PPP_FILTER).  Note that it
208              is  possible to apply different constraints to incoming and out‐
209              going packets using the inbound and outbound qualifiers.
210
211       allow-ip address(es)
212              Allow peers to use  the  given  IP  address  or  subnet  without
213              authenticating  themselves.  The parameter is parsed as for each
214              element of the list of allowed IP addresses in the secrets files
215              (see the AUTHENTICATION section below).
216
217       allow-number number
218              Allow  peers  to  connect  from  the  given telephone number.  A
219              trailing `*' character will match all numbers beginning with the
220              leading part.
221
222       bsdcomp nr,nt
223              Request  that the peer compress packets that it sends, using the
224              BSD-Compress scheme, with a maximum code size of  nr  bits,  and
225              agree  to  compress packets sent to the peer with a maximum code
226              size of nt bits.  If nt is not specified,  it  defaults  to  the
227              value given for nr.  Values in the range 9 to 15 may be used for
228              nr and nt; larger values give  better  compression  but  consume
229              more kernel memory for compression dictionaries.  Alternatively,
230              a value of 0 for nr or nt disables  compression  in  the  corre‐
231              sponding  direction.  Use nobsdcomp or bsdcomp 0 to disable BSD-
232              Compress compression entirely.
233
234       ca ca-file
235              (EAP-TLS) Use the file ca-file as the X.509 Certificate  Author‐
236              ity  (CA) file (in PEM format), needed for setting up an EAP-TLS
237              connection.  This option is used on the client-side in  conjunc‐
238              tion with the cert and key options.
239
240       cdtrcts
241              Use  a non-standard hardware flow control (i.e. DTR/CTS) to con‐
242              trol the flow of data  on  the  serial  port.   If  neither  the
243              crtscts,  the nocrtscts, the cdtrcts nor the nocdtrcts option is
244              given, the hardware flow control setting for the serial port  is
245              left  unchanged.   Some  serial  ports (such as Macintosh serial
246              ports) lack a true RTS output. Such serial ports use  this  mode
247              to  implement true bi-directional flow control. The sacrifice is
248              that this flow control mode does not permit using DTR as a modem
249              control line.
250
251       cert certfile
252              (EAP-TLS) Use the file certfile as the X.509 certificate (in PEM
253              format), needed for  setting  up  an  EAP-TLS  connection.  This
254              option is used on the client-side in conjunction with the ca and
255              key options.
256
257       chap-interval n
258              If this option is given, pppd will rechallenge the peer every  n
259              seconds.
260
261       chap-max-challenge n
262              Set  the  maximum  number  of  CHAP challenge transmissions to n
263              (default 10).
264
265       chap-restart n
266              Set the CHAP restart interval (retransmission timeout for  chal‐
267              lenges) to n seconds (default 3).
268
269       child-timeout n
270              When  exiting,  wait for up to n seconds for any child processes
271              (such as the command specified with the  pty  command)  to  exit
272              before  exiting.   At  the  end of the timeout, pppd will send a
273              SIGTERM signal to any remaining child  processes  and  exit.   A
274              value  of  0 means no timeout, that is, pppd will wait until all
275              child processes have exited.
276
277       connect-delay n
278              Wait for up to n milliseconds after the connect script  finishes
279              for  a valid PPP packet from the peer.  At the end of this time,
280              or when a valid PPP packet is received from the peer, pppd  will
281              commence  negotiation  by  sending  its  first  LCP packet.  The
282              default value is 1000 (1 second).  This wait period only applies
283              if the connect or pty option is used.
284
285       crl filename
286              (EAP-TLS)  Use  the  file filename as the Certificate Revocation
287              List to check for the validity of the peer's  certificate.  This
288              option  is  not  mandatory for setting up an EAP-TLS connection.
289              Also see the crl-dir option.
290
291       crl-dir directory
292              (EAP-TLS) Use the directory directory to scan for CRL  files  in
293              has  format  ($hash.r0)  to check for the validity of the peer's
294              certificate.  This option is not mandatory  for  setting  up  an
295              EAP-TLS connection.  Also see the crl option.
296
297       debug  Enables  connection  debugging  facilities.   If  this option is
298              given, pppd will log the contents of all control packets sent or
299              received  in  a  readable  form.  The packets are logged through
300              syslog with facility daemon and level debug.   This  information
301              can  be directed to a file by setting up /etc/syslog.conf appro‐
302              priately (see syslog.conf(5)).
303
304       default-asyncmap
305              Disable asyncmap negotiation, forcing all control characters  to
306              be escaped for both the transmit and the receive direction.
307
308       default-mru
309              Disable  MRU  [Maximum  Receive  Unit]  negotiation.   With this
310              option, pppd will use the default MRU value of  1500  bytes  for
311              both the transmit and receive direction.
312
313       deflate nr,nt
314              Request  that the peer compress packets that it sends, using the
315              Deflate scheme, with a maximum window size of 2**nr  bytes,  and
316              agree to compress packets sent to the peer with a maximum window
317              size of 2**nt bytes.  If nt is not specified, it defaults to the
318              value given for nr.  Values in the range 9 to 15 may be used for
319              nr and nt; larger values give  better  compression  but  consume
320              more kernel memory for compression dictionaries.  Alternatively,
321              a value of 0 for nr or nt disables  compression  in  the  corre‐
322              sponding  direction.   Use  nodeflate  or  deflate  0 to disable
323              Deflate compression entirely.  (Note: pppd requests Deflate com‐
324              pression  in  preference  to  BSD-Compress  if  the  peer can do
325              either.)
326
327       demand Initiate the link only on demand,  i.e.  when  data  traffic  is
328              present.   With this option, the remote IP address may be speci‐
329              fied by the user on the command line or in an options  file,  or
330              if  not,  pppd  will  use  an  arbitrary address in the 10.x.x.x
331              range.  Pppd will initially configure the interface  and  enable
332              it  for IP traffic without connecting to the peer.  When traffic
333              is available, pppd will connect to the peer and perform negotia‐
334              tion,  authentication,  etc.   When this is completed, pppd will
335              commence passing data packets  (i.e.,  IP  packets)  across  the
336              link.
337
338              The demand option implies the persist option.  If this behaviour
339              is not desired,  use  the  nopersist  option  after  the  demand
340              option.   The  idle  and holdoff options are also useful in con‐
341              junction with the demand option.
342
343       domain d
344              Append the domain name d to the local host name for  authentica‐
345              tion  purposes.   For example, if gethostname() returns the name
346              porsche,   but   the   fully   qualified    domain    name    is
347              porsche.Quotron.COM, you could specify domain Quotron.COM.  Pppd
348              would then use  the  name  porsche.Quotron.COM  for  looking  up
349              secrets  in the secrets file, and as the default name to send to
350              the peer when authenticating itself to the peer.  This option is
351              privileged.
352
353       dryrun With  the dryrun option, pppd will print out all the option val‐
354              ues which have been set and then exit, after parsing the command
355              line  and  options  files  and  checking  the option values, but
356              before initiating the link.  The option  values  are  logged  at
357              level  info,  and  also  printed  to  standard output unless the
358              device on standard output is the device that pppd would be using
359              to communicate with the peer.
360
361       dump   With  the dump option, pppd will print out all the option values
362              which have been set.  This option  is  like  the  dryrun  option
363              except that pppd proceeds as normal rather than exiting.
364
365       enable-session
366              Enables  session  accounting via PAM or wtwp/wtmpx, as appropri‐
367              ate.  When PAM is enabled, the PAM "account" and "session"  mod‐
368              ule  stacks  determine  behavior,  and  are  enabled for all PPP
369              authentication protocols.   When  PAM  is  disabled,  wtmp/wtmpx
370              entries are recorded regardless of whether the peer name identi‐
371              fies a valid user on the local system, making peers  visible  in
372              the last(1) log.  This feature is automatically enabled when the
373              pppd login option is used.  Session accounting  is  disabled  by
374              default.
375
376       endpoint <epdisc>
377              Sets the endpoint discriminator sent by the local machine to the
378              peer during multilink negotiation to <epdisc>.  The  default  is
379              to  use  the  MAC address of the first ethernet interface on the
380              system, if any, otherwise the IPv4 address corresponding to  the
381              hostname,  if  any,  provided  it  is  not  in  the multicast or
382              locally-assigned IP address ranges, or  the  localhost  address.
383              The endpoint discriminator can be the string null or of the form
384              type:value, where type is a decimal number or one of the strings
385              local,  IP, MAC, magic, or phone.  The value is an IP address in
386              dotted-decimal notation for the IP type, or a string of bytes in
387              hexadecimal, separated by periods or colons for the other types.
388              For the MAC type, the value may also be the name of an  ethernet
389              or  similar  network  interface.   This option is currently only
390              available under Linux.
391
392       eap-interval n
393              If this option is given and pppd authenticates the peer with EAP
394              (i.e.,  is  the  server),  pppd  will restart EAP authentication
395              every n seconds.  For EAP SRP-SHA1, see  also  the  srp-interval
396              option, which enables lightweight rechallenge.
397
398       eap-max-rreq n
399              Set  the  maximum  number  of  EAP  Requests  to which pppd will
400              respond (as a client) without hearing EAP  Success  or  Failure.
401              (Default is 20.)
402
403       eap-max-sreq n
404              Set  the maximum number of EAP Requests that pppd will issue (as
405              a server) while attempting authentication.  (Default is 10.)
406
407       eap-restart n
408              Set the retransmit timeout for EAP Requests  when  acting  as  a
409              server (authenticator).  (Default is 3 seconds.)
410
411       eap-timeout n
412              Set the maximum time to wait for the peer to send an EAP Request
413              when acting as a client (authenticatee).  (Default  is  20  sec‐
414              onds.)
415
416       hide-password
417              When  logging  the  contents  of PAP packets, this option causes
418              pppd to exclude the password string from the log.  This  is  the
419              default.
420
421       holdoff n
422              Specifies how many seconds to wait before re-initiating the link
423              after it terminates.  This option only has  any  effect  if  the
424              persist  or  demand  option  is used.  The holdoff period is not
425              applied if the link was terminated because it was idle.
426
427       idle n Specifies that pppd should disconnect if the link is idle for  n
428              seconds.   The  link is idle when no data packets (i.e. IP pack‐
429              ets) are being sent or received.  Note: it is not  advisable  to
430              use  this  option  with  the  persist  option without the demand
431              option.  If the active-filter  option  is  given,  data  packets
432              which  are  rejected by the specified activity filter also count
433              as the link being idle.
434
435       ipcp-accept-local
436              With this option, pppd will accept the peer's idea of our  local
437              IP  address,  even  if  the local IP address was specified in an
438              option.
439
440       ipcp-accept-remote
441              With this option, pppd  will  accept  the  peer's  idea  of  its
442              (remote) IP address, even if the remote IP address was specified
443              in an option.
444
445       ipcp-max-configure n
446              Set the maximum number of IPCP  configure-request  transmissions
447              to n (default 10).
448
449       ipcp-max-failure n
450              Set  the  maximum  number of IPCP configure-NAKs returned before
451              starting to send configure-Rejects instead to n (default 10).
452
453       ipcp-max-terminate n
454              Set the maximum number of IPCP  terminate-request  transmissions
455              to n (default 3).
456
457       ipcp-restart n
458              Set the IPCP restart interval (retransmission timeout) to n sec‐
459              onds (default 3).
460
461       ipparam string
462              Provides an extra parameter to the ip-up, ip-pre-up and  ip-down
463              scripts.   If this option is given, the string supplied is given
464              as the 6th parameter to those scripts.
465
466       ipv6cp-accept-local
467              With this option, pppd will accept the peer's idea of our  local
468              IPv6  interface  identifier,  even  if  the local IPv6 interface
469              identifier was specified in an option.
470
471       ipv6cp-max-configure n
472              Set the maximum number of IPv6CP configure-request transmissions
473              to n (default 10).
474
475       ipv6cp-max-failure n
476              Set  the maximum number of IPv6CP configure-NAKs returned before
477              starting to send configure-Rejects instead to n (default 10).
478
479       ipv6cp-max-terminate n
480              Set the maximum number of IPv6CP terminate-request transmissions
481              to n (default 3).
482
483       ipv6cp-restart n
484              Set  the  IPv6CP  restart interval (retransmission timeout) to n
485              seconds (default 3).
486
487       ipx    Enable the IPXCP and IPX protocols.  This  option  is  presently
488              only  supported  under  Linux,  and only if your kernel has been
489              configured to include IPX support.
490
491       ipx-network n
492              Set the IPX network number in the IPXCP configure request  frame
493              to  n, a hexadecimal number (without a leading 0x).  There is no
494              valid default.  If this option is  not  specified,  the  network
495              number is obtained from the peer.  If the peer does not have the
496              network number, the IPX protocol will not be started.
497
498       ipx-node n:m
499              Set the IPX node numbers. The two  node  numbers  are  separated
500              from  each  other  with a colon character. The first number n is
501              the local node number. The second number m is  the  peer's  node
502              number.  Each  node  number  is a hexadecimal number, at most 10
503              digits long. The node numbers on the ipx-network must be unique.
504              There  is no valid default. If this option is not specified then
505              the node numbers are obtained from the peer.
506
507       ipx-router-name <string>
508              Set the name of the router. This is a string and is sent to  the
509              peer as information data.
510
511       ipx-routing n
512              Set  the  routing  protocol  to be received by this option. More
513              than one instance of ipx-routing may be  specified.  The  'none'
514              option (0) may be specified as the only instance of ipx-routing.
515              The values may be 0 for NONE, 2 for RIP/SAP, and 4 for NLSP.
516
517       ipxcp-accept-local
518              Accept the peer's NAK for  the  node  number  specified  in  the
519              ipx-node  option.  If a node number was specified, and non-zero,
520              the default is to insist that the value be used. If you  include
521              this  option then you will permit the peer to override the entry
522              of the node number.
523
524       ipxcp-accept-network
525              Accept the peer's NAK for the network number  specified  in  the
526              ipx-network  option. If a network number was specified, and non-
527              zero, the default is to insist that the value be  used.  If  you
528              include  this  option  then you will permit the peer to override
529              the entry of the node number.
530
531       ipxcp-accept-remote
532              Use the peer's network number specified in the configure request
533              frame.  If  a  node  number  was specified for the peer and this
534              option was not specified, the peer will be  forced  to  use  the
535              value which you have specified.
536
537       ipxcp-max-configure n
538              Set  the  maximum number of IPXCP configure request frames which
539              the system will send to n. The default is 10.
540
541       ipxcp-max-failure n
542              Set the maximum number of IPXCP NAK frames which the local  sys‐
543              tem  will  send before it rejects the options. The default value
544              is 3.
545
546       ipxcp-max-terminate n
547              Set the maximum number of IPXCP terminate request frames  before
548              the  local  system  considers  that the peer is not listening to
549              them. The default value is 3.
550
551       kdebug n
552              Enable debugging code in the kernel-level PPP driver.  The argu‐
553              ment values depend on the specific kernel driver, but in general
554              a value of 1 will enable general kernel debug  messages.   (Note
555              that  these  messages  are usually only useful for debugging the
556              kernel driver itself.)  For the Linux 2.2.x kernel  driver,  the
557              value is a sum of bits: 1 to enable general debug messages, 2 to
558              request that the contents of received packets be printed, and  4
559              to  request that the contents of transmitted packets be printed.
560              On most systems, messages printed by the kernel  are  logged  by
561              syslog(1) to a file as directed in the /etc/syslog.conf configu‐
562              ration file.
563
564       key keyfile
565              (EAP-TLS) Use the file keyfile as the private key file  (in  PEM
566              format),  needed  for  setting  up  an  EAP-TLS connection. This
567              option is used on the client-side in conjunction with the ca and
568              cert options.
569
570       ktune  Enables  pppd  to  alter  kernel settings as appropriate.  Under
571              Linux,   pppd   will   enable   IP    forwarding    (i.e.    set
572              /proc/sys/net/ipv4/ip_forward  to  1)  if the proxyarp option is
573              used, and will enable the dynamic IP address  option  (i.e.  set
574              /proc/sys/net/ipv4/ip_dynaddr  to 1) in demand mode if the local
575              address changes.
576
577       lcp-echo-failure n
578              If this option is given, pppd will presume the peer to  be  dead
579              if  n  LCP  echo-requests are sent without receiving a valid LCP
580              echo-reply.  If this happens, pppd will  terminate  the  connec‐
581              tion.   Use  of  this  option  requires a non-zero value for the
582              lcp-echo-interval parameter.  This option can be used to  enable
583              pppd  to terminate after the physical connection has been broken
584              (e.g., the modem has hung up) in situations  where  no  hardware
585              modem control lines are available.
586
587       lcp-echo-interval n
588              If  this  option  is  given,  pppd will send an LCP echo-request
589              frame to the peer every n seconds.   Normally  the  peer  should
590              respond  to  the  echo-request  by  sending an echo-reply.  This
591              option can be used with the lcp-echo-failure  option  to  detect
592              that the peer is no longer connected.
593
594       lcp-max-configure n
595              Set the maximum number of LCP configure-request transmissions to
596              n (default 10).
597
598       lcp-max-failure n
599              Set the maximum number of  LCP  configure-NAKs  returned  before
600              starting to send configure-Rejects instead to n (default 10).
601
602       lcp-max-terminate n
603              Set the maximum number of LCP terminate-request transmissions to
604              n (default 3).
605
606       lcp-restart n
607              Set the LCP restart interval (retransmission timeout) to n  sec‐
608              onds (default 3).
609
610       linkname name
611              Sets  the  logical name of the link to name.  Pppd will create a
612              file named ppp-name.pid in /var/run (or /etc/ppp  on  some  sys‐
613              tems)  containing  its process ID.  This can be useful in deter‐
614              mining which instance of pppd is responsible for the link  to  a
615              given peer system.  This is a privileged option.
616
617       local  Don't  use the modem control lines.  With this option, pppd will
618              ignore the state of the CD  (Carrier  Detect)  signal  from  the
619              modem  and  will  not change the state of the DTR (Data Terminal
620              Ready) signal.  This is the opposite of the modem option.
621
622       logfd n
623              Send log messages to file descriptor n.  Pppd will send log mes‐
624              sages to at most one file or file descriptor (as well as sending
625              the log messages to syslog), so  this  option  and  the  logfile
626              option  are mutually exclusive.  The default is for pppd to send
627              log messages to stdout (file descriptor 1),  unless  the  serial
628              port is already open on stdout.
629
630       logfile filename
631              Append log messages to the file filename (as well as sending the
632              log messages to syslog).  The file is opened with the privileges
633              of the user who invoked pppd, in append mode.
634
635       login  Use  the  system  password  database for authenticating the peer
636              using PAP, and record the user in the system  wtmp  file.   Note
637              that  the  peer  must  have an entry in the /etc/ppp/pap-secrets
638              file as well as the  system  password  database  to  be  allowed
639              access.  See also the enable-session option.
640
641       master_detach
642              If  multilink  is enabled and this pppd process is the multilink
643              bundle master, and the link controlled by this pppd process ter‐
644              minates, this pppd process continues to run in order to maintain
645              the bundle.  If the master_detach option has  been  given,  pppd
646              will  detach  from  its  controlling terminal in this situation,
647              even if the nodetach option has been given.
648
649       maxconnect n
650              Terminate the connection when it has been available for  network
651              traffic  for  n  seconds (i.e. n seconds after the first network
652              control protocol comes up).
653
654       maxfail n
655              Terminate after n consecutive  failed  connection  attempts.   A
656              value of 0 means no limit.  The default value is 10.
657
658       modem  Use  the modem control lines.  This option is the default.  With
659              this option, pppd will wait for the CD (Carrier  Detect)  signal
660              from  the  modem  to  be asserted when opening the serial device
661              (unless a connect script is specified), and it will drop the DTR
662              (Data Terminal Ready) signal briefly when the connection is ter‐
663              minated and before executing the  connect  script.   On  Ultrix,
664              this  option  implies  hardware flow control, as for the crtscts
665              option.  This is the opposite of the local option.
666
667       mp     Enables the use of PPP multilink; this is an alias for the `mul‐
668              tilink'  option.   This option is currently only available under
669              Linux.
670
671       mppe-stateful
672              Allow MPPE to  use  stateful  mode.   Stateless  mode  is  still
673              attempted first.  The default is to disallow stateful mode.
674
675       mpshortseq
676              Enables  the use of short (12-bit) sequence numbers in multilink
677              headers, as opposed to 24-bit sequence numbers.  This option  is
678              only available under Linux, and only has any effect if multilink
679              is enabled (see the multilink option).
680
681       mrru n Sets the Maximum Reconstructed Receive Unit to n.  The  MRRU  is
682              the  maximum  size  for a received packet on a multilink bundle,
683              and is analogous to the MRU  for  the  individual  links.   This
684              option is currently only available under Linux, and only has any
685              effect if multilink is enabled (see the multilink option).
686
687       ms-dns <addr>
688              If pppd is acting as a server  for  Microsoft  Windows  clients,
689              this  option  allows  pppd to supply one or two DNS (Domain Name
690              Server) addresses to the clients.  The first  instance  of  this
691              option  specifies  the  primary DNS address; the second instance
692              (if given) specifies the secondary DNS  address.   (This  option
693              was  present  in  some  older  versions  of  pppd under the name
694              dns-addr.)
695
696       ms-wins <addr>
697              If pppd is acting as a server for Microsoft Windows  or  "Samba"
698              clients, this option allows pppd to supply one or two WINS (Win‐
699              dows Internet Name Services) server addresses  to  the  clients.
700              The  first  instance  of  this option specifies the primary WINS
701              address; the second instance (if given) specifies the  secondary
702              WINS address.
703
704       multilink
705              Enables the use of the PPP multilink protocol.  If the peer also
706              supports multilink, then this link can become part of  a  bundle
707              between  the local system and the peer.  If there is an existing
708              bundle to the peer, pppd will join this  link  to  that  bundle,
709              otherwise pppd will create a new bundle.  See the MULTILINK sec‐
710              tion below.  This  option  is  currently  only  available  under
711              Linux.
712
713       name name
714              Set  the name of the local system for authentication purposes to
715              name.  This is a privileged option.  With this option, pppd will
716              use  lines  in  the  secrets files which have name as the second
717              field when looking for a secret to  use  in  authenticating  the
718              peer.  In addition, unless overridden with the user option, name
719              will be used as the name to send to the peer when authenticating
720              the  local  system to the peer.  (Note that pppd does not append
721              the domain name to name.)
722
723       noaccomp
724              Disable Address/Control compression in both directions (send and
725              receive).
726
727       need-peer-eap
728              (EAP-TLS)  Require the peer to verify our authentication creden‐
729              tials.
730
731       noauth Do not require the peer to authenticate itself.  This option  is
732              privileged.
733
734       nobsdcomp
735              Disables  BSD-Compress  compression;  pppd  will  not request or
736              agree to compress packets using the BSD-Compress scheme.
737
738       noccp  Disable CCP (Compression Control  Protocol)  negotiation.   This
739              option  should  only  be  required if the peer is buggy and gets
740              confused by requests from pppd for CCP negotiation.
741
742       nocrtscts
743              Disable hardware flow control (i.e. RTS/CTS) on the serial port.
744              If neither the crtscts nor the nocrtscts nor the cdtrcts nor the
745              nocdtrcts option is given, the hardware flow control setting for
746              the serial port is left unchanged.
747
748       nocdtrcts
749              This  option is a synonym for nocrtscts. Either of these options
750              will disable both forms of hardware flow control.
751
752       nodefaultroute
753              Disable the defaultroute option.  The system  administrator  who
754              wishes  to  prevent users from creating default routes with pppd
755              can do so by placing this option in the /etc/ppp/options file.
756
757       nodefaultroute6
758              Disable the defaultroute6 option.  The system administrator  who
759              wishes  to  prevent  users from adding a default route with pppd
760              can do so by placing this option in the /etc/ppp/options file.
761
762       nodeflate
763              Disables Deflate compression; pppd will not request or agree  to
764              compress packets using the Deflate scheme.
765
766       nodetach
767              Don't  detach  from  the  controlling  terminal.   Without  this
768              option, if a serial device other than the terminal on the  stan‐
769              dard  input  is specified, pppd will fork to become a background
770              process.
771
772       noendpoint
773              Disables pppd from sending an endpoint discriminator to the peer
774              or  accepting  one  from  the  peer  (see  the MULTILINK section
775              below).  This option should only be  required  if  the  peer  is
776              buggy.
777
778       noip   Disable  IPCP  negotiation  and  IP  communication.  This option
779              should only be required if the peer is buggy and  gets  confused
780              by requests from pppd for IPCP negotiation.
781
782       noipv6 Disable  IPv6CP  negotiation and IPv6 communication. This option
783              should only be required if the peer is buggy and  gets  confused
784              by requests from pppd for IPv6CP negotiation.
785
786       noipdefault
787              Disables the default behaviour when no local IP address is spec‐
788              ified, which is to determine (if possible) the local IP  address
789              from the hostname.  With this option, the peer will have to sup‐
790              ply the local IP address  during  IPCP  negotiation  (unless  it
791              specified explicitly on the command line or in an options file).
792
793       noipx  Disable the IPXCP and IPX protocols.  This option should only be
794              required if the peer is buggy and gets confused by requests from
795              pppd for IPXCP negotiation.
796
797       noktune
798              Opposite of the ktune option; disables pppd from changing system
799              settings.
800
801       nolock Opposite of the lock option; specifies that pppd should not cre‐
802              ate  a  UUCP-style lock file for the serial device.  This option
803              is privileged.
804
805       nolog  Do not send log messages to a file  or  file  descriptor.   This
806              option cancels the logfd and logfile options.
807
808       nomagic
809              Disable magic number negotiation.  With this option, pppd cannot
810              detect a looped-back line.  This option should only be needed if
811              the peer is buggy.
812
813       nomp   Disables  the  use  of  PPP multilink.  This option is currently
814              only available under Linux.
815
816       nomppe Disables MPPE (Microsoft Point to Point  Encryption).   This  is
817              the default.
818
819       nomppe-40
820              Disable 40-bit encryption with MPPE.
821
822       nomppe-128
823              Disable 128-bit encryption with MPPE.
824
825       nomppe-stateful
826              Disable MPPE stateful mode.  This is the default.
827
828       nompshortseq
829              Disables  the  use of short (12-bit) sequence numbers in the PPP
830              multilink protocol, forcing the use of 24-bit sequence  numbers.
831              This  option  is  currently only available under Linux, and only
832              has any effect if multilink is enabled.
833
834       nomultilink
835              Disables the use of PPP multilink.   This  option  is  currently
836              only available under Linux.
837
838       nopcomp
839              Disable  protocol  field  compression  negotiation  in  both the
840              receive and the transmit direction.
841
842       nopersist
843              Exit once a connection has been made and  terminated.   This  is
844              the  default unless the persist or demand option has been speci‐
845              fied.
846
847       nopredictor1
848              Do not accept or agree to Predictor-1 compression.
849
850       noproxyarp
851              Disable the  proxyarp  option.   The  system  administrator  who
852              wishes  to  prevent  users  from creating proxy ARP entries with
853              pppd can do so by placing this option  in  the  /etc/ppp/options
854              file.
855
856       noremoteip
857              Allow pppd to operate without having an IP address for the peer.
858              This option is only available under Linux.  Normally, pppd  will
859              request  the  peer's IP address, and if the peer does not supply
860              it, pppd will use an arbitrary address in the  10.x.x.x  subnet.
861              With  this  option,  if the peer does not supply its IP address,
862              pppd will not ask the peer for it, and will not set the destina‐
863              tion  address  of the ppp interface.  In this situation, the ppp
864              interface can be used for routing by creating device routes, but
865              the peer itself cannot be addressed directly for IP traffic.
866
867       notty  Normally,  pppd  requires  a terminal device.  With this option,
868              pppd will allocate itself a pseudo-tty master/slave pair and use
869              the  slave  as  its  terminal  device.  Pppd will create a child
870              process to act as a `character  shunt'  to  transfer  characters
871              between the pseudo-tty master and its standard input and output.
872              Thus pppd will transmit characters on its  standard  output  and
873              receive  characters  on  its standard input even if they are not
874              terminal devices.  This option increases  the  latency  and  CPU
875              overhead  of  transferring data over the ppp interface as all of
876              the characters sent and received must flow through the character
877              shunt process.  An explicit device name may not be given if this
878              option is used.
879
880       novj   Disable Van Jacobson style TCP/IP header compression in both the
881              transmit and the receive direction.
882
883       novjccomp
884              Disable  the  connection-ID  compression  option in Van Jacobson
885              style TCP/IP header compression.  With this  option,  pppd  will
886              not  omit  the  connection-ID  byte from Van Jacobson compressed
887              TCP/IP headers, nor ask the peer to do so.
888
889       papcrypt
890              Indicates that all  secrets  in  the  /etc/ppp/pap-secrets  file
891              which  are  used  for  checking  the  identity  of  the peer are
892              encrypted, and thus pppd should not  accept  a  password  which,
893              before   encryption,   is  identical  to  the  secret  from  the
894              /etc/ppp/pap-secrets file.
895
896       pap-max-authreq n
897              Set the maximum number of PAP authenticate-request transmissions
898              to n (default 10).
899
900       pap-restart n
901              Set  the PAP restart interval (retransmission timeout) to n sec‐
902              onds (default 3).
903
904       pap-timeout n
905              Set the maximum time that pppd will wait for the peer to authen‐
906              ticate itself with PAP to n seconds (0 means no limit).
907
908       pass-filter filter-expression
909              Specifies  a packet filter to applied to data packets being sent
910              or received to determine which  packets  should  be  allowed  to
911              pass.   Packets  which  are  rejected by the filter are silently
912              discarded.  This option can be used to prevent specific  network
913              daemons  (such as routed) using up link bandwidth, or to provide
914              a very basic firewall capability.  The filter-expression  syntax
915              is as described for tcpdump(1), except that qualifiers which are
916              inappropriate for a PPP link, such as ether  and  arp,  are  not
917              permitted.   Generally  the filter expression should be enclosed
918              in single-quotes to prevent whitespace in  the  expression  from
919              being  interpreted  by  the  shell.  Note that it is possible to
920              apply different constraints to  incoming  and  outgoing  packets
921              using  the  inbound and outbound qualifiers. This option is cur‐
922              rently only available under Linux, and requires that the  kernel
923              was configured to include PPP filtering support (CONFIG_PPP_FIL‐
924              TER).
925
926       password password-string
927              Specifies the password to use for authenticating  to  the  peer.
928              Use  of this option is discouraged, as the password is likely to
929              be visible to other users on the system (for example,  by  using
930              ps(1)).
931
932       persist
933              Do  not  exit  after  a connection is terminated; instead try to
934              reopen the connection. The maxfail option still has an effect on
935              persistent connections.
936
937       plugin filename
938              Load  the shared library object file filename as a plugin.  This
939              is a privileged option.  If filename does not  contain  a  slash
940              (/),  pppd  will look in the /usr/lib/pppd/version directory for
941              the plugin, where version is the version  number  of  pppd  (for
942              example, 2.4.2).
943
944       predictor1
945              Request  that  the peer compress frames that it sends using Pre‐
946              dictor-1 compression, and agree to compress  transmitted  frames
947              with Predictor-1 if requested.  This option has no effect unless
948              the kernel driver supports Predictor-1 compression.
949
950       privgroup group-name
951              Allows members of group group-name to  use  privileged  options.
952              This  is  a privileged option.  Use of this option requires care
953              as there is no guarantee that members of group-name  cannot  use
954              pppd  to  become  root  themselves.   Consider  it equivalent to
955              putting the members of group-name in the kmem or disk group.
956
957       proxyarp
958              Add an entry to this system's ARP [Address Resolution  Protocol]
959              table  with  the IP address of the peer and the Ethernet address
960              of this system.  This will have the effect of  making  the  peer
961              appear to other systems to be on the local ethernet.
962
963       pty script
964              Specifies  that  the command script is to be used to communicate
965              rather than a specific  terminal  device.   Pppd  will  allocate
966              itself  a  pseudo-tty master/slave pair and use the slave as its
967              terminal device.  The script will be run in a child process with
968              the  pseudo-tty  master  as  its  standard input and output.  An
969              explicit device name may not be given if this  option  is  used.
970              (Note:  if the record option is used in conjunction with the pty
971              option, the child process will have pipes on its standard  input
972              and output.)
973
974       receive-all
975              With  this  option, pppd will accept all control characters from
976              the peer, including those marked in the receive asyncmap.  With‐
977              out this option, pppd will discard those characters as specified
978              in RFC1662.  This option should only be needed if  the  peer  is
979              buggy.
980
981       record filename
982              Specifies  that  pppd  should  record  all  characters  sent and
983              received to a file named  filename.   This  file  is  opened  in
984              append  mode,  using  the  user's user-ID and permissions.  This
985              option is implemented using a pseudo-tty and a process to trans‐
986              fer  characters  between  the  pseudo-tty  and  the  real serial
987              device, so it will increase the  latency  and  CPU  overhead  of
988              transferring  data  over  the ppp interface.  The characters are
989              stored in a tagged format with timestamps,  which  can  be  dis‐
990              played in readable form using the pppdump(8) program.
991
992       remotename name
993              Set  the  assumed  name  of the remote system for authentication
994              purposes to name.
995
996       remotenumber number
997              Set the assumed  telephone  number  of  the  remote  system  for
998              authentication purposes to number.
999
1000       refuse-chap
1001              With  this option, pppd will not agree to authenticate itself to
1002              the peer using CHAP.
1003
1004       refuse-mschap
1005              With this option, pppd will not agree to authenticate itself  to
1006              the peer using MS-CHAP.
1007
1008       refuse-mschap-v2
1009              With  this option, pppd will not agree to authenticate itself to
1010              the peer using MS-CHAPv2.
1011
1012       refuse-eap
1013              With this option, pppd will not agree to authenticate itself  to
1014              the peer using EAP.
1015
1016       refuse-pap
1017              With  this option, pppd will not agree to authenticate itself to
1018              the peer using PAP.
1019
1020       require-chap
1021              Require the peer to authenticate itself  using  CHAP  [Challenge
1022              Handshake Authentication Protocol] authentication.
1023
1024       require-mppe
1025              Require  the  use of MPPE (Microsoft Point to Point Encryption).
1026              This option disables all other compression types.   This  option
1027              enables  both  40-bit and 128-bit encryption.  In order for MPPE
1028              to successfully come up, you must have authenticated with either
1029              MS-CHAP  or  MS-CHAPv2.  This option is presently only supported
1030              under Linux, and only if your  kernel  has  been  configured  to
1031              include MPPE support.
1032
1033       require-mppe-40
1034              Require the use of MPPE, with 40-bit encryption.
1035
1036       require-mppe-128
1037              Require the use of MPPE, with 128-bit encryption.
1038
1039       require-mschap
1040              Require the peer to authenticate itself using MS-CHAP [Microsoft
1041              Challenge Handshake Authentication Protocol] authentication.
1042
1043       require-mschap-v2
1044              Require the peer to authenticate itself using MS-CHAPv2  [Micro‐
1045              soft  Challenge  Handshake  Authentication  Protocol, Version 2]
1046              authentication.
1047
1048       require-eap
1049              Require the peer to authenticate itself  using  EAP  [Extensible
1050              Authentication Protocol] authentication.
1051
1052       require-pap
1053              Require  the  peer  to  authenticate  itself using PAP [Password
1054              Authentication Protocol] authentication.
1055
1056       set name=value
1057              Set an environment variable for  scripts  that  are  invoked  by
1058              pppd.   When  set by a privileged source, the variable specified
1059              by name cannot be changed by options contained  in  an  unprivi‐
1060              leged  source.   See  also  the unset option and the environment
1061              described in SCRIPTS.
1062
1063       show-password
1064              When logging the contents of PAP  packets,  this  option  causes
1065              pppd to show the password string in the log message.
1066
1067       silent With this option, pppd will not transmit LCP packets to initiate
1068              a connection until a valid LCP packet is received from the  peer
1069              (as for the `passive' option with ancient versions of pppd).
1070
1071       srp-interval n
1072              If this parameter is given and pppd uses EAP SRP-SHA1 to authen‐
1073              ticate the peer (i.e., is the server), then pppd  will  use  the
1074              optional lightweight SRP rechallenge mechanism at intervals of n
1075              seconds.  This option is faster than eap-interval  reauthentica‐
1076              tion  because it uses a hash-based mechanism and does not derive
1077              a new session key.
1078
1079       srp-pn-secret string
1080              Set the long-term pseudonym-generating secret  for  the  server.
1081              This  value  is  optional  and  if set, needs to be known at the
1082              server (authenticator) side only, and should  be  different  for
1083              each  server  (or  poll of identical servers).  It is used along
1084              with the current date to generate a key to encrypt  and  decrypt
1085              the client's identity contained in the pseudonym.
1086
1087       srp-use-pseudonym
1088              When  operating  as  an  EAP SRP-SHA1 client, attempt to use the
1089              pseudonym stored in ~/.ppp_pseudonym first as the identity,  and
1090              save  in  this  file  any  pseudonym  offered by the peer during
1091              authentication.
1092
1093       sync   Use synchronous HDLC serial encoding  instead  of  asynchronous.
1094              The device used by pppd with this option must have sync support.
1095              Currently supports Microgate SyncLink adapters under  Linux  and
1096              FreeBSD 2.2.8 and later.
1097
1098       unit num
1099              Sets the ppp unit number (for a ppp0 or ppp1 etc interface name)
1100              for outbound connections.  If the  unit  is  already  in  use  a
1101              dynamically allocated number will be used.
1102
1103       ifname string
1104              Set  the  ppp  interface  name for outbound connections.  If the
1105              interface name is already in use, or if the name cannot be  used
1106              for any other reason, pppd will terminate.
1107
1108       unset name
1109              Remove a variable from the environment variable for scripts that
1110              are invoked by pppd.  When specified by a privileged source, the
1111              variable  name cannot be set by options contained in an unprivi‐
1112              leged source.  See also  the  set  option  and  the  environment
1113              described in SCRIPTS.
1114
1115       updetach
1116              With this option, pppd will detach from its controlling terminal
1117              once it has successfully established the ppp connection (to  the
1118              point  where  the first network control protocol, usually the IP
1119              control protocol, has come up).
1120
1121       up_sdnotify
1122              Use this  option  to  run  pppd  in  systemd  service  units  of
1123              Type=notify (up_sdnotify implies nodetach).  When up_sdnotify is
1124              enabled, pppd will  notify  systemd  once  it  has  successfully
1125              established  the  ppp  connection  (to the point where the first
1126              network control protocl, usually the IP  control  protocol,  has
1127              come  up).  This  option  is only availble when pppd is compiled
1128              with systemd support.
1129
1130       usehostname
1131              Enforce the use of the hostname (with domain name  appended,  if
1132              given)  as  the name of the local system for authentication pur‐
1133              poses (overrides the name option).  This option is not  normally
1134              needed since the name option is privileged.
1135
1136       usepeerdns
1137              Ask  the  peer  for up to 2 DNS server addresses.  The addresses
1138              supplied by the peer (if any) are passed to  the  /etc/ppp/ip-up
1139              script in the environment variables DNS1 and DNS2, and the envi‐
1140              ronment variable USEPEERDNS will be set to 1.  In addition, pppd
1141              will  create  an /var/run/ppp/resolv.conf file containing one or
1142              two nameserver lines with the address(es) supplied by the peer.
1143
1144       user name
1145              Sets the name used for authenticating the local  system  to  the
1146              peer to name.
1147
1148       vj-max-slots n
1149              Sets the number of connection slots to be used by the Van Jacob‐
1150              son TCP/IP header compression and decompression code to n, which
1151              must be between 2 and 16 (inclusive).
1152
1153       welcome script
1154              Run  the  executable or shell command specified by script before
1155              initiating PPP negotiation, after the connect  script  (if  any)
1156              has completed.  A value for this option from a privileged source
1157              cannot be overridden by a non-privileged user.
1158
1159       xonxoff
1160              Use software flow control (i.e. XON/XOFF) to control the flow of
1161              data on the serial port.
1162

OPTIONS FILES

1164       Options  can  be  taken  from  files as well as the command line.  Pppd
1165       reads  options  from   the   files   /etc/ppp/options,   ~/.ppprc   and
1166       /etc/ppp/options.ttyname  (in that order) before processing the options
1167       on the command line.  (In fact, the command-line options are scanned to
1168       find  the  terminal  name before the options.ttyname file is read.)  In
1169       forming the name of the options.ttyname  file,  the  initial  /dev/  is
1170       removed  from  the  terminal  name,  and any remaining / characters are
1171       replaced with dots.
1172
1173       An options file is parsed into a series of words, delimited  by  white‐
1174       space.   Whitespace  can be included in a word by enclosing the word in
1175       double-quotes (").  A backslash (\) quotes the following character.   A
1176       hash  (#)  starts a comment, which continues until the end of the line.
1177       There is no restriction on using the file or  call  options  within  an
1178       options file.
1179

SECURITY

1181       pppd provides system administrators with sufficient access control that
1182       PPP access to a server machine can  be  provided  to  legitimate  users
1183       without  fear of compromising the security of the server or the network
1184       it's on.  This control is provided through  restrictions  on  which  IP
1185       addresses  the  peer  may  use, based on its authenticated identity (if
1186       any), and through restrictions on which options a  non-privileged  user
1187       may use.  Several of pppd's options are privileged, in particular those
1188       which permit potentially insecure  configurations;  these  options  are
1189       only accepted in files which are under the control of the system admin‐
1190       istrator, or if pppd is being run by root.
1191
1192       The default behaviour of pppd is to allow an  unauthenticated  peer  to
1193       use a given IP address only if the system does not already have a route
1194       to that IP address.  For example, a system with a permanent  connection
1195       to  the wider internet will normally have a default route, and thus all
1196       peers will have to authenticate themselves in order to set up a connec‐
1197       tion.   On such a system, the auth option is the default.  On the other
1198       hand, a system where the PPP link is the only connection to the  inter‐
1199       net will not normally have a default route, so the peer will be able to
1200       use almost any IP address without authenticating itself.
1201
1202       As indicated above, some  security-sensitive  options  are  privileged,
1203       which  means  that  they  may not be used by an ordinary non-privileged
1204       user running a setuid-root pppd, either on the  command  line,  in  the
1205       user's ~/.ppprc file, or in an options file read using the file option.
1206       Privileged options may be  used  in  /etc/ppp/options  file  or  in  an
1207       options  file  read using the call option.  If pppd is being run by the
1208       root user, privileged options can be used without restriction.
1209
1210       When opening the device, pppd uses either the invoking user's  user  ID
1211       or  the root UID (that is, 0), depending on whether the device name was
1212       specified by the user or the system administrator.  If the device  name
1213       comes from a privileged source, that is, /etc/ppp/options or an options
1214       file read using the call option, pppd uses full  root  privileges  when
1215       opening  the  device.   Thus,  by  creating  an  appropriate file under
1216       /etc/ppp/peers, the system administrator can allow users to establish a
1217       ppp  connection via a device which they would not normally have permis‐
1218       sion to access.  Otherwise pppd uses the invoking user's real UID  when
1219       opening the device.
1220

AUTHENTICATION

1222       Authentication  is  the process whereby one peer convinces the other of
1223       its identity.  This involves the first peer sending  its  name  to  the
1224       other,  together  with some kind of secret information which could only
1225       come from the genuine  authorized  user  of  that  name.   In  such  an
1226       exchange,  we  will  call the first peer the "client" and the other the
1227       "server".  The client has a name by which it identifies itself  to  the
1228       server, and the server also has a name by which it identifies itself to
1229       the client.  Generally the genuine client shares some secret (or  pass‐
1230       word)  with  the  server,  and  authenticates itself by proving that it
1231       knows that secret.  Very often, the names used for authentication  cor‐
1232       respond  to the internet hostnames of the peers, but this is not essen‐
1233       tial.
1234
1235       At present, pppd supports three authentication protocols: the  Password
1236       Authentication  Protocol (PAP), Challenge Handshake Authentication Pro‐
1237       tocol  (CHAP),  and  Extensible  Authentication  Protocol  (EAP).   PAP
1238       involves  the  client  sending its name and a cleartext password to the
1239       server to authenticate itself.  In contrast, the server  initiates  the
1240       CHAP  authentication exchange by sending a challenge to the client (the
1241       challenge packet includes the server's name).  The client must  respond
1242       with  a response which includes its name plus a hash value derived from
1243       the shared secret and the challenge, in order to prove  that  it  knows
1244       the  secret.  EAP supports CHAP-style authentication, and also includes
1245       the SRP-SHA1 mechanism, which is resistant to dictionary-based  attacks
1246       and does not require a cleartext password on the server side.
1247
1248       The  PPP  protocol, being symmetrical, allows both peers to require the
1249       other to authenticate itself.  In that case, two separate and  indepen‐
1250       dent  authentication exchanges will occur.  The two exchanges could use
1251       different authentication protocols, and in principle,  different  names
1252       could be used in the two exchanges.
1253
1254       The default behaviour of pppd is to agree to authenticate if requested,
1255       and to not require authentication from the peer.   However,  pppd  will
1256       not  agree  to authenticate itself with a particular protocol if it has
1257       no secrets which could be used to do so.
1258
1259       Pppd  stores  secrets  for  use  in  authentication  in  secrets  files
1260       (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP, MS-CHAP,
1261       MS-CHAPv2, and EAP  MD5-Challenge,  and  /etc/ppp/srp-secrets  for  EAP
1262       SRP-SHA1).   All secrets files have the same format.  The secrets files
1263       can contain secrets for pppd to use in authenticating itself  to  other
1264       systems,  as  well as secrets for pppd to use when authenticating other
1265       systems to itself.
1266
1267       Each line in a secrets file contains one secret.   A  given  secret  is
1268       specific to a particular combination of client and server - it can only
1269       be used by that client to authenticate itself  to  that  server.   Thus
1270       each  line  in  a  secrets  file has at least 3 fields: the name of the
1271       client, the name of the server, and the secret.  These  fields  may  be
1272       followed  by  a  list of the IP addresses that the specified client may
1273       use when connecting to the specified server.
1274
1275       A secrets file is parsed into words as  for  a  options  file,  so  the
1276       client name, server name and secrets fields must each be one word, with
1277       any embedded spaces or other  special  characters  quoted  or  escaped.
1278       Note that case is significant in the client and server names and in the
1279       secret.
1280
1281       If the secret starts with an `@', what follows is  assumed  to  be  the
1282       name  of  a file from which to read the secret.  A "*" as the client or
1283       server name matches any name.  When selecting a secret, pppd takes  the
1284       best match, i.e.  the match with the fewest wildcards.
1285
1286       Any  following words on the same line are taken to be a list of accept‐
1287       able IP addresses for that client.  If there are only 3  words  on  the
1288       line,  or  if  the  first word is "-", then all IP addresses are disal‐
1289       lowed.  To allow any address, use "*".  A word starting with "!"  indi‐
1290       cates  that the specified address is not acceptable.  An address may be
1291       followed by "/" and a number n, to indicate a whole  subnet,  i.e.  all
1292       addresses which have the same value in the most significant n bits.  In
1293       this form, the address may be followed by a plus sign ("+") to indicate
1294       that  one  address from the subnet is authorized, based on the ppp net‐
1295       work interface unit number in use.  In this case, the host part of  the
1296       address will be set to the unit number plus one.
1297
1298       Thus  a  secrets  file  contains both secrets for use in authenticating
1299       other hosts, plus secrets which we use for authenticating ourselves  to
1300       others.   When  pppd  is  authenticating  the peer (checking the peer's
1301       identity), it chooses a secret with the peer's name in the first  field
1302       and  the name of the local system in the second field.  The name of the
1303       local system defaults to the hostname, with the domain name appended if
1304       the  domain  option  is  used.  This default can be overridden with the
1305       name option, except when the usehostname  option  is  used.   (For  EAP
1306       SRP-SHA1,  see the srp-entry(8) utility for generating proper validator
1307       entries to be used in the "secret" field.)
1308
1309       When pppd is choosing a secret to use in authenticating itself  to  the
1310       peer,  it  first  determines  what  name it is going to use to identify
1311       itself to the peer.  This name can be specified by the  user  with  the
1312       user option.  If this option is not used, the name defaults to the name
1313       of the local system, determined as described in the previous paragraph.
1314       Then  pppd looks for a secret with this name in the first field and the
1315       peer's name in the second field.  Pppd will know the name of  the  peer
1316       if CHAP or EAP authentication is being used, because the peer will have
1317       sent it in the challenge packet.  However, if PAP is being  used,  pppd
1318       will  have  to  determine the peer's name from the options specified by
1319       the user.  The user can specify  the  peer's  name  directly  with  the
1320       remotename  option.   Otherwise, if the remote IP address was specified
1321       by a name (rather than in numeric form), that name will be used as  the
1322       peer's name.  Failing that, pppd will use the null string as the peer's
1323       name.
1324
1325       When authenticating the peer with PAP, the supplied password  is  first
1326       compared  with  the  secret  from  the  secrets  file.  If the password
1327       doesn't match the secret, the password is encrypted using  crypt()  and
1328       checked  against the secret again.  Thus secrets for authenticating the
1329       peer can be stored in encrypted  form  if  desired.   If  the  papcrypt
1330       option  is  given,  the  first (unencrypted) comparison is omitted, for
1331       better security.
1332
1333       Furthermore, if the login option was specified, the username and  pass‐
1334       word  are also checked against the system password database.  Thus, the
1335       system administrator can set up  the  pap-secrets  file  to  allow  PPP
1336       access  only  to certain users, and to restrict the set of IP addresses
1337       that each user can use.  Typically, when using the  login  option,  the
1338       secret  in /etc/ppp/pap-secrets would be "", which will match any pass‐
1339       word supplied by the peer.  This avoids  the  need  to  have  the  same
1340       secret in two places.
1341
1342       Authentication  must  be  satisfactorily  completed before IPCP (or any
1343       other Network Control  Protocol)  can  be  started.   If  the  peer  is
1344       required  to  authenticate itself, and fails to do so, pppd will termi‐
1345       nated the link (by closing LCP).  If IPCP negotiates an unacceptable IP
1346       address  for the remote host, IPCP will be closed.  IP packets can only
1347       be sent or received when IPCP is open.
1348
1349       In some cases it is desirable to allow some hosts which can't authenti‐
1350       cate  themselves  to  connect  and  use  one  of a restricted set of IP
1351       addresses, even when the local host generally requires  authentication.
1352       If  the  peer refuses to authenticate itself when requested, pppd takes
1353       that as equivalent to authenticating with PAP using  the  empty  string
1354       for  the  username  and  password.   Thus,  by  adding  a  line  to the
1355       pap-secrets file which specifies the empty string for  the  client  and
1356       password,  it  is  possible  to  allow restricted access to hosts which
1357       refuse to authenticate themselves.
1358

ROUTING

1360       When IPCP negotiation is completed successfully, pppd will  inform  the
1361       kernel  of  the  local  and  remote IP addresses for the ppp interface.
1362       This is sufficient to create a host route to  the  remote  end  of  the
1363       link,  which  will enable the peers to exchange IP packets.  Communica‐
1364       tion with other machines generally  requires  further  modification  to
1365       routing  tables  and/or  ARP  (Address Resolution Protocol) tables.  In
1366       most cases the defaultroute and/or proxyarp options are sufficient  for
1367       this,  but  in  some  cases  further  intervention  is  required.   The
1368       /etc/ppp/ip-up script can be used for this.
1369
1370       Sometimes it is desirable to add a default  route  through  the  remote
1371       host, as in the case of a machine whose only connection to the Internet
1372       is through the ppp interface.  The defaultroute option causes  pppd  to
1373       create  such a default route when IPCP comes up, and delete it when the
1374       link is terminated.
1375
1376       In some cases it is desirable to use proxy ARP, for example on a server
1377       machine  connected  to a LAN, in order to allow other hosts to communi‐
1378       cate with the remote host.  The proxyarp option causes pppd to look for
1379       a network interface on the same subnet as the remote host (an interface
1380       supporting broadcast and ARP, which is up and not a  point-to-point  or
1381       loopback interface).  If found, pppd creates a permanent, published ARP
1382       entry with the IP address of the remote host and the  hardware  address
1383       of the network interface found.
1384
1385       When the demand option is used, the interface IP addresses have already
1386       been set at the point when IPCP comes up.  If pppd has not been able to
1387       negotiate  the  same  addresses that it used to configure the interface
1388       (for example when the peer is an  ISP  that  uses  dynamic  IP  address
1389       assignment), pppd has to change the interface IP addresses to the nego‐
1390       tiated addresses.  This may disrupt existing connections, and  the  use
1391       of  demand dialling with peers that do dynamic IP address assignment is
1392       not recommended.
1393
1395       Multilink PPP provides the capability to combine two or more PPP  links
1396       between  a  pair of machines into a single `bundle', which appears as a
1397       single virtual PPP link which has the combined bandwidth of  the  indi‐
1398       vidual links.  Currently, multilink PPP is only supported under Linux.
1399
1400       Pppd  detects  that the link it is controlling is connected to the same
1401       peer as another link using the peer's endpoint  discriminator  and  the
1402       authenticated  identity  of the peer (if it authenticates itself).  The
1403       endpoint discriminator is a block of data which is hopefully unique for
1404       each  peer.   Several  types  of  data  can be used, including locally-
1405       assigned strings  of  bytes,  IP  addresses,  MAC  addresses,  randomly
1406       strings  of  bytes, or E-164 phone numbers.  The endpoint discriminator
1407       sent to the peer by pppd can be set using the endpoint option.
1408
1409       In some circumstances the peer may send no endpoint discriminator or  a
1410       non-unique  value.   The  bundle  option  adds an extra string which is
1411       added to the peer's endpoint discriminator and  authenticated  identity
1412       when  matching  up links to be joined together in a bundle.  The bundle
1413       option can also be used to allow the establishment of multiple  bundles
1414       between  the  local  system  and the peer.  Pppd uses a TDB database in
1415       /var/run/pppd2.tdb to match up links.
1416
1417       Assuming that multilink is enabled and the peer is willing to negotiate
1418       multilink,  then when pppd is invoked to bring up the first link to the
1419       peer, it will detect that no other link is connected to  the  peer  and
1420       create a new bundle, that is, another ppp network interface unit.  When
1421       another pppd is invoked to bring up another link to the peer,  it  will
1422       detect the existing bundle and join its link to it.
1423
1424       If  the  first  link  terminates (for example, because of a hangup or a
1425       received LCP terminate-request) the  bundle  is  not  destroyed  unless
1426       there are no other links remaining in the bundle.  Rather than exiting,
1427       the first pppd keeps running after its link terminates, until  all  the
1428       links  in  the  bundle  have  terminated.  If the first pppd receives a
1429       SIGTERM or SIGINT signal, it will destroy the bundle and send a  SIGHUP
1430       to  the  pppd  processes  for  each of the links in the bundle.  If the
1431       first pppd receives a SIGHUP signal, it will terminate its link but not
1432       the bundle.
1433
1434       Note: demand mode is not currently supported with multilink.
1435

EXAMPLES

1437       The  following  examples assume that the /etc/ppp/options file contains
1438       the auth option (as in the default /etc/ppp/options  file  in  the  ppp
1439       distribution).
1440
1441       Probably  the  most  common use of pppd is to dial out to an ISP.  This
1442       can be done with a command such as
1443
1444              pppd call isp
1445
1446       where the /etc/ppp/peers/isp file is set up by the system administrator
1447       to contain something like this:
1448
1449              ttyS0 19200 crtscts
1450              connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp'
1451              noauth
1452
1453       In  this  example,  we  are  using  chat to dial the ISP's modem and go
1454       through any logon sequence required.  The /etc/ppp/chat-isp  file  con‐
1455       tains  the  script used by chat; it could for example contain something
1456       like this:
1457
1458              ABORT "NO CARRIER"
1459              ABORT "NO DIALTONE"
1460              ABORT "ERROR"
1461              ABORT "NO ANSWER"
1462              ABORT "BUSY"
1463              ABORT "Username/Password Incorrect"
1464              "" "at"
1465              OK "at&d0&c1"
1466              OK "atdt2468135"
1467              "name:" "^Umyuserid"
1468              "word:" "\qmypassword"
1469              "ispts" "\q^Uppp"
1470              "~-^Uppp-~"
1471
1472       See the chat(8) man page for details of chat scripts.
1473
1474       Pppd can also be used to provide a dial-in ppp service for  users.   If
1475       the  users  already have login accounts, the simplest way to set up the
1476       ppp service is to let the users log in to their accounts and  run  pppd
1477       (installed setuid-root) with a command such as
1478
1479              pppd proxyarp
1480
1481       To  allow  a user to use the PPP facilities, you need to allocate an IP
1482       address  for   that   user's   machine   and   create   an   entry   in
1483       /etc/ppp/pap-secrets,  /etc/ppp/chap-secrets,  or  /etc/ppp/srp-secrets
1484       (depending on which authentication method the PPP implementation on the
1485       user's  machine  supports), so that the user's machine can authenticate
1486       itself.  For example, if Joe has a machine called "joespc" that  is  to
1487       be  allowed  to  dial  in to the machine called "server" and use the IP
1488       address  joespc.my.net,  you  would  add  an   entry   like   this   to
1489       /etc/ppp/pap-secrets or /etc/ppp/chap-secrets:
1490
1491              joespc    server    "joe's secret" joespc.my.net
1492
1493       (See  srp-entry(8)  for  a  means  to  generate the server's entry when
1494       SRP-SHA1 is in use.)  Alternatively, you can create a  username  called
1495       (for example) "ppp", whose login shell is pppd and whose home directory
1496       is /etc/ppp.  Options to be used when pppd is run this way can  be  put
1497       in /etc/ppp/.ppprc.
1498
1499       If your serial connection is any more complicated than a piece of wire,
1500       you may need to arrange for some control characters to be escaped.   In
1501       particular,  it is often useful to escape XON (^Q) and XOFF (^S), using
1502       asyncmap a0000.  If the path includes a  telnet,  you  probably  should
1503       escape ^] as well (asyncmap 200a0000).  If the path includes an rlogin,
1504       you will need to use the escape ff option on the end which  is  running
1505       the  rlogin client, since many rlogin implementations are not transpar‐
1506       ent; they will remove the sequence [0xff, 0xff, 0x73, 0x73, followed by
1507       any 8 bytes] from the stream.
1508

DIAGNOSTICS

1510       Messages  are  sent  to  the  syslog  daemon using facility LOG_DAEMON.
1511       (This can be overridden by recompiling  pppd  with  the  macro  LOG_PPP
1512       defined  as the desired facility.)  See the syslog(8) documentation for
1513       details of where the syslog daemon will write the  messages.   On  most
1514       systems,  the  syslog  daemon uses the /etc/syslog.conf file to specify
1515       the destination(s) for syslog messages.  You may need to edit that file
1516       to suit.
1517
1518       The  debug  option  causes  the contents of all control packets sent or
1519       received to be logged, that is, all LCP, PAP, CHAP, EAP, or IPCP  pack‐
1520       ets.   This can be useful if the PPP negotiation does not succeed or if
1521       authentication fails.  If debugging is enabled  at  compile  time,  the
1522       debug option also causes other debugging messages to be logged.
1523
1524       Debugging  can  also be enabled or disabled by sending a SIGUSR1 signal
1525       to the pppd process.  This signal acts as a toggle.
1526

EXIT STATUS

1528       The exit status of pppd is  set  to  indicate  whether  any  error  was
1529       detected, or the reason for the link being terminated.  The values used
1530       are:
1531
1532       0      Pppd has detached, or otherwise the connection was  successfully
1533              established and terminated at the peer's request.
1534
1535       1      An  immediately  fatal  error  of some kind occurred, such as an
1536              essential system call failing, or running out of virtual memory.
1537
1538       2      An error was detected in processing the options given,  such  as
1539              two mutually exclusive options being used.
1540
1541       3      Pppd is not setuid-root and the invoking user is not root.
1542
1543       4      The  kernel  does  not  support PPP, for example, the PPP kernel
1544              driver is not included or cannot be loaded.
1545
1546       5      Pppd terminated because it was sent a SIGINT, SIGTERM or  SIGHUP
1547              signal.
1548
1549       6      The serial port could not be locked.
1550
1551       7      The serial port could not be opened.
1552
1553       8      The connect script failed (returned a non-zero exit status).
1554
1555       9      The  command  specified  as the argument to the pty option could
1556              not be run.
1557
1558       10     The PPP negotiation failed, that is, it didn't reach  the  point
1559              where at least one network protocol (e.g. IP) was running.
1560
1561       11     The peer system failed (or refused) to authenticate itself.
1562
1563       12     The  link was established successfully and terminated because it
1564              was idle.
1565
1566       13     The link was established successfully and terminated because the
1567              connect time limit was reached.
1568
1569       14     Callback  was  negotiated  and  an  incoming  call should arrive
1570              shortly.
1571
1572       15     The link was terminated because the peer is  not  responding  to
1573              echo requests.
1574
1575       16     The link was terminated by the modem hanging up.
1576
1577       17     The PPP negotiation failed because serial loopback was detected.
1578
1579       18     The init script failed (returned a non-zero exit status).
1580
1581       19     We failed to authenticate ourselves to the peer.
1582

SCRIPTS

1584       Pppd  invokes  scripts at various stages in its processing which can be
1585       used to perform site-specific ancillary processing.  These scripts  are
1586       usually  shell  scripts,  but  could  be executable code files instead.
1587       Pppd does not wait for the scripts to finish (except for the  ip-pre-up
1588       script).  The scripts are executed as root (with the real and effective
1589       user-id set to 0), so that they can do things such  as  update  routing
1590       tables  or  run  privileged  daemons.   Be careful that the contents of
1591       these scripts do not compromise your system's security.  Pppd runs  the
1592       scripts  with standard input, output and error redirected to /dev/null,
1593       and with an environment that is empty except for some environment vari‐
1594       ables  that give information about the link.  The environment variables
1595       that pppd sets are:
1596
1597       DEVICE The name of the serial tty device being used.
1598
1599       IFNAME The name of the network interface being used.
1600
1601       IPLOCAL
1602              The IP address for the local end of the link.  This is only  set
1603              when IPCP has come up.
1604
1605       IPREMOTE
1606              The IP address for the remote end of the link.  This is only set
1607              when IPCP has come up.
1608
1609       PEERNAME
1610              The authenticated name of the peer.  This is  only  set  if  the
1611              peer authenticates itself.
1612
1613       SPEED  The baud rate of the tty device.
1614
1615       ORIG_UID
1616              The real user-id of the user who invoked pppd.
1617
1618       PPPLOGNAME
1619              The  username  of  the  real  user-id that invoked pppd. This is
1620              always set.
1621
1622       For the ip-down and auth-down scripts, pppd  also  sets  the  following
1623       variables giving statistics for the connection:
1624
1625       CONNECT_TIME
1626              The  number  of  seconds  from  when the PPP negotiation started
1627              until the connection was terminated.
1628
1629       BYTES_SENT
1630              The number of bytes sent (at the level of the serial port)  dur‐
1631              ing the connection.
1632
1633       BYTES_RCVD
1634              The  number  of bytes received (at the level of the serial port)
1635              during the connection.
1636
1637       LINKNAME
1638              The logical name of the link, set with the linkname option.
1639
1640       DNS1   If the peer supplies DNS server addresses, this variable is  set
1641              to  the  first  DNS  server address supplied (whether or not the
1642              usepeerdns option was given).
1643
1644       DNS2   If the peer supplies DNS server addresses, this variable is  set
1645              to  the  second  DNS server address supplied (whether or not the
1646              usepeerdns option was given).
1647
1648       Pppd invokes the following scripts, if they exist.  It is not an  error
1649       if they don't exist.
1650
1651       /etc/ppp/auth-up
1652              A  program  or  script which is executed after the remote system
1653              successfully authenticates itself.   It  is  executed  with  the
1654              parameters
1655
1656              interface-name peer-name user-name tty-device speed
1657
1658              Note  that  this  script  is  not  executed  if the peer doesn't
1659              authenticate itself, for example when the noauth option is used.
1660
1661       /etc/ppp/auth-down
1662              A program or script which is executed when the link  goes  down,
1663              if  /etc/ppp/auth-up was previously executed.  It is executed in
1664              the same manner with the same parameters as /etc/ppp/auth-up.
1665
1666       /etc/ppp/ip-pre-up
1667              A program or script which is executed just before the  ppp  net‐
1668              work  interface  is  brought  up.   It is executed with the same
1669              parameters as the ip-up  script  (below).   At  this  point  the
1670              interface  exists  and  has  IP  addresses assigned but is still
1671              down.  This can be used to add  firewall  rules  before  any  IP
1672              traffic can pass through the interface.  Pppd will wait for this
1673              script to finish before  bringing  the  interface  up,  so  this
1674              script should run quickly.
1675
1676       /etc/ppp/ip-up
1677              A program or script which is executed when the link is available
1678              for sending and receiving IP packets (that  is,  IPCP  has  come
1679              up).  It is executed with the parameters
1680
1681              interface-name       tty-device      speed      local-IP-address
1682              remote-IP-address ipparam
1683
1684       /etc/ppp/ip-down
1685              A program or script which is executed when the link is no longer
1686              available for sending and receiving IP packets.  This script can
1687              be used for  undoing  the  effects  of  the  /etc/ppp/ip-up  and
1688              /etc/ppp/ip-pre-up  scripts.   It  is invoked in the same manner
1689              and with the same parameters as the ip-up script.
1690
1691       /etc/ppp/ipv6-up
1692              Like /etc/ppp/ip-up, except that it is executed when the link is
1693              available for sending and receiving IPv6 packets. It is executed
1694              with the parameters
1695
1696              interface-name   tty-device    speed    local-link-local-address
1697              remote-link-local-address ipparam
1698
1699       /etc/ppp/ipv6-down
1700              Similar  to /etc/ppp/ip-down, but it is executed when IPv6 pack‐
1701              ets can no longer be transmitted on the  link.  It  is  executed
1702              with the same parameters as the ipv6-up script.
1703
1704       /etc/ppp/ipx-up
1705              A program or script which is executed when the link is available
1706              for sending and receiving IPX packets (that is, IPXCP  has  come
1707              up).  It is executed with the parameters
1708
1709              interface-name       tty-device       speed       network-number
1710              local-IPX-node-address  remote-IPX-node-address  local-IPX-rout‐
1711              ing-protocol  remote-IPX-routing-protocol  local-IPX-router-name
1712              remote-IPX-router-name ipparam pppd-pid
1713
1714              The local-IPX-routing-protocol  and  remote-IPX-routing-protocol
1715              field may be one of the following:
1716
1717              NONE      to indicate that there is no routing protocol
1718              RIP       to indicate that RIP/SAP should be used
1719              NLSP      to indicate that Novell NLSP should be used
1720              RIP NLSP  to indicate that both RIP/SAP and NLSP should be used
1721
1722       /etc/ppp/ipx-down
1723              A program or script which is executed when the link is no longer
1724              available for sending and receiving IPX  packets.   This  script
1725              can  be  used  for  undoing  the  effects of the /etc/ppp/ipx-up
1726              script.  It is invoked in the same  manner  and  with  the  same
1727              parameters as the ipx-up script.
1728

FILES

1730       /var/run/pppn.pid (BSD or Linux), /etc/ppp/pppn.pid (others)
1731              Process-ID for pppd process on ppp interface unit n.
1732
1733       /var/run/ppp-name.pid (BSD or Linux),
1734              /etc/ppp/ppp-name.pid  (others)  Process-ID for pppd process for
1735              logical link name (see the linkname option).
1736
1737       /var/run/pppd2.tdb
1738              Database containing information about pppd processes, interfaces
1739              and links, used for matching links to bundles in multilink oper‐
1740              ation.  May be examined by external programs to obtain  informa‐
1741              tion  about  running  pppd instances, the interfaces and devices
1742              they    are    using,    IP    address     assignments,     etc.
1743              /etc/ppp/pap-secrets  Usernames,  passwords and IP addresses for
1744              PAP authentication.  This file should be owned by root  and  not
1745              readable or writable by any other user.  Pppd will log a warning
1746              if this is not the case.
1747
1748       /etc/ppp/chap-secrets
1749              Names,  secrets  and  IP  addresses  for  CHAP/MS-CHAP/MS-CHAPv2
1750              authentication.   As  for /etc/ppp/pap-secrets, this file should
1751              be owned by root and not readable or writable by any other user.
1752              Pppd will log a warning if this is not the case.
1753
1754       /etc/ppp/srp-secrets
1755              Names, secrets, and IP addresses for EAP authentication.  As for
1756              /etc/ppp/pap-secrets, this file should be owned by root and  not
1757              readable or writable by any other user.  Pppd will log a warning
1758              if this is not the case.
1759
1760       ~/.ppp_pseudonym
1761              Saved client-side SRP-SHA1 pseudonym.  See the srp-use-pseudonym
1762              option for details.
1763
1764       /etc/ppp/options
1765              System  default  options  for  pppd,  read  before  user default
1766              options or command-line options.
1767
1768       ~/.ppprc
1769              User default options, read before /etc/ppp/options.ttyname.
1770
1771       /etc/ppp/options.ttyname
1772              System default options for the  serial  port  being  used,  read
1773              after  ~/.ppprc.   In forming the ttyname part of this filename,
1774              an initial /dev/ is stripped from the port  name  (if  present),
1775              and any slashes in the remaining part are converted to dots.
1776
1777       /etc/ppp/peers
1778              A  directory  containing  options files which may contain privi‐
1779              leged options, even if pppd was invoked by  a  user  other  than
1780              root.  The system administrator can create options files in this
1781              directory to permit non-privileged users  to  dial  out  without
1782              requiring  the peer to authenticate, but only to certain trusted
1783              peers.
1784

SEE ALSO

1786       chat(8), pppstats(8)
1787
1788       RFC1144
1789              Jacobson, V.  Compressing TCP/IP headers  for  low-speed  serial
1790              links.  February 1990.
1791
1792       RFC1321
1793              Rivest, R.  The MD5 Message-Digest Algorithm.  April 1992.
1794
1795       RFC1332
1796              McGregor,  G.   PPP  Internet  Protocol Control Protocol (IPCP).
1797              May 1992.
1798
1799       RFC1334
1800              Lloyd, B.; Simpson, W.A.  PPP authentication protocols.  October
1801              1992.
1802
1803       RFC1661
1804              Simpson, W.A.  The Point-to-Point Protocol (PPP).  July 1994.
1805
1806       RFC1662
1807              Simpson, W.A.  PPP in HDLC-like Framing.  July 1994.
1808
1809       RFC2284
1810              Blunk,  L.; Vollbrecht, J., PPP Extensible Authentication Proto‐
1811              col (EAP).  March 1998.
1812
1813       RFC2472
1814              Haskin, D.  IP Version 6 over PPP December 1998.
1815
1816       RFC2945
1817              Wu, T., The SRP Authentication and Key Exchange System September
1818              2000.
1819
1820       draft-ietf-pppext-eap-srp-03.txt
1821              Carlson, J.; et al., EAP SRP-SHA1 Authentication Protocol.  July
1822              2001.
1823

NOTES

1825       Some limited degree of control can be exercised  over  a  running  pppd
1826       process by sending it a signal from the list below.
1827
1828       SIGINT, SIGTERM
1829              These signals cause pppd to terminate the link (by closing LCP),
1830              restore the serial device settings, and exit.  If a connector or
1831              disconnector  process  is  currently running, pppd will send the
1832              same signal to its process group, so as to terminate the connec‐
1833              tor or disconnector process.
1834
1835       SIGHUP This  signal  causes  pppd  to  terminate  the link, restore the
1836              serial device settings, and close the  serial  device.   If  the
1837              persist  or  demand  option has been specified, pppd will try to
1838              reopen the serial device and start another connection (after the
1839              holdoff  period).   Otherwise pppd will exit.  If this signal is
1840              received during the holdoff period, it causes pppd  to  end  the
1841              holdoff  period  immediately.   If  a  connector or disconnector
1842              process is running, pppd  will  send  the  same  signal  to  its
1843              process group.
1844
1845       SIGUSR1
1846              This signal toggles the state of the debug option.
1847
1848       SIGUSR2
1849              This signal causes pppd to renegotiate compression.  This can be
1850              useful to re-enable compression after it has been disabled as  a
1851              result  of  a  fatal  decompression error.  (Fatal decompression
1852              errors generally indicate a bug in one or other implementation.)
1853
1854

AUTHORS

1856       Paul Mackerras  (paulus@samba.org),  based  on  earlier  work  by  Drew
1857       Perkins, Brad Clements, Karl Fox, Greg Christy, and Brad Parker.
1858
1859
1861       Pppd  is  copyrighted and made available under conditions which provide
1862       that it may be copied and used in source or binary forms provided  that
1863       the  conditions  listed below are met.  Portions of pppd are covered by
1864       the following copyright notices:
1865
1866       Copyright  (c)  1984-2000  Carnegie  Mellon  University.   All   rights
1867       reserved.
1868       Copyright (c) 1993-2004 Paul Mackerras. All rights reserved.
1869       Copyright (c) 1995 Pedro Roque Marques.  All rights reserved.
1870       Copyright (c) 1995 Eric Rosenquist.  All rights reserved.
1871       Copyright (c) 1999 Tommi Komulainen.  All rights reserved.
1872       Copyright (C) Andrew Tridgell 1999
1873       Copyright (c) 2000 by Sun Microsystems, Inc.  All rights reserved.
1874       Copyright (c) 2001 by Sun Microsystems, Inc.  All rights reserved.
1875       Copyright (c) 2002 Google, Inc.  All rights reserved.
1876
1877       The copyright notices contain the following statements.
1878
1879       Redistribution and use in source and binary forms, with or without mod‐
1880       ification, are permitted provided that  the  following  conditions  are
1881       met:
1882
1883       1. Redistributions of source code must retain the above copyright
1884          notice, this list of conditions and the following disclaimer.
1885
1886       2. Redistributions in binary form must reproduce the above copyright
1887          notice, this list of conditions and the following disclaimer in
1888          the documentation and/or other materials provided with the
1889          distribution.
1890
1891       3. The name "Carnegie Mellon University" must not be used to
1892          endorse or promote products derived from this software without
1893          prior written permission. For permission or any legal
1894          details, please contact
1895            Office of Technology Transfer
1896            Carnegie Mellon University
1897            5000 Forbes Avenue
1898            Pittsburgh, PA  15213-3890
1899            (412) 268-4387, fax: (412) 268-7395
1900            tech-transfer@andrew.cmu.edu
1901
1902       3b. The name(s) of the authors of this software must not be used to
1903          endorse or promote products derived from this software without
1904          prior written permission.
1905
1906       4. Redistributions of any form whatsoever must retain the following
1907          acknowledgements:
1908          "This product includes software developed by Computing Services
1909           at Carnegie Mellon University (http://www.cmu.edu/computing/)."
1910          "This product includes software developed by Paul Mackerras
1911           <paulus@samba.org>".
1912          "This product includes software developed by Pedro Roque Marques
1913           <pedro_m@yahoo.com>".
1914          "This product includes software developed by Tommi Komulainen
1915           <Tommi.Komulainen@iki.fi>".
1916
1917       CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
1918       SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND  FIT‐
1919       NESS,  IN  NO  EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE FOR ANY
1920       SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR  ANY  DAMAGES  WHATSOEVER
1921       RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
1922       CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING  OUT  OF  OR  IN
1923       CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1924
1925       THE  AUTHORS  OF  THIS  SOFTWARE DISCLAIM ALL WARRANTIES WITH REGARD TO
1926       THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY  AND
1927       FITNESS, IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDI‐
1928       RECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING  FROM
1929       LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLI‐
1930       GENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR  IN  CONNECTION  WITH
1931       THE USE OR PERFORMANCE OF THIS SOFTWARE.
1932
1933
1934
1935                                                                       PPPD(8)
Impressum