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 be‐
19       sides 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  en‐
43              coded  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 de‐
101              fault value of -1, the route is only added if there  is  no  de‐
102              fault 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       replacedefaultroute
112              This  option  is  a flag to the defaultroute option. If default‐
113              route is set and this flag is also set, pppd replaces an  exist‐
114              ing  default  route  with the new default route.  This option is
115              privileged.
116
117       disconnect script
118              Execute the command specified by script,  by  passing  it  to  a
119              shell,  after pppd has terminated the link.  This command could,
120              for example, issue commands to the modem to cause it to hang  up
121              if  hardware modem control signals were not available.  The dis‐
122              connect script is not run if the modem has already hung  up.   A
123              value  for  this option from a privileged source cannot be over‐
124              ridden by a non-privileged user.
125
126       escape xx,yy,...
127              Specifies that certain characters should be escaped on transmis‐
128              sion (regardless of whether the peer requests them to be escaped
129              with its async control character map).  The characters to be es‐
130              caped  are  specified as a list of hex numbers separated by com‐
131              mas.  Note that almost any character can be  specified  for  the
132              escape option, unlike the asyncmap option which only allows con‐
133              trol characters to be specified.  The characters which  may  not
134              be escaped are those with hex values 0x20 - 0x3f or 0x5e.
135
136       file name
137              Read  options  from  file  name (the format is described below).
138              The file must be readable by the user who has invoked pppd.
139
140       init script
141              Execute the command specified by script,  by  passing  it  to  a
142              shell,  to  initialize the serial line.  This script would typi‐
143              cally use the chat(8) program to configure the modem  to  enable
144              auto  answer.   A value for this option from a privileged source
145              cannot be overridden by a non-privileged user.
146
147       lock   Specifies that pppd should create a UUCP-style lock file for the
148              serial  device to ensure exclusive access to the device.  By de‐
149              fault, pppd will not create a lock file.
150
151       mru n  Set the MRU [Maximum Receive Unit] value to n. Pppd will ask the
152              peer  to  send  packets of no more than n bytes.  The value of n
153              must be between 128 and 16384; the default is 1500.  A value  of
154              296  works well on very slow links (40 bytes for TCP/IP header +
155              256 bytes of data).  Note that for the IPv6  protocol,  the  MRU
156              must be at least 1280.
157
158       mtu n  Set the MTU [Maximum Transmit Unit] value to n.  Unless the peer
159              requests a smaller value via MRU negotiation, pppd will  request
160              that  the  kernel  networking  code send data packets of no more
161              than n bytes through the PPP network interface.  Note  that  for
162              the IPv6 protocol, the MTU must be at least 1280.
163
164       passive
165              Enables the "passive" option in the LCP.  With this option, pppd
166              will attempt to initiate a connection; if no reply  is  received
167              from  the  peer,  pppd will then just wait passively for a valid
168              LCP packet from the peer, instead of exiting, as it would  with‐
169              out this option.
170

OPTIONS

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

PPPOE OPTIONS

1196       To establish PPP link over Ethernet (PPPoE) it is needed to load pppd's
1197       plugin  pppoe.so and then specify option nic-interface instead of modem
1198       options ttyname and speed.  Recognized pppd's PPPoE options are:
1199
1200       nic-interface
1201              Use the ethernet device interface to communicate with the  peer.
1202              For  example,  establishing PPPoE link on eth0 interface is done
1203              by specifying ppp'd option nic-eth0. Prefix nic- for this option
1204              may  be  avoided  if  interface name is unambiguous and does not
1205              look like any other pppd's option.
1206
1207       pppoe-service name
1208              Connect to specified PPPoE service name. For  backward  compati‐
1209              bility also rp_pppoe_service option name is supported.
1210
1211       pppoe-ac name
1212              Connect  to  specified PPPoE access concentrator name. For back‐
1213              ward compatibility also rp_pppoe_ac option name is supported.
1214
1215       pppoe-sess sessid:macaddr
1216              Attach to existing PPPoE  session.  For  backward  compatibility
1217              also rp_pppoe_sess option name is supported.
1218
1219       pppoe-verbose n
1220              Be  verbose  about discovered access concentrators. For backward
1221              compatibility also rp_pppoe_verbose option name is supported.
1222
1223       pppoe-mac macaddr
1224              Connect to specified MAC address.
1225
1226       pppoe-host-uniq string
1227              Set the PPPoE Host-Uniq tag to the supplied hex string.  By  de‐
1228              fault PPPoE Host-Uniq tag is set to the pppd's process PID.  For
1229              backward compatibility this option may be specified without  pp‐
1230              poe- prefix.
1231
1232       pppoe-padi-timeout n
1233              Initial timeout for discovery packets in seconds (default 5).
1234
1235       pppoe-padi-attempts n
1236              Number of discovery attempts (default 3).
1237

OPTIONS FILES

1239       Options  can  be  taken  from  files as well as the command line.  Pppd
1240       reads  options  from   the   files   /etc/ppp/options,   ~/.ppprc   and
1241       /etc/ppp/options.ttyname  (in that order) before processing the options
1242       on the command line.  (In fact, the command-line options are scanned to
1243       find  the  terminal  name before the options.ttyname file is read.)  In
1244       forming the name of the options.ttyname file, the initial /dev/ is  re‐
1245       moved  from  the  terminal name, and any remaining / characters are re‐
1246       placed with dots.
1247
1248       An options file is parsed into a series of words, delimited  by  white‐
1249       space.   Whitespace  can be included in a word by enclosing the word in
1250       double-quotes (").  A backslash (\) quotes the following character.   A
1251       hash  (#)  starts a comment, which continues until the end of the line.
1252       There is no restriction on using the file or call options within an op‐
1253       tions file.
1254

SECURITY

1256       pppd provides system administrators with sufficient access control that
1257       PPP access to a server machine can  be  provided  to  legitimate  users
1258       without  fear of compromising the security of the server or the network
1259       it's on.  This control is provided through restrictions on which IP ad‐
1260       dresses the peer may use, based on its authenticated identity (if any),
1261       and through restrictions on which options  a  non-privileged  user  may
1262       use.   Several  of  pppd's  options are privileged, in particular those
1263       which permit potentially insecure  configurations;  these  options  are
1264       only accepted in files which are under the control of the system admin‐
1265       istrator, or if pppd is being run by root.
1266
1267       The default behaviour of pppd is to allow an  unauthenticated  peer  to
1268       use a given IP address only if the system does not already have a route
1269       to that IP address.  For example, a system with a permanent  connection
1270       to  the wider internet will normally have a default route, and thus all
1271       peers will have to authenticate themselves in order to set up a connec‐
1272       tion.   On such a system, the auth option is the default.  On the other
1273       hand, a system where the PPP link is the only connection to the  inter‐
1274       net will not normally have a default route, so the peer will be able to
1275       use almost any IP address without authenticating itself.
1276
1277       As indicated above, some  security-sensitive  options  are  privileged,
1278       which  means  that  they  may not be used by an ordinary non-privileged
1279       user running a setuid-root pppd, either on the  command  line,  in  the
1280       user's ~/.ppprc file, or in an options file read using the file option.
1281       Privileged options may be used in /etc/ppp/options file or  in  an  op‐
1282       tions  file  read  using  the call option.  If pppd is being run by the
1283       root user, privileged options can be used without restriction.
1284
1285       When opening the device, pppd uses either the invoking user's  user  ID
1286       or  the root UID (that is, 0), depending on whether the device name was
1287       specified by the user or the system administrator.  If the device  name
1288       comes from a privileged source, that is, /etc/ppp/options or an options
1289       file read using the call option, pppd uses full  root  privileges  when
1290       opening  the  device.   Thus,  by  creating  an  appropriate file under
1291       /etc/ppp/peers, the system administrator can allow users to establish a
1292       ppp  connection via a device which they would not normally have permis‐
1293       sion to access.  Otherwise pppd uses the invoking user's real UID  when
1294       opening the device.
1295

AUTHENTICATION

1297       Authentication  is  the process whereby one peer convinces the other of
1298       its identity.  This involves the first peer sending  its  name  to  the
1299       other,  together  with some kind of secret information which could only
1300       come from the genuine authorized user of that name.   In  such  an  ex‐
1301       change,  we  will  call  the  first peer the "client" and the other the
1302       "server".  The client has a name by which it identifies itself  to  the
1303       server, and the server also has a name by which it identifies itself to
1304       the client.  Generally the genuine client shares some secret (or  pass‐
1305       word)  with  the  server,  and  authenticates itself by proving that it
1306       knows that secret.  Very often, the names used for authentication  cor‐
1307       respond  to the internet hostnames of the peers, but this is not essen‐
1308       tial.
1309
1310       At present, pppd supports three authentication protocols: the  Password
1311       Authentication  Protocol (PAP), Challenge Handshake Authentication Pro‐
1312       tocol (CHAP), and Extensible Authentication Protocol  (EAP).   PAP  in‐
1313       volves  the  client  sending  its  name and a cleartext password to the
1314       server to authenticate itself.  In contrast, the server  initiates  the
1315       CHAP  authentication exchange by sending a challenge to the client (the
1316       challenge packet includes the server's name).  The client must  respond
1317       with  a response which includes its name plus a hash value derived from
1318       the shared secret and the challenge, in order to prove  that  it  knows
1319       the  secret.  EAP supports CHAP-style authentication, and also includes
1320       the SRP-SHA1 mechanism, which is resistant to dictionary-based  attacks
1321       and does not require a cleartext password on the server side.
1322
1323       The  PPP  protocol, being symmetrical, allows both peers to require the
1324       other to authenticate itself.  In that case, two separate and  indepen‐
1325       dent  authentication exchanges will occur.  The two exchanges could use
1326       different authentication protocols, and in principle,  different  names
1327       could be used in the two exchanges.
1328
1329       The default behaviour of pppd is to agree to authenticate if requested,
1330       and to not require authentication from the peer.   However,  pppd  will
1331       not  agree  to authenticate itself with a particular protocol if it has
1332       no secrets which could be used to do so.
1333
1334       Pppd  stores  secrets  for  use  in  authentication  in  secrets  files
1335       (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP, MS-CHAP,
1336       MS-CHAPv2, and EAP  MD5-Challenge,  and  /etc/ppp/srp-secrets  for  EAP
1337       SRP-SHA1).   All secrets files have the same format.  The secrets files
1338       can contain secrets for pppd to use in authenticating itself  to  other
1339       systems,  as  well as secrets for pppd to use when authenticating other
1340       systems to itself.
1341
1342       Each line in a secrets file contains one secret.   A  given  secret  is
1343       specific to a particular combination of client and server - it can only
1344       be used by that client to authenticate itself  to  that  server.   Thus
1345       each  line  in  a  secrets  file has at least 3 fields: the name of the
1346       client, the name of the server, and the secret.  These  fields  may  be
1347       followed  by  a  list of the IP addresses that the specified client may
1348       use when connecting to the specified server.
1349
1350       A secrets file is parsed into words as  for  a  options  file,  so  the
1351       client name, server name and secrets fields must each be one word, with
1352       any embedded spaces or other  special  characters  quoted  or  escaped.
1353       Note that case is significant in the client and server names and in the
1354       secret.
1355
1356       If the secret starts with an `@', what follows is  assumed  to  be  the
1357       name  of  a file from which to read the secret.  A "*" as the client or
1358       server name matches any name.  When selecting a secret, pppd takes  the
1359       best match, i.e.  the match with the fewest wildcards.
1360
1361       Any  following words on the same line are taken to be a list of accept‐
1362       able IP addresses for that client.  If there are only 3  words  on  the
1363       line,  or  if  the  first word is "-", then all IP addresses are disal‐
1364       lowed.  To allow any address, use "*".  A word starting with "!"  indi‐
1365       cates  that the specified address is not acceptable.  An address may be
1366       followed by "/" and a number n, to indicate a whole  subnet,  i.e.  all
1367       addresses which have the same value in the most significant n bits.  In
1368       this form, the address may be followed by a plus sign ("+") to indicate
1369       that  one  address from the subnet is authorized, based on the ppp net‐
1370       work interface unit number in use.  In this case, the host part of  the
1371       address will be set to the unit number plus one.
1372
1373       Thus  a  secrets  file  contains both secrets for use in authenticating
1374       other hosts, plus secrets which we use for authenticating ourselves  to
1375       others.   When  pppd  is  authenticating  the peer (checking the peer's
1376       identity), it chooses a secret with the peer's name in the first  field
1377       and  the name of the local system in the second field.  The name of the
1378       local system defaults to the hostname, with the domain name appended if
1379       the  domain  option  is  used.  This default can be overridden with the
1380       name option, except when the usehostname  option  is  used.   (For  EAP
1381       SRP-SHA1,  see the srp-entry(8) utility for generating proper validator
1382       entries to be used in the "secret" field.)
1383
1384       When pppd is choosing a secret to use in authenticating itself  to  the
1385       peer,  it first determines what name it is going to use to identify it‐
1386       self to the peer.  This name can be specified by the user with the user
1387       option.   If  this option is not used, the name defaults to the name of
1388       the local system, determined as described in  the  previous  paragraph.
1389       Then  pppd looks for a secret with this name in the first field and the
1390       peer's name in the second field.  Pppd will know the name of  the  peer
1391       if CHAP or EAP authentication is being used, because the peer will have
1392       sent it in the challenge packet.  However, if PAP is being  used,  pppd
1393       will  have  to  determine the peer's name from the options specified by
1394       the user.  The user can specify the peer's name directly with  the  re‐
1395       motename  option.  Otherwise, if the remote IP address was specified by
1396       a name (rather than in numeric form), that name will  be  used  as  the
1397       peer's name.  Failing that, pppd will use the null string as the peer's
1398       name.
1399
1400       When authenticating the peer with PAP, the supplied password  is  first
1401       compared  with  the  secret  from  the  secrets  file.  If the password
1402       doesn't match the secret, the password is encrypted using  crypt()  and
1403       checked  against the secret again.  Thus secrets for authenticating the
1404       peer can be stored in encrypted form if desired.  If the  papcrypt  op‐
1405       tion  is given, the first (unencrypted) comparison is omitted, for bet‐
1406       ter security.
1407
1408       Furthermore, if the login option was specified, the username and  pass‐
1409       word  are also checked against the system password database.  Thus, the
1410       system administrator can set up the pap-secrets file to allow  PPP  ac‐
1411       cess  only  to  certain  users, and to restrict the set of IP addresses
1412       that each user can use.  Typically, when using the  login  option,  the
1413       secret  in /etc/ppp/pap-secrets would be "", which will match any pass‐
1414       word supplied by the peer.  This avoids the need to have the  same  se‐
1415       cret in two places.
1416
1417       Authentication  must  be  satisfactorily  completed before IPCP (or any
1418       other Network Control Protocol) can be started.  If  the  peer  is  re‐
1419       quired to authenticate itself, and fails to do so, pppd will terminated
1420       the link (by closing LCP).  If IPCP negotiates an unacceptable  IP  ad‐
1421       dress for the remote host, IPCP will be closed.  IP packets can only be
1422       sent or received when IPCP is open.
1423
1424       In some cases it is desirable to allow some hosts which can't authenti‐
1425       cate  themselves  to  connect and use one of a restricted set of IP ad‐
1426       dresses, even when the local host  generally  requires  authentication.
1427       If  the  peer refuses to authenticate itself when requested, pppd takes
1428       that as equivalent to authenticating with PAP using  the  empty  string
1429       for  the  username and password.  Thus, by adding a line to the pap-se‐
1430       crets file which specifies the empty string for the  client  and  pass‐
1431       word,  it  is possible to allow restricted access to hosts which refuse
1432       to authenticate themselves.
1433

ROUTING

1435       When IPCP negotiation is completed successfully, pppd will  inform  the
1436       kernel  of  the  local  and  remote IP addresses for the ppp interface.
1437       This is sufficient to create a host route to  the  remote  end  of  the
1438       link,  which  will enable the peers to exchange IP packets.  Communica‐
1439       tion with other machines generally  requires  further  modification  to
1440       routing  tables  and/or  ARP  (Address Resolution Protocol) tables.  In
1441       most cases the defaultroute and/or proxyarp options are sufficient  for
1442       this,  but  in  some  cases  further  intervention  is  required.   The
1443       /etc/ppp/ip-up script can be used for this.
1444
1445       Sometimes it is desirable to add a default  route  through  the  remote
1446       host, as in the case of a machine whose only connection to the Internet
1447       is through the ppp interface.  The defaultroute option causes  pppd  to
1448       create  such a default route when IPCP comes up, and delete it when the
1449       link is terminated.
1450
1451       In some cases it is desirable to use proxy ARP, for example on a server
1452       machine  connected  to a LAN, in order to allow other hosts to communi‐
1453       cate with the remote host.  The proxyarp option causes pppd to look for
1454       a network interface on the same subnet as the remote host (an interface
1455       supporting broadcast and ARP, which is up and not a  point-to-point  or
1456       loopback interface).  If found, pppd creates a permanent, published ARP
1457       entry with the IP address of the remote host and the  hardware  address
1458       of the network interface found.
1459
1460       When the demand option is used, the interface IP addresses have already
1461       been set at the point when IPCP comes up.  If pppd has not been able to
1462       negotiate  the  same  addresses that it used to configure the interface
1463       (for example when the peer is an ISP that uses dynamic IP  address  as‐
1464       signment), pppd has to change the interface IP addresses to the negoti‐
1465       ated addresses.  This may disrupt existing connections, and the use  of
1466       demand dialling with peers that do dynamic IP address assignment is not
1467       recommended.
1468
1470       Multilink PPP provides the capability to combine two or more PPP  links
1471       between  a  pair of machines into a single `bundle', which appears as a
1472       single virtual PPP link which has the combined bandwidth of  the  indi‐
1473       vidual links.  Currently, multilink PPP is only supported under Linux.
1474
1475       Pppd  detects  that the link it is controlling is connected to the same
1476       peer as another link using the peer's endpoint  discriminator  and  the
1477       authenticated  identity  of the peer (if it authenticates itself).  The
1478       endpoint discriminator is a block of data which is hopefully unique for
1479       each  peer.   Several  types of data can be used, including locally-as‐
1480       signed strings of bytes, IP addresses, MAC addresses, randomly  strings
1481       of  bytes,  or E-164 phone numbers.  The endpoint discriminator sent to
1482       the peer by pppd can be set using the endpoint option.
1483
1484       In some circumstances the peer may send no endpoint discriminator or  a
1485       non-unique  value.   The  bundle  option  adds an extra string which is
1486       added to the peer's endpoint discriminator and  authenticated  identity
1487       when  matching  up links to be joined together in a bundle.  The bundle
1488       option can also be used to allow the establishment of multiple  bundles
1489       between  the  local  system  and the peer.  Pppd uses a TDB database in
1490       /var/run/pppd2.tdb to match up links.
1491
1492       Assuming that multilink is enabled and the peer is willing to negotiate
1493       multilink,  then when pppd is invoked to bring up the first link to the
1494       peer, it will detect that no other link is connected to  the  peer  and
1495       create a new bundle, that is, another ppp network interface unit.  When
1496       another pppd is invoked to bring up another link to the peer,  it  will
1497       detect the existing bundle and join its link to it.
1498
1499       If the first link terminates (for example, because of a hangup or a re‐
1500       ceived LCP terminate-request) the bundle is not destroyed unless  there
1501       are  no  other links remaining in the bundle.  Rather than exiting, the
1502       first pppd keeps running after its link terminates, until all the links
1503       in the bundle have terminated.  If the first pppd receives a SIGTERM or
1504       SIGINT signal, it will destroy the bundle and send a SIGHUP to the pppd
1505       processes  for  each of the links in the bundle.  If the first pppd re‐
1506       ceives a SIGHUP signal, it will terminate its link but not the bundle.
1507
1508       Note: demand mode is not currently supported with multilink.
1509

EXAMPLES

1511       The following examples assume that the /etc/ppp/options  file  contains
1512       the  auth  option  (as  in the default /etc/ppp/options file in the ppp
1513       distribution).
1514
1515       Probably the most common use of pppd is to dial out to  an  ISP.   This
1516       can be done with a command such as
1517
1518              pppd call isp
1519
1520       where the /etc/ppp/peers/isp file is set up by the system administrator
1521       to contain something like this:
1522
1523              ttyS0 19200 crtscts
1524              connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp'
1525              noauth
1526
1527       In this example, we are using chat to  dial  the  ISP's  modem  and  go
1528       through  any  logon sequence required.  The /etc/ppp/chat-isp file con‐
1529       tains the script used by chat; it could for example  contain  something
1530       like this:
1531
1532              ABORT "NO CARRIER"
1533              ABORT "NO DIALTONE"
1534              ABORT "ERROR"
1535              ABORT "NO ANSWER"
1536              ABORT "BUSY"
1537              ABORT "Username/Password Incorrect"
1538              "" "at"
1539              OK "at&d0&c1"
1540              OK "atdt2468135"
1541              "name:" "^Umyuserid"
1542              "word:" "\qmypassword"
1543              "ispts" "\q^Uppp"
1544              "~-^Uppp-~"
1545
1546       See the chat(8) man page for details of chat scripts.
1547
1548       Pppd  can  also be used to provide a dial-in ppp service for users.  If
1549       the users already have login accounts, the simplest way to set  up  the
1550       ppp  service  is to let the users log in to their accounts and run pppd
1551       (installed setuid-root) with a command such as
1552
1553              pppd proxyarp
1554
1555       To allow a user to use the PPP facilities, you need to allocate  an  IP
1556       address for that user's machine and create an entry in /etc/ppp/pap-se‐
1557       crets, /etc/ppp/chap-secrets,  or  /etc/ppp/srp-secrets  (depending  on
1558       which  authentication  method  the PPP implementation on the user's ma‐
1559       chine supports), so that the user's machine  can  authenticate  itself.
1560       For example, if Joe has a machine called "joespc" that is to be allowed
1561       to dial in to the machine called "server" and use the IP  address  joe‐
1562       spc.my.net, you would add an entry like this to /etc/ppp/pap-secrets or
1563       /etc/ppp/chap-secrets:
1564
1565              joespc    server    "joe's secret" joespc.my.net
1566
1567       (See srp-entry(8) for a means  to  generate  the  server's  entry  when
1568       SRP-SHA1  is  in use.)  Alternatively, you can create a username called
1569       (for example) "ppp", whose login shell is pppd and whose home directory
1570       is  /etc/ppp.   Options to be used when pppd is run this way can be put
1571       in /etc/ppp/.ppprc.
1572
1573       If your serial connection is any more complicated than a piece of wire,
1574       you  may need to arrange for some control characters to be escaped.  In
1575       particular, it is often useful to escape XON (^Q) and XOFF (^S),  using
1576       asyncmap a0000.  If the path includes a telnet, you probably should es‐
1577       cape ^] as well (asyncmap 200a0000).  If the path includes  an  rlogin,
1578       you  will  need to use the escape ff option on the end which is running
1579       the rlogin client, since many rlogin implementations are not  transpar‐
1580       ent; they will remove the sequence [0xff, 0xff, 0x73, 0x73, followed by
1581       any 8 bytes] from the stream.
1582

DIAGNOSTICS

1584       Messages are sent to  the  syslog  daemon  using  facility  LOG_DAEMON.
1585       (This  can be overridden by recompiling pppd with the macro LOG_PPP de‐
1586       fined as the desired facility.)  See the  syslog(8)  documentation  for
1587       details  of  where  the syslog daemon will write the messages.  On most
1588       systems, the syslog daemon uses the /etc/syslog.conf  file  to  specify
1589       the destination(s) for syslog messages.  You may need to edit that file
1590       to suit.
1591
1592       The debug option causes the contents of all control packets sent or re‐
1593       ceived to be logged, that is, all LCP, PAP, CHAP, EAP, or IPCP packets.
1594       This can be useful if the PPP negotiation does not succeed  or  if  au‐
1595       thentication fails.  If debugging is enabled at compile time, the debug
1596       option also causes other debugging messages to be logged.
1597
1598       Debugging can also be enabled or disabled by sending a  SIGUSR1  signal
1599       to the pppd process.  This signal acts as a toggle.
1600

EXIT STATUS

1602       The  exit  status  of pppd is set to indicate whether any error was de‐
1603       tected, or the reason for the link being terminated.  The  values  used
1604       are:
1605
1606       0      Pppd  has detached, or otherwise the connection was successfully
1607              established and terminated at the peer's request.
1608
1609       1      An immediately fatal error of some kind occurred, such as an es‐
1610              sential system call failing, or running out of virtual memory.
1611
1612       2      An  error  was detected in processing the options given, such as
1613              two mutually exclusive options being used.
1614
1615       3      Pppd is not setuid-root and the invoking user is not root.
1616
1617       4      The kernel does not support PPP, for  example,  the  PPP  kernel
1618              driver is not included or cannot be loaded.
1619
1620       5      Pppd  terminated because it was sent a SIGINT, SIGTERM or SIGHUP
1621              signal.
1622
1623       6      The serial port could not be locked.
1624
1625       7      The serial port could not be opened.
1626
1627       8      The connect script failed (returned a non-zero exit status).
1628
1629       9      The command specified as the argument to the  pty  option  could
1630              not be run.
1631
1632       10     The  PPP  negotiation failed, that is, it didn't reach the point
1633              where at least one network protocol (e.g. IP) was running.
1634
1635       11     The peer system failed (or refused) to authenticate itself.
1636
1637       12     The link was established successfully and terminated because  it
1638              was idle.
1639
1640       13     The link was established successfully and terminated because the
1641              connect time limit was reached.
1642
1643       14     Callback was negotiated  and  an  incoming  call  should  arrive
1644              shortly.
1645
1646       15     The  link  was  terminated because the peer is not responding to
1647              echo requests.
1648
1649       16     The link was terminated by the modem hanging up.
1650
1651       17     The PPP negotiation failed because serial loopback was detected.
1652
1653       18     The init script failed (returned a non-zero exit status).
1654
1655       19     We failed to authenticate ourselves to the peer.
1656

SCRIPTS

1658       Pppd invokes scripts at various stages in its processing which  can  be
1659       used  to perform site-specific ancillary processing.  These scripts are
1660       usually shell scripts, but could  be  executable  code  files  instead.
1661       Pppd  does not wait for the scripts to finish (except for the ip-pre-up
1662       script).  The scripts are executed as root (with the real and effective
1663       user-id  set  to  0), so that they can do things such as update routing
1664       tables or run privileged daemons.  Be  careful  that  the  contents  of
1665       these  scripts do not compromise your system's security.  Pppd runs the
1666       scripts with standard input, output and error redirected to  /dev/null,
1667       and with an environment that is empty except for some environment vari‐
1668       ables that give information about the link.  The environment  variables
1669       that pppd sets are:
1670
1671       DEVICE The name of the serial tty device being used.
1672
1673       IFNAME The name of the network interface being used.
1674
1675       IPLOCAL
1676              The  IP address for the local end of the link.  This is only set
1677              when IPCP has come up.
1678
1679       IPREMOTE
1680              The IP address for the remote end of the link.  This is only set
1681              when IPCP has come up.
1682
1683       PEERNAME
1684              The  authenticated  name  of  the peer.  This is only set if the
1685              peer authenticates itself.
1686
1687       SPEED  The baud rate of the tty device.
1688
1689       ORIG_UID
1690              The real user-id of the user who invoked pppd.
1691
1692       PPPLOGNAME
1693              The username of the real user-id that invoked pppd. This is  al‐
1694              ways set.
1695
1696       For  the  ip-down  and  auth-down scripts, pppd also sets the following
1697       variables giving statistics for the connection:
1698
1699       CONNECT_TIME
1700              The number of seconds from when the PPP negotiation started  un‐
1701              til the connection was terminated.
1702
1703       BYTES_SENT
1704              The  number of bytes sent (at the level of the serial port) dur‐
1705              ing the connection.
1706
1707       BYTES_RCVD
1708              The number of bytes received (at the level of the  serial  port)
1709              during the connection.
1710
1711       LINKNAME
1712              The logical name of the link, set with the linkname option.
1713
1714       CALL_FILE
1715              The value of the call option.
1716
1717       DNS1   If  the peer supplies DNS server addresses, this variable is set
1718              to the first DNS server address supplied  (whether  or  not  the
1719              usepeerdns option was given).
1720
1721       DNS2   If  the peer supplies DNS server addresses, this variable is set
1722              to the second DNS server address supplied (whether  or  not  the
1723              usepeerdns option was given).
1724
1725       Pppd  invokes the following scripts, if they exist.  It is not an error
1726       if they don't exist.
1727
1728       /etc/ppp/auth-up
1729              A program or script which is executed after  the  remote  system
1730              successfully  authenticates itself.  It is executed with the pa‐
1731              rameters
1732
1733              interface-name peer-name user-name tty-device speed
1734
1735              Note that this script is not executed if the  peer  doesn't  au‐
1736              thenticate itself, for example when the noauth option is used.
1737
1738       /etc/ppp/auth-down
1739              A  program  or script which is executed when the link goes down,
1740              if /etc/ppp/auth-up was previously executed.  It is executed  in
1741              the same manner with the same parameters as /etc/ppp/auth-up.
1742
1743       /etc/ppp/ip-pre-up
1744              A  program  or script which is executed just before the ppp net‐
1745              work interface is brought up.  It is executed with the same  pa‐
1746              rameters  as the ip-up script (below).  At this point the inter‐
1747              face exists and has IP addresses assigned  but  is  still  down.
1748              This can be used to add firewall rules before any IP traffic can
1749              pass through the interface.  Pppd will wait for this  script  to
1750              finish  before  bringing the interface up, so this script should
1751              run quickly.
1752
1753       /etc/ppp/ip-up
1754              A program or script which is executed when the link is available
1755              for  sending  and  receiving  IP packets (that is, IPCP has come
1756              up).  It is executed with the parameters
1757
1758              interface-name tty-device speed  local-IP-address  remote-IP-ad‐
1759              dress ipparam
1760
1761       /etc/ppp/ip-down
1762              A program or script which is executed when the link is no longer
1763              available for sending and receiving IP packets.  This script can
1764              be  used  for  undoing  the  effects  of  the /etc/ppp/ip-up and
1765              /etc/ppp/ip-pre-up scripts.  It is invoked in  the  same  manner
1766              and with the same parameters as the ip-up script.
1767
1768       /etc/ppp/ipv6-up
1769              Like /etc/ppp/ip-up, except that it is executed when the link is
1770              available for sending and receiving IPv6 packets. It is executed
1771              with the parameters
1772
1773              interface-name  tty-device  speed  local-link-local-address  re‐
1774              mote-link-local-address ipparam
1775
1776       /etc/ppp/ipv6-down
1777              Similar to /etc/ppp/ip-down, but it is executed when IPv6  pack‐
1778              ets  can  no  longer  be transmitted on the link. It is executed
1779              with the same parameters as the ipv6-up script.
1780
1781       /etc/ppp/ipx-up
1782              A program or script which is executed when the link is available
1783              for  sending  and receiving IPX packets (that is, IPXCP has come
1784              up).  It is executed with the parameters
1785
1786              interface-name    tty-device    speed     network-number     lo‐
1787              cal-IPX-node-address   remote-IPX-node-address   local-IPX-rout‐
1788              ing-protocol  remote-IPX-routing-protocol  local-IPX-router-name
1789              remote-IPX-router-name ipparam pppd-pid
1790
1791              The  local-IPX-routing-protocol  and remote-IPX-routing-protocol
1792              field may be one of the following:
1793
1794              NONE      to indicate that there is no routing protocol
1795              RIP       to indicate that RIP/SAP should be used
1796              NLSP      to indicate that Novell NLSP should be used
1797              RIP NLSP  to indicate that both RIP/SAP and NLSP should be used
1798
1799       /etc/ppp/ipx-down
1800              A program or script which is executed when the link is no longer
1801              available  for  sending  and receiving IPX packets.  This script
1802              can be used for  undoing  the  effects  of  the  /etc/ppp/ipx-up
1803              script.   It is invoked in the same manner and with the same pa‐
1804              rameters as the ipx-up script.
1805

FILES

1807       /var/run/pppn.pid (BSD or Linux), /etc/ppp/pppn.pid (others)
1808              Process-ID for pppd process on ppp interface unit n.
1809
1810       /var/run/ppp-name.pid (BSD or Linux),
1811              /etc/ppp/ppp-name.pid (others) Process-ID for pppd  process  for
1812              logical link name (see the linkname option).
1813
1814       /var/run/pppd2.tdb
1815              Database containing information about pppd processes, interfaces
1816              and links, used for matching links to bundles in multilink oper‐
1817              ation.   May be examined by external programs to obtain informa‐
1818              tion about running pppd instances, the  interfaces  and  devices
1819              they  are  using, IP address assignments, etc.  /etc/ppp/pap-se‐
1820              crets Usernames, passwords and IP addresses for PAP  authentica‐
1821              tion.   This  file  should  be owned by root and not readable or
1822              writable by any other user.  Pppd will log a warning if this  is
1823              not the case.
1824
1825       /etc/ppp/chap-secrets
1826              Names,  secrets  and IP addresses for CHAP/MS-CHAP/MS-CHAPv2 au‐
1827              thentication.  As for /etc/ppp/pap-secrets, this file should  be
1828              owned  by  root  and not readable or writable by any other user.
1829              Pppd will log a warning if this is not the case.
1830
1831       /etc/ppp/srp-secrets
1832              Names, secrets, and IP addresses for EAP authentication.  As for
1833              /etc/ppp/pap-secrets,  this file should be owned by root and not
1834              readable or writable by any other user.  Pppd will log a warning
1835              if this is not the case.
1836
1837       ~/.ppp_pseudonym
1838              Saved client-side SRP-SHA1 pseudonym.  See the srp-use-pseudonym
1839              option for details.
1840
1841       /etc/ppp/options
1842              System default options for pppd, read before  user  default  op‐
1843              tions or command-line options.
1844
1845       ~/.ppprc
1846              User default options, read before /etc/ppp/options.ttyname.
1847
1848       /etc/ppp/options.ttyname
1849              System  default options for the serial port being used, read af‐
1850              ter ~/.ppprc.  In forming the ttyname part of this filename,  an
1851              initial  /dev/  is stripped from the port name (if present), and
1852              any slashes in the remaining part are converted to dots.
1853
1854       /etc/ppp/peers
1855              A directory containing options files which  may  contain  privi‐
1856              leged  options,  even  if  pppd was invoked by a user other than
1857              root.  The system administrator can create options files in this
1858              directory to permit non-privileged users to dial out without re‐
1859              quiring the peer to authenticate, but only  to  certain  trusted
1860              peers.
1861

SEE ALSO

1863       chat(8), pppstats(8)
1864
1865       RFC1144
1866              Jacobson,  V.   Compressing  TCP/IP headers for low-speed serial
1867              links.  February 1990.
1868
1869       RFC1321
1870              Rivest, R.  The MD5 Message-Digest Algorithm.  April 1992.
1871
1872       RFC1332
1873              McGregor, G.  PPP Internet  Protocol  Control  Protocol  (IPCP).
1874              May 1992.
1875
1876       RFC1334
1877              Lloyd, B.; Simpson, W.A.  PPP authentication protocols.  October
1878              1992.
1879
1880       RFC1661
1881              Simpson, W.A.  The Point-to-Point Protocol (PPP).  July 1994.
1882
1883       RFC1662
1884              Simpson, W.A.  PPP in HDLC-like Framing.  July 1994.
1885
1886       RFC1990
1887              Sklower, K.; et al., The PPP Multilink  Protocol  (MP).   August
1888              1996.
1889
1890       RFC2284
1891              Blunk,  L.; Vollbrecht, J., PPP Extensible Authentication Proto‐
1892              col (EAP).  March 1998.
1893
1894       RFC2472
1895              Haskin, D.  IP Version 6 over PPP December 1998.
1896
1897       RFC2945
1898              Wu, T., The SRP Authentication and Key Exchange System September
1899              2000.
1900
1901       draft-ietf-pppext-eap-srp-03.txt
1902              Carlson, J.; et al., EAP SRP-SHA1 Authentication Protocol.  July
1903              2001.
1904

NOTES

1906       Some limited degree of control can be exercised  over  a  running  pppd
1907       process by sending it a signal from the list below.
1908
1909       SIGINT, SIGTERM
1910              These signals cause pppd to terminate the link (by closing LCP),
1911              restore the serial device settings, and exit.  If a connector or
1912              disconnector  process  is  currently running, pppd will send the
1913              same signal to its process group, so as to terminate the connec‐
1914              tor or disconnector process.
1915
1916       SIGHUP This  signal  causes pppd to terminate the link, restore the se‐
1917              rial device settings, and close the serial device.  If the  per‐
1918              sist  or  demand option has been specified, pppd will try to re‐
1919              open the serial device and start another connection  (after  the
1920              holdoff  period).   Otherwise pppd will exit.  If this signal is
1921              received during the holdoff period, it causes pppd  to  end  the
1922              holdoff  period  immediately.   If  a  connector or disconnector
1923              process is running, pppd  will  send  the  same  signal  to  its
1924              process group.
1925
1926       SIGUSR1
1927              This signal toggles the state of the debug option.
1928
1929       SIGUSR2
1930              This signal causes pppd to renegotiate compression.  This can be
1931              useful to re-enable compression after it has been disabled as  a
1932              result of a fatal decompression error.  (Fatal decompression er‐
1933              rors generally indicate a bug in one or other implementation.)
1934
1935

AUTHORS

1937       Paul Mackerras  (paulus@samba.org),  based  on  earlier  work  by  Drew
1938       Perkins, Brad Clements, Karl Fox, Greg Christy, and Brad Parker.
1939
1940
1942       Pppd  is  copyrighted and made available under conditions which provide
1943       that it may be copied and used in source or binary forms provided  that
1944       the  conditions  listed below are met.  Portions of pppd are covered by
1945       the following copyright notices:
1946
1947       Copyright (c) 1984-2000 Carnegie  Mellon  University.  All  rights  re‐
1948       served.
1949       Copyright (c) 1993-2004 Paul Mackerras. All rights reserved.
1950       Copyright (c) 1995 Pedro Roque Marques.  All rights reserved.
1951       Copyright (c) 1995 Eric Rosenquist.  All rights reserved.
1952       Copyright (c) 1999 Tommi Komulainen.  All rights reserved.
1953       Copyright (C) Andrew Tridgell 1999
1954       Copyright (c) 2000 by Sun Microsystems, Inc.  All rights reserved.
1955       Copyright (c) 2001 by Sun Microsystems, Inc.  All rights reserved.
1956       Copyright (c) 2002 Google, Inc.  All rights reserved.
1957
1958       The copyright notices contain the following statements.
1959
1960       Redistribution and use in source and binary forms, with or without mod‐
1961       ification, are permitted provided that  the  following  conditions  are
1962       met:
1963
1964       1. Redistributions of source code must retain the above copyright
1965          notice, this list of conditions and the following disclaimer.
1966
1967       2. Redistributions in binary form must reproduce the above copyright
1968          notice, this list of conditions and the following disclaimer in
1969          the documentation and/or other materials provided with the
1970          distribution.
1971
1972       3. The name "Carnegie Mellon University" must not be used to
1973          endorse or promote products derived from this software without
1974          prior written permission. For permission or any legal
1975          details, please contact
1976            Office of Technology Transfer
1977            Carnegie Mellon University
1978            5000 Forbes Avenue
1979            Pittsburgh, PA  15213-3890
1980            (412) 268-4387, fax: (412) 268-7395
1981            tech-transfer@andrew.cmu.edu
1982
1983       3b. The name(s) of the authors of this software must not be used to
1984          endorse or promote products derived from this software without
1985          prior written permission.
1986
1987       4. Redistributions of any form whatsoever must retain the following
1988          acknowledgements:
1989          "This product includes software developed by Computing Services
1990           at Carnegie Mellon University (http://www.cmu.edu/computing/)."
1991          "This product includes software developed by Paul Mackerras
1992           <paulus@samba.org>".
1993          "This product includes software developed by Pedro Roque Marques
1994           <pedro_m@yahoo.com>".
1995          "This product includes software developed by Tommi Komulainen
1996           <Tommi.Komulainen@iki.fi>".
1997
1998       CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
1999       SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND  FIT‐
2000       NESS,  IN  NO  EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE FOR ANY
2001       SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR  ANY  DAMAGES  WHATSOEVER
2002       RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
2003       CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING  OUT  OF  OR  IN
2004       CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
2005
2006       THE  AUTHORS  OF  THIS  SOFTWARE DISCLAIM ALL WARRANTIES WITH REGARD TO
2007       THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY  AND
2008       FITNESS, IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDI‐
2009       RECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING  FROM
2010       LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLI‐
2011       GENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR  IN  CONNECTION  WITH
2012       THE USE OR PERFORMANCE OF THIS SOFTWARE.
2013
2014
2015
2016                                                                       PPPD(8)
Impressum