MyWebUniversity.com Home Page

OpenSolaris man pages main menu


System Administration Commands                           pppd(1M)



NAME
     pppd - point to point protocol daemon

SYNOPSIS
     pppd [ttyname] [speed] [options]


DESCRIPTION
     The point-to-point protocol  (P)  provides  a  method  for
     transmitting datagrams over serial point-to-point links. P
     is composed of three components: a facility for  encapsulat-
     ing  datagrams over serial links, an extensible link control
     protocol (LCP), and a family of  network  control  protocols
     (NCP)  for  establishing  and configuring different network-
     layer protocols.


     The encapsulation scheme is provided by driver code  in  the
     kernel.  pppd  provides the basic LCP authentication support
     and several NCPs for establishing and configuring the Inter-
     net  Protocol  (referred  to  as  the IP Control Protocol or
     "IPCP") and IPv6 (IPV6CP).

OPTIONS
     The following sections discuss the pppd options:

  Options Files
     Options are taken from files  and  the  command  line.  pppd
     reads  options from the files /etc/ppp/options, $HOME/.ppprc
     and /etc/ppp/options.ttyname (in that order) before process-
     ing  the  options on the command line. (Command-line options
     are scanned for the terminal name before the options.ttyname
     file is read.) To form the name of the options.ttyname file,
     the initial /dev/ is removed from the terminal name, and any
     remaining  forward  slash  characters  (/) are replaced with
     dots. For example, with  serial  device  /dev/cua/a,  option
     file /etc/ppp/options.cua.a is read.


     An options file is parsed into a series of  words  that  are
     delimited  by  whitespace.  Whitespace  can be included in a
     word by enclosing the word in double-quotes ("). A backslash
     (\)  quotes  the  succeeding  character. A hash (#) starts a
     comment, which continues until the end of the line. There is
     no  restriction  on using the file or call options within an
     options file.

  Frequently Used Options
                  Communicate over  the  named  device.
                            The  string  /dev/  is  prepended  if
                            necessary.  If  no  device  name   is
                            given, or if the name of the terminal



SunOS 5.11          Last change: 21 Nov 2001                    1






System Administration Commands                           pppd(1M)



                            connected to the  standard  input  is
                            given,  pppd  uses  that terminal and
                            does not fork to put  itself  in  the
                            background.  A  value for this option
                            from a privileged  source  cannot  be
                            overridden by a non-privileged user.


                     Set  the  baud  rate  to    (a
                            decimal  number).  The  default is to
                            leave the baud rate  unchanged.  This
                            option  is  normally needed for dial-
                            out only.


     asyncmap          Set the async character map to .
                            The map describes which control char-
                            acters   cannot    be    successfully
                            received  over  the serial line. pppd
                            asks the peer to send  these  charac-
                            ters as a 2-byte escape sequence. The
                            argument is a 32 bit hex number, with
                            each  bit representing a character to
                            escape. Bit 0  (00000001)  represents
                            the character 0x00; bit 31 (80000000)
                            represents the character 0x1f or  ^.
                            If   multiple  asyncmap  options  are
                            given, the values are ORed  together.
                            If  no asyncmap option is given, pppd
                            attempts to negotiate a value  of  0.
                            If  the  peer  agrees,  this disables
                            escaping  of  the  standard   control
                            characters.  Use the default-asyncmap
                            option  to  disable  negotiation  and
                            escape all control characters.


     auth                   Require  the  peer  to   authenticate
                            itself  before allowing network pack-
                            ets to  be  sent  or  received.  This
                            option  is  the default if the system
                            has a default route. If the  auth  or
                            the  noauth  option is not specified,
                            pppd allows  the  peer  to  use  only
                            those  IP addresses to which the sys-
                            tem does not already have a route.


     call name              Read   options    from    the    file
                            /etc/ppp/peers/name.  This  file  may
                            contain privileged options, including
                            noauth, even if pppd is not being run



SunOS 5.11          Last change: 21 Nov 2001                    2






System Administration Commands                           pppd(1M)



                            by root.  The  name  string  may  not
                            begin  with  a slash ("/") or include
                            consecutive periods ("..") as a path-
                            name component.


     callback number        Request a callback to the given tele-
                            phone number using Microsoft CBCP.


     connect script         Use the executable or  shell  command
                            specified  by  script  to  set up the
                            serial line. This script would  typi-
                            cally  use  the  chat(1M)  program to
                            dial the modem and start  the  remote
                            P  session. A value for this option
                            originating from a privileged  source
                            cannot   be   overridden  by  a  non-
                            privileged user.


     crtscts                Use hardware flow control,  that  is,
                            RTS/CTS,  to control the flow of data
                            on the serial port. If  the  crtscts,
                            nocrtscts,   cdtrcts   or   nocdtrcts
                            option is not provided, the  hardware
                            flow  control  setting for the serial
                            port is left unchanged.  Some  serial
                            ports  lack a true RTS output and use
                            this mode to implement unidirectional
                            flow   control.   The   serial   port
                            suspends transmission when  requested
                            by the modem by means of CTS but can-
                            not request the modem to stop sending
                            to the computer. This mode allows the
                            use of DTR as a modem control line.


     defaultroute           Add a default  route  to  the  system
                            routing  tables when IPCP negotiation
                            successfully  completes,  using   the
                            peer  as  the  gateway. This entry is
                            removed when the  P  connection  is
                            broken.  This option is privileged if
                            the nodefaultroute option  is  speci-
                            fied.


     disconnect  script     Run the executable or  shell  command
                            specified  by  script after pppd ter-
                            minates  the  link.  Typically,  this
                            script  is  used to command the modem



SunOS 5.11          Last change: 21 Nov 2001                    3






System Administration Commands                           pppd(1M)



                            to hang up if hardware modem  control
                            signals are not available. disconnect
                            is not run if the modem  has  already
                            hung up. A value for this option ori-
                            ginating  from  a  privileged  source
                            cannot   be   overridden  by  a  non-
                            privileged user.


     escape xx,yy,...       Specifies that certain characters  be
                            escaped on transmission regardless of
                            whether the peer requests them to  be
                            escaped  with its async control char-
                            acter  map.  The  characters  to   be
                            escaped  are  specified  as a list of
                            hex numbers separated by commas. Note
                            that  almost  any  character  can  be
                            specified  for  the  escape   option,
                            unlike   the  asyncmap  option  which
                            allows only control characters to  be
                            specified.  Characters that cannot be
                            escaped  are  those  containing   hex
                            values 0x20 through 0x3f and 0x5e.


     file name              Read options from file name. If  this
                            option is used on the command line or
                            in $HOME/.ppprc,  the  file  must  be
                            readable  by  the user invoking pppd.
                            See  for a list of  files  that  pppd
                            always  reads,  regardless of the use
                            of this option.


     init  script           Run the executable or  shell  command
                            specified by script to initialize the
                            serial line. This script would  typi-
                            cally  use  the  chat(1M)  program to
                            configure the modem to  enable  auto-
                            answer.  A value for this option from
                            a privileged source cannot  be  over-
                            ridden by a non-privileged user.


     lock                   Directs pppd to create  a  UCP-style
                            lock  file  for  the serial device to
                            ensure exclusive access to  the  dev-
                            ice.


     mru n                  Set the Maximum  Receive  Unit  (MRU)
                            value  to  n.  pppd  asks the peer to



SunOS 5.11          Last change: 21 Nov 2001                    4






System Administration Commands                           pppd(1M)



                            send packets of no more than n bytes.
                            Minimum MRU value is 128. Default MRU
                            value is 1500.  A  value  of  296  is
                            recommended  for slow links (40 bytes
                            for TCP/IP  header  ]  256  bytes  of
                            data). For IPv6, MRU must be at least
                            1280.


     mtu n                  Set the Maximum Transmit  Unit  (MTU)
                            value  to n. Unless the peer requests
                            a smaller value via MRU  negotiation,
                            pppd  requests  the kernel networking
                            code to send data packets of no  more
                            than  n bytes through the P network
                            interface. For IPv6, MTU must  be  at
                            least 1280.


     passive                Enables the "passive" option  in  the
                            LCP.  With this option, pppd attempts
                            to initiate a connection; if no reply
                            is received from the peer, pppd waits
                            passively  for  a  valid  LCP  packet
                            instead   of  exiting,  as  it  would
                            without this option.


  Options
     :

         Set the local  and/or  remote  interface  IP  addresses.
         Either  one  may  be omitted, but the colon is required.
         The IP addresses are specified with a host  name  or  in
         decimal   dot  notation,  for  example:  :10.1.2.3.  The
         default local address is the first  IP  address  of  the
         system  unless  the  noipdefault option is provided. The
         remote address is obtained from the peer if  not  speci-
         fied  in  any option. Thus, in simple cases, this option
         is not required. If a local and/or remote IP address  is
         specified  with this option, pppd will not accept a dif-
         ferent value from  the  peer  in  the  IPCP  negotiation
         unless  the  ipcp-accept-local and/or ipcp-accept-remote
         options are given, respectively.


     allow-fcs fcs-type

         Set allowable FCS type(s) for data sent to the peer. The
         fcs-type  is a comma-separated list of "crc16", "crc32",
         "null", or integers. By default,  all  known  types  are
         allowed.  If  this  option  is  specified  and  the peer



SunOS 5.11          Last change: 21 Nov 2001                    5






System Administration Commands                           pppd(1M)



         requests a type not listed, a LCP Configure-Nak is  sent
         to request only the listed types.


     allow-ip address(es)

         Allow peers to  use  the  given  IP  address  or  subnet
         without  authenticating  themselves.  The  parameter  is
         parsed in the same manner as each element of the list of
         allowed IP addresses is parsed in the secrets files. See
         the  section more more details.


     bsdcomp nr,nt

         Request that the peer compress  packets  that  it  sends
         using  the BSD-Compress scheme, with a maximum code size
         of nr bits, and agree to compress packets  sent  to  the
         peer  with  a maximum code size of nt bits. If nt is not
         specified, it defaults to the value given for nr. Values
         in  the  range 9 to 15 may be used for nr and nt; larger
         values provide better compression but consume more  ker-
         nel  memory for compression dictionaries. Alternatively,
         a value of 0 for nr or nt disables  compression  in  the
         corresponding  direction.  Use nobsdcomp or bsdcomp 0 to
         disable  BSD-Compress  compression  entirely.  If   this
         option is read from a privileged source, a nonprivileged
         user may not specify a code size larger than  the  value
         from the privileged source.


     cdtrcts

         Use a non-standard hardware flow control such as DTR/CTS
         to  control  the flow of data on the serial port. If the
         crtscts, nocrtscts, cdtrcts or nocdtrcts option  is  not
         specified,  the  hardware  flow  control setting for the
         serial port is left unchanged. Some serial ports lack  a
         true  RTS  output.  Such  serial  ports use this mode to
         implement true bi-directional flow  control.  Note  that
         this  flow  control  mode does not permit using DTR as a
         modem control line.


     chap-interval n

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


     chap-max-challenge n




SunOS 5.11          Last change: 21 Nov 2001                    6






System Administration Commands                           pppd(1M)



         Set the maximum number of CHAP  challenge  transmissions
         to n (default 10).


     chap-restart n

         Set the CHAP restart  interval  (retransmission  timeout
         for challenges) to n seconds. The default is 3.


     connect-delay n

         Wait for up to n milliseconds after the  connect  script
         finishes  for a valid P packet from the peer. When the
         wait period elapses  or  when  a  valid  P  packet  is
         received from the peer, pppd begins negotiation by send-
         ing its first LCP packet. The default value is  1000  (1
         second).  A  wait  period applies only if the connect or
         pty option is used.


     datarate n

         Set maximum data rate to n (in bytes  per  second)  when
         using the pty, notty, record, or socket options.


     debug

         Enables connection debugging facilities. If this  option
         is  given, pppd logs the contents of all control packets
         sent or received in a readable  form.  The  packets  are
         logged  through  syslog  with  facility daemon and level
         debug. This information can be directed  to  a  file  by
         configuring /etc/syslog.conf appropriately.


     default-asyncmap

         Disable asyncmap negotiation, forcing all control  char-
         acters  to  be  escaped  for  both  the transmit and the
         receive direction.


     default-fcs

         Disable  FCS  Alternatives  negotiation   entirely.   By
         default, no FCS Alternatives option is sent to the peer,
         but the option is accepted. If this option is  specified
         by the peer, then LCP Configure-Reject is sent.





SunOS 5.11          Last change: 21 Nov 2001                    7






System Administration Commands                           pppd(1M)



     default-mru

         Disable MRU [Maximum  Receive  Unit]  negotiation.  With
         this  option,  pppd  uses  the default MRU value of 1500
         bytes for the transmit and receive directions.


     deflate nr,nt,e

         Request that the peer compress packets  that  it  sends,
         using  the deflate scheme, with a maximum window size of
         2**nr bytes, and agree to compress packets sent  to  the
         peer  with  a  maximum  window  size  of 2**nt bytes and
         effort level of e (1 to 9). If nt is not  specified,  it
         defaults  to  the value given for nr. If e is not speci-
         fied, it defaults to 6. Values in the range 9 to 15  may
         be  used  for  nr  and  nt; larger values provide better
         compression but consume more kernel memory for  compres-
         sion  dictionaries.  (Value  8 is not permitted due to a
         zlib bug.) Alternatively, a value of 0 for nr or nt dis-
         ables  compression  in  the corresponding direction. Use
         nodeflate or deflate 0 to  disable  deflate  compression
         entirely.  (Note:  pppd  requests deflate compression in
         preference to BSD-Compress if the peer can  do  either.)
         If  this  option  is  read  from  a privileged source, a
         nonprivileged user may not specify a  code  size  larger
         than the value from the privileged source.


     demand

         Initiate the link only on demand,  that  is,  when  data
         traffic  is  present.  With  this  option, the remote IP
         address must be specified by the  user  on  the  command
         line  or  in  an options file. pppd initially configures
         and enables the interface for IP  traffic  without  con-
         necting  to  the  peer.  When traffic is available, pppd
         connects to the peer and performs negotiation, authenti-
         cation  and  other  actions. When completed, pppd passes
         data packets across the link. The demand option  implies
         the persist option. If this behavior is not desired, use
         the nopersist option after the demand option.  The  idle
         and  holdoff options can be used in conjunction with the
         demand option.


     domain d

         Append the domain name d to  the  local  host  name  for
         authentication  purposes.  For example, if gethostname()
         returns the name porsche, but the fully qualified domain
         name  is  porsche.Quotron.COM,  you could specify domain



SunOS 5.11          Last change: 21 Nov 2001                    8






System Administration Commands                           pppd(1M)



         Quotron.COM. With this configuration, pppd uses the name
         porsche.Quotron.COM for accessing secrets in the secrets
         file and as the default name when authenticating to  the
         peer. This option is privileged.


     endpoint endpoint-value

         Set the endpoint discriminator (normally  used  for  RFC
         1990  Multilink  P operation). The endpoint-value con-
         sists of a class identifier and a class-dependent value.
         The  class  identifier  is one of "null," "local," "IP,"
         "MAC,"  "magic,"  "phone,"  or  a  decimal  integer.  If
         present, the class-dependent value is separated from the
         identifier by a colon (":") or period (".") . This value
         may  be  a  standard dotted-decimal IP address for class
         "IP," an optionally colon-or-dot separated hex  Ethernet
         address  for  class  "MAC"  (must have 6 numbers), or an
         arbitrary string of bytes specified in hex with optional
         colon  or  dot  separators  between bytes. Although this
         option is available, this implementation does  not  sup-
         port multilink.


     fcs fcs-type

         Set FCS type(s) desired for data sent by the  peer.  The
         fcs-type  is  a  comma-separated  list  of crc16, crc32,
         null, or  integers.  By  default,  an  FCS  Alternatives
         option  is  not  specified, and the medium-dependent FCS
         type is used. If this option is specified and  the  peer
         sends  an  LCP  Configure-Nak, only the listed types are
         used. If none are in common, the FCS Alternatives option
         is  omitted  from the next LCP Configure-Request to drop
         back to the default.


     hide-password

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


     holdoff n

         Specifies how many seconds to wait before  re-initiating
         the  link  after it terminates. This option is effective
         only if the persist or demand option is used. The  hold-
         off  period  is  not  applied  if the link is terminated
         because it was idle.




SunOS 5.11          Last change: 21 Nov 2001                    9






System Administration Commands                           pppd(1M)



     ident string

         Set the LCP Identification string. The default value  is
         a  version  string  similar  to that displayed by the --
         version option.


     idle n

         Specifies that pppd must disconnect if the link is  idle
         for  n  seconds.  The  link is idle when no data packets
         (i.e. IP packets) are being sent or received. Do not use
         this  option  with  the  persist  option but without the
         demand option.


     ipcp-accept-local

         With this option, pppd accepts the peer's  idea  of  the
         local IP address, even if the local IP address is speci-
         fied in an option.


     ipcp-accept-remote

         With this option, pppd accepts the peer's  idea  of  its
         remote  IP  address,  even  if  the remote IP address is
         specified in an option.


     ipcp-max-configure n

         Set  the  maximum  number  of   IPCP   Configure-Request
         transmissions to n (default 10).


     ipcp-max-failure n

         Set the  maximum  number  of  IPCP  Configure-NAKs  sent
         before  sending  Configure-Rejects instead to n (default
         10).


     ipcp-max-terminate n

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


     ipcp-restart n

         Set the IPCP restart interval  (retransmission  timeout)



SunOS 5.11          Last change: 21 Nov 2001                   10






System Administration Commands                           pppd(1M)



         to n seconds (default 3).


     ipparam string

         Provides an extra parameter to  the  ip-up  and  ip-down
         scripts.  When this option is given, the string supplied
         is given as the sixth parameter to  those  scripts.  See
         the  section.


     ipv6
     ,

         Set the local and/or remote 64-bit interface identifier.
         Either one may be omitted. The identifier must be speci-
         fied in standard ASCI notation of IPv6  addresses  (for
         example:  ::dead:beef).  If the ipv6cp-use-ipaddr option
         is given, the local and remote identifiers  are  derived
         from  the  respective  IPv4  addresses  (see above). The
         ipv6cp-use-persistent option can be used instead of  the
         ipv6 , option.


     ipv6cp-accept-local

         Accept peer's interface identifier for  the  local  link
         identifier.


     ipv6cp-max-configure n

         Set  the  maximum  number  of  IPv6CP  Configure-Request
         transmissions to n (default 10).


     ipv6cp-max-failure n

         Set the maximum number  of  IPv6CP  Configure-NAKs  sent
         before  sending  Configure-Rejects instead to n (default
         10).


     ipv6cp-max-terminate n

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


     ipv6cp-restart n

         Set the IPv6CP restart interval (retransmission timeout)



SunOS 5.11          Last change: 21 Nov 2001                   11






System Administration Commands                           pppd(1M)



         to n seconds (default 3).


     ipv6cp-use-ipaddr

         If either the local or remote IPv6 address  is  unspeci-
         fied, use the corresponding configured IPv4 address as a
         default interface identifier. (This option uses the con-
         figured  addresses, not the negotiated addresses. Do not
         use it with ipcp-accept-local if the local IPv6 identif-
         ier  is  unspecified  or  with ipcp-accept-remote if the
         remote IPv6 identifier is unspecified.)


     ipv6cp-use-persistent

         Use uniquely-available persistent value for  link  local
         address.


     kdebug n

         Enable debugging code in the  kernel-level  P  driver.
         Argument  n  is  the  sum  of the following values: 1 to
         enable general debug messages, 2 to  request  that  con-
         tents  of  received packets be printed, and 4 to request
         contents of transmitted  packets  be  printed.  Messages
         printed  by  the  kernel  are logged by syslogd(1M) to a
         file  directed  in  the  /etc/syslog.conf  configuration
         file.  Do  not  use  the  kdebug  option to debug failed
         links. Use the debug option instead.


     lcp-echo-failure n

         If this option is given, pppd presumes the  peer  to  be
         dead if n LCP Echo-Requests are sent without receiving a
         valid LCP Echo-Reply. If this happens,  pppd  terminates
         the  connection.  This  option requires a non-zero value
         for the lcp-echo-interval parameter. This option enables
         pppd  to terminate after the physical connection is bro-
         ken (for example, if the modem has hung  up)  in  situa-
         tions  where  no hardware modem control lines are avail-
         able.


     lcp-echo-interval n

         If this option is given, pppd sends an LCP  Echo-Request
         frame  to  the  peer  every n seconds. Normally the peer
         responds to the Echo-Request by sending  an  Echo-Reply.
         This option can be used with the lcp-echo-failure option



SunOS 5.11          Last change: 21 Nov 2001                   12






System Administration Commands                           pppd(1M)



         to detect that the peer is no longer connected.


     lcp-max-configure n

         Set  the  maximum  number   of   LCP   Configure-Request
         transmissions to n (default 10).


     lcp-max-failure n

         Set the maximum number of LCP Configure-NAKs sent before
         starting to send Configure-Rejects instead to n (default
         10).


     lcp-max-terminate n

         Set  the  maximum  number   of   LCP   Terminate-Request
         transmissions to n (default 3).


     lcp-restart n

         Set the LCP restart interval (retransmission timeout) to
         n seconds (default 3).


     linkname name

         Sets the logical name of the link to name. pppd  creates
         a  file  named  ppp-name.pid  in /var/run containing its
         process ID. This is useful in determining which instance
         of pppd is responsible for the link to a given peer sys-
         tem. This is a privileged option.


     local

         Do not use modem control lines. With this  option,  pppd
         ignores the state of the CD (Carrier Detect) signal from
         the modem and does not change the state of the DTR (Data
         Terminal Ready) signal.


     logfd n

         Send log messages to file descriptor n. pppd  sends  log
         messages  to  (at  most) one file or file descriptor (as
         well as sending the log messages  to  syslog),  so  this
         option and the logfile option are mutually exclusive. By
         default  pppd  sends  log  messages  to   stdout   (file



SunOS 5.11          Last change: 21 Nov 2001                   13






System Administration Commands                           pppd(1M)



         descriptor 1) unless the serial port is open on stdout.


     logfile filename

         Append log messages to the file filename (and  send  the
         log  messages  to  syslog). The file is opened in append
         mode with the privileges of the user who invoked pppd.


     login

         Use the system password database for authenticating  the
         peer  using  PAP, and record the user in the system wtmp
         file. Note that the peer  must  have  an  entry  in  the
         /etc/ppp/pap-secrets  file and the system password data-
         base to be allowed access.


     maxconnect n

         Terminate the connection after it has been available for
         network  traffic for n seconds (that is, n seconds after
         the first  network  control  protocol  starts).  An  LCP
         Time-Remaining  message  is  sent  when  the  first  NCP
         starts, and again when 5, 2, and 0.5 minutes are remain-
         ing.


     maxfail n

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


     modem

         Use the modem control lines. This option is the default.
         With this option, pppd waits for the CD (Carrier Detect)
         signal from the modem to be asserted  when  opening  the
         serial  device  (unless  a connect script is specified),
         and drops the DTR (Data Terminal Ready)  signal  briefly
         when  the  connection is terminated and before executing
         the connect script.


     ms-dns 

         If pppd is acting as  a  server  for  Microsoft  Windows
         clients,  this  option  allows pppd to supply one or two
         DNS (Domain Name Server) addresses to the  clients.  The



SunOS 5.11          Last change: 21 Nov 2001                   14






System Administration Commands                           pppd(1M)



         first  instance of this option specifies the primary DNS
         address; the second instance (if  given)  specifies  the
         secondary DNS address. If the first instance specifies a
         name that resolves to multiple IP  addresses,  then  the
         first two addresses are used. (This option is present in
         some older versions of pppd under the name dns-addr.)


     ms-lanman

         If pppd connects as a client to a Microsoft  server  and
         uses  MS-CHAPv1  for authentication, this option selects
         the LAN Manager password style instead of Microsoft NT.


     ms-wins 

         If pppd acts as a server for Microsoft Windows or  Samba
         clients,  this  option  allows pppd to supply one or two
         WINS (Windows Internet Name Services)  server  addresses
         to the clients. The first instance of this option speci-
         fies the primary WINS address; the second  instance  (if
         given)  specifies  the  secondary  WINS address. As with
         ms-dns, if the name specified resolves  to  multiple  IP
         addresses,  then  the first two will be taken as primary
         and secondary.


     name name

         Set the name of the local system for authentication pur-
         poses  to  name.  This is a privileged option. With this
         option, pppd uses lines in the secrets files  that  have
         name  as the second field to look for a secret to use in
         authenticating the peer. In addition, unless  overridden
         with  the  user option, name is used as the name to send
         to the peer when authenticating the local system.  (Note
         that pppd does not append the domain name to name.)


     no-accm-test

         Disable use of asyncmap (ACM) checking using LCP  Echo-
         Request  messages. If the lcp-echo-failure is used on an
         asynchronous line, pppd includes all control  characters
         in  the first n LCP Echo-Request messages. If the async-
         map is set incorrectly, the link drops rather than  con-
         tinue  operation  with random failures. This option dis-
         ables that feature.






SunOS 5.11          Last change: 21 Nov 2001                   15






System Administration Commands                           pppd(1M)



     noaccomp

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


     noauth

         Do not require the peer  to  authenticate  itself.  This
         option is privileged.


     nobsdcomp

         Disables BSD-Compress compression; pppd will not request
         or  agree  to  compress  packets  using the BSD-Compress
         scheme. This option is not necessary if noccp is  speci-
         fied.


     noccp

         Disable CP (Compression Control Protocol)  negotiation.
         This option should only be required if the peer has bugs
         or becomes confused by requests from pppd for CP  nego-
         tiation.  If  CP  is  disabled,  then  BSD  and deflate
         compression do not need to be separately disabled.


     nocrtscts

         Disable hardware flow  control  (i.e.  RTS/CTS)  on  the
         serial  port.  If  the  crtscts,  nocrtscts,  cdtrcts or
         nocdtrcts options are not given, the hardware flow  con-
         trol setting for the serial port is left unchanged.


     nocdtrcts

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


     nodefaultroute

         Disable the defaultroute option. You  can  prevent  non-
         root  users  from  creating  default routes with pppd by
         placing this option in the /etc/ppp/options file.


     nodeflate




SunOS 5.11          Last change: 21 Nov 2001                   16






System Administration Commands                           pppd(1M)



         Disables deflate compression; pppd will not  request  or
         agree to compress packets using the deflate scheme. This
         option is not necessary if noccp is specified.


     nodeflatedraft

         Do not use Internet Draft (incorrectly  assigned)  algo-
         rithm number for deflate compression. This option is not
         necessary if noccp is specified.


     nodetach

         Do not detach from  the  controlling  terminal.  Without
         this  option,  pppd forks to become a background process
         if a serial device other than the terminal on the  stan-
         dard input is specified.


     noendpoint

         Do not send or accept the Multilink Endpoint Discrimina-
         tor option.


     noident

         Disable use of LCP  Identification.  LCP  Identification
         messages will not be sent to the peer, but received mes-
         sages will be logged. (Specify this option twice to com-
         pletely  disable  LCP Identification. In this case, pppd
         sends LCP Code-Reject in response to received LCP  Iden-
         tification messages.)


     noip

         Disable IPCP negotiation and IP communication. Use  this
         option  only if the peer has bugs or becomes confused by
         requests from pppd for IPCP negotiation.


     noipv6

         Disable IPv6CP negotiation and IPv6 communication.  IPv6
         is not enabled by default.


     noipdefault

         Disables the default behavior when no local  IP  address



SunOS 5.11          Last change: 21 Nov 2001                   17






System Administration Commands                           pppd(1M)



         is  specified,  which  is to determine (if possible) the
         local IP address from the hostname.  With  this  option,
         the  peer  must  supply the local IP address during IPCP
         negotiation (unless it specified explicitly on the  com-
         mand line or in an options file).


     nolog

         Do not send log messages to a file or  file  descriptor.
         This  option  cancels  the  logfd  and  logfile options.
         nologfd acts as an alias for this option.


     nomagic

         Disable magic number negotiation. With this option, pppd
         cannot  detect  a looped-back line. Use this option only
         if the peer has bugs. Do not use  this  option  to  work
         around the "Serial line is looped back" error message.


     nopam

         This privileged option disables use of pluggable authen-
         tication  modules.  If  this  option  is specified, pppd
         reverts  to  standard  authentication  mechanisms.   The
         default is not to use PAM.


     nopcomp

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


     nopersist

         Exit once a connection has  been  made  and  terminated.
         This  is the default unless the persist or demand option
         is specified.


     noplink

         Cause pppd to use ILINK instead of IPLINK. This is the
         default.  When ILINK is used, the system cleans up ter-
         minated interfaces (even when SIGKIL is used) but  does
         not  allow ifconfig(1M) to unplumb P streams or insert
         or remove modules dynamically. Use the plink  option  if
         ifconfig(1M)  modinsert, modremove or unplumb support is
         needed.



SunOS 5.11          Last change: 21 Nov 2001                   18






System Administration Commands                           pppd(1M)



     nopredictor1

         Do not accept or agree to Predictor-1 compression. (This
         option is accepted for compatibility. The implementation
         does not support Predictor-1 compression.)


     noproxyarp

         Disable the proxyarp option.  If  you  want  to  prevent
         users  from  creating proxy ARP entries with pppd, place
         this option in the /etc/ppp/options file.


     notty

         Normally, pppd requires a  terminal  device.  With  this
         option,  pppd allocates itself a pseudo-tty master/slave
         pair and uses the slave as  its  terminal  device.  pppd
         creates  a  child process to act as a character shunt to
         transfer characters between the  pseudo-tty  master  and
         its  standard  input  and  output.  Thus, pppd transmits
         characters on its standard output and  receives  charac-
         ters on its standard input even if they are not terminal
         devices. This option increases the latency and CPU over-
         head  of transferring data over the ppp interface as all
         of the characters sent and received  must  flow  through
         the character shunt process. An explicit device name may
         not be given if this option is used.


     novj

         Disable Van Jacobson style TCP/IP header compression  in
         both the transmit and the receive direction.


     novjccomp

         Disable the  connection-ID  compression  option  in  Van
         Jacobson  style  TCP/IP  header  compression.  With this
         option, pppd does not omit the connection-ID  byte  from
         Van  Jacobson compressed TCP/IP headers, nor does it ask
         the peer to do so. This option is unnecessary if novj is
         specified.


     pam

         This privileged option enables use of PAM.  If  this  is
         specified,  pppd  uses  the pam(3PAM) framework for user
         authentication with a service name of "ppp" if the login



SunOS 5.11          Last change: 21 Nov 2001                   19






System Administration Commands                           pppd(1M)



         option  and  PAP authentication are used. The default is
         not to use PAM.


     papcrypt

         Indicates that pppd should not accept a password  which,
         before  encryption,  is identical to the secret from the
         /etc/ppp/pap-secrets  file.  Use  this  option  if   the
         secrets in the pap-secrets file are in crypt(3C) format.


     pap-max-authreq n

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


     pap-restart n

         Set the PAP restart interval (retransmission timeout) to
         n seconds (default 3).


     pap-timeout n

         Set the maximum time that pppd waits  for  the  peer  to
         authenticate itself with PAP to n seconds (0= no limit).
         The default is 30 seconds.


     password string

         Password string for authentication to the peer.


     persist

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


     plink

         Cause pppd to use IPLINK instead of ILINK. The default
         is  to  use ILINK, which cleans up terminated interface
         (even  if  SIGKIL  is  used),  but   does   not   allow
         ifconfig(1M)  to unplumb P streams or insert or remove
         modules dynamically. Use  this  option  if  ifconfig(1M)
         modinsert/modremove/unplumb  support is needed. See also
         the plumbed option.




SunOS 5.11          Last change: 21 Nov 2001                   20






System Administration Commands                           pppd(1M)



     plugin filename

         Load the shared library object file filename as  a  plu-
         gin.  This  is  a privileged option. Unless the filename
         specifies  an  explicit   path,   /etc/ppp/plugins   and
         /usr/lib/inet/ppp  will  be  searched  for the object to
         load in that order.


     plumbed

         This option indicates that pppd should  find  a  plumbed
         interface   and  use  that  for  the  session.  If  IPv4
         addresses or IPv6 interface IDs or link MTU  are  other-
         wise  unspecified,  they  are  copied from the interface
         selected. This mode mimics some of the functionality  of
         the  older aspppd implementation and may be helpful when
         pppd  is  used  with  external  applications  that   use
         ifconfig(1M).


     pppmux timer

         Enable  P  Multiplexing  option  negotiation  and  set
         transmit multiplexing timeout to timer microseconds.


     privgroup group-name

         Allows members of group  group-name  to  use  privileged
         options.  This  is a privileged option. Because there is
         no guarantee that members of group-name cannot use  pppd
         to  become  root themselves, you should be careful using
         this option.  Consider  it  equivalent  to  putting  the
         members of group-name in the root or sys group.


     proxyarp

         Add an entry to the system's Address Resolution Protocol
         (ARP) table with the IP address of the peer and the Eth-
         ernet address of this system. When you use this  option,
         the  peer  appears  to  other systems to be on the local
         Ethernet. The remote address on the P link must be  in
         the same subnet as assigned to an Ethernet interface.


     pty  script

         Specifies that the command script, and  not  a  specific
         terminal  device  is used for serial communication. pppd
         allocates itself a pseudo-tty master/slave pair and uses



SunOS 5.11          Last change: 21 Nov 2001                   21






System Administration Commands                           pppd(1M)



         the slave as its terminal device. script runs in a child
         process with the pseudo-tty master as its standard input
         and  output. An explicit device name may not be given if
         this option is used. (Note: if the record option is used
         in  conjunction  with  the pty option, the child process
         will have pipes on its standard input and output.)


     receive-all

         With this option, pppd accepts  all  control  characters
         from  the  peer,  including  those marked in the receive
         asyncmap. Without this option, pppd discards those char-
         acters  as  specified in RFC 1662. This option should be
         used only if the peer has bugs, as is often  found  with
         dial-back implementations.


     record filename

         Directs pppd to record all characters sent and  received
         to  a  file named filename. filename is opened in append
         mode, using the user's user-ID and permissions.  Because
         this  option uses a pseudo-tty and a process to transfer
         characters between the pseudo-tty and  the  real  serial
         device,  it  increases  the  latency and CPU overhead of
         transferring data over the P interface. Characters are
         stored  in  a  tagged format with timestamps that can be
         displayed in readable form using  the  pppdump(1M)  pro-
         gram.  This  option is generally used when debugging the
         kernel portion of pppd (especially CP compression algo-
         rithms)  and  not for debugging link configuration prob-
         lems. See the debug option.


     remotename name

         Set the assumed name of the remote system for  authenti-
         cation  purposes  to  name. Microsoft WindowsNT does not
         provide a system name in its  CHAP  Challenge  messages,
         and  this option is often used to work around this prob-
         lem.


     refuse-chap

         With this option, pppd will not  agree  to  authenticate
         itself  to  the  peer using standard Challenge Handshake
         Authentication  Protocol   (CHAP).   (MS-CHAP   is   not
         affected.)





SunOS 5.11          Last change: 21 Nov 2001                   22






System Administration Commands                           pppd(1M)



     refuse-mschap

         Do not agree to authenticate to peer with MS-CHAPv1.  If
         this option is specified, requests for MS-CHAPv1 authen-
         tication from the peer are declined with LCP  Configure-
         Nak.  That  option  does  not  disable any other form of
         CHAP.


     refuse-mschapv2

         Do not agree to authenticate to peer with MS-CHAPv2.  If
         specified, this option requests that MS-CHAPv2 authenti-
         cation from the peer be declined with LCP Configure-Nak.
         That option does not disable any other form of CHAP.


     refuse-pap

         With this option, pppd will not  agree  to  authenticate
         itself  to the peer using Password Authentication Proto-
         col (PAP).


     require-chap

         Require the peer to authenticate itself  using  standard
         CHAP authentication. MS-CHAP is not affected.


     require-mschap

         Require the peer to authenticate itself using  MS-CHAPv1
         authentication.


     require-mschapv2

         Require the peer to authenticate itself using  MS-CHAPv2
         authentication.


     require-pap

         Require  the  peer  to  authenticate  itself  using  PAP
         authentication.


     show-password

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



SunOS 5.11          Last change: 21 Nov 2001                   23






System Administration Commands                           pppd(1M)



     silent

         With this option, pppd will not transmit LCP packets  to
         initiate  a  connection  until  a  valid  LCP  packet is
         received from the  peer.  This  is  like  the  "passive"
         option  with  older versions of pppd and is retained for
         compatibility, but the current passive  option  is  pre-
         ferred.


     small-accm-test

         When checking the asyncmap (ACM) setting, pppd uses all
         256  possible  values by default. See no-accm-test. This
         option restricts the test so that  only  the  32  values
         affected  by  standard ACM negotiation are tested. This
         option is useful on very slow links.


     socket host:port

         Connect to given host and port using  TCP  and  run  P
         over this connection.


     sync

         Use synchronous HDLC serial encoding  instead  of  asyn-
         chronous.  The device used by pppd with this option must
         have sync support. Currently supports zs,  se,  and  hsi
         drivers.


     unit n

         Set P interface unit number to n, if possible.


     updetach

         With this option, pppd  detaches  from  its  controlling
         terminal  after  establishing  the  P connection. When
         this is specified, messages sent to stderr by  the  con-
         nect  script,  usually  chat(1M), and debugging messages
         from the debug option are directed  to  pppd's  standard
         output.


     usehostname

         Enforce  the  use  of  the  hostname  with  domain  name
         appended,  if given, as the name of the local system for



SunOS 5.11          Last change: 21 Nov 2001                   24






System Administration Commands                           pppd(1M)



         authentication purposes. This overrides the name option.
         Because  the  name  option is privileged, this option is
         normally not needed.


     usepeerdns

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


     user name

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


     vj-max-slots n

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


     welcome script

         Run the executable or shell command specified by  script
         before  initiating  P  negotiation,  after the connect
         script, if any, has completed. A value for  this  option
         from  a privileged source cannot be overridden by a non-
         privileged user.


     xonxoff

         Use software flow control, that is, XON/XOF, to control
         the flow of data on the serial port.


  Obsolete Options
     The following options are obsolete:

     ]ua name      Read a PAP user name  and  password  from  the
                   file  name.  This file must have two lines for
                   name and password. Name and password are  sent
                   to the peer when the peer requests PAP authen-
                   tication.



SunOS 5.11          Last change: 21 Nov 2001                   25






System Administration Commands                           pppd(1M)



     ]ipv6         Enable  IPv6  and  IPv6CP  without  specifying
                   interface identifiers.


     --version     Show version number and exit.


     --help        Show brief help message and exit.


EXTENDED DESCRIPTION
     The following sections  discuss  miscellaneous  features  of
     pppd:

  Security
     pppd allows  system  administrators  to  provide  legitimate
     users  with  P  access to a server machine without fear of
     compromising the security of the server or  the  network  it
     runs  on.  Access  control  is  provided  by  restricting IP
     addresses the peer may use based on its authenticated  iden-
     tity  (if  any),  and through restrictions on options a non-
     privileged user may use.  Options  that  permit  potentially
     insecure  configurations  are privileged. Privileged options
     are accepted only in files that are under the control of the
     system administrator or when pppd is being run by root.


     By default, pppd allows an unauthenticated  peer  to  use  a
     given  IP address only if the system does not already have a
     route to that IP address. For example, a system with a  per-
     manent connection to the wider Internet will normally have a
     default route, meaning all  peers  must  authenticate  them-
     selves  to  set  up a connection. On such a system, the auth
     option is the default. Conversely, a system with a P  link
     that  comprises the only connection to the Internet probably
     does not possess a default route, so the peer can use virtu-
     ally any IP address without authenticating itself.


     Security-sensitive options  are  privileged  and  cannot  be
     accessed  by  a  non-privileged user running pppd, either on
     the command line, in the user's $HOME/.ppprc file, or in  an
     options  file read using the file option. Privileged options
     may be used in /etc/ppp/options file or in an  options  file
     read using the call option. If pppd is run by the root user,
     privileged options can be used without restriction.  If  the
     /etc/ppp/options  file  does  not  exist, then only root may
     invoke pppd. The /etc/ppp/options file must be created  (but
     may  be  empty)  to  allow ordinary non-root users to access
     pppd.





SunOS 5.11          Last change: 21 Nov 2001                   26






System Administration Commands                           pppd(1M)



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

  Authentication
     During the authentication process, one  peer  convinces  the
     other  of  its  identity by sending its name and some secret
     information to the other. During authentication,  the  first
     peer  becomes  the  "client"  and  the  second  becomes  the
     "server." Authentication names can (but are not required to)
     correspond to the peer's Internet hostnames.


     pppd supports four authentication  protocols:  the  Password
     Authentication  Protocol  (PAP) and three forms of the Chal-
     lenge Handshake Authentication Protocol (CHAP). With the PAP
     protocol, the client sends its name and a cleartext password
     to the server to authenticate itself. With CHAP, the  server
     initiates the authentication exchange by sending a challenge
     to the client who must respond with  its  name  and  a  hash
     value derived from the shared secret and the challenge.


     The P protocol is symmetrical, meaning that each peer  may
     be  required  to authenticate itself to the other. Different
     authentication protocols and names  can  be  used  for  each
     exchange.


     By default, pppd authenticates if  requested  and  does  not
     require authentication from the peer. However, pppd does not
     authenticate itself with a specific protocol if  it  has  no
     secrets that can do so.


     pppd stores  authentication  secrets  in  the  /etc/ppp/pap-
     secrets  (for  PAP),  and  /etc/ppp/chap-secrets  (for CHAP)
     files. Both files use the same  format.  pppd  uses  secrets
     files to authenticate itself to other systems and to authen-
     ticate other systems to itself.


     Secrets files contain  one  secret  per  line.  Secrets  are
     specific  to  a  particular combination of client and server



SunOS 5.11          Last change: 21 Nov 2001                   27






System Administration Commands                           pppd(1M)



     and can only be used by that client to  authenticate  itself
     to that server. Each line in a secrets file has a minimum of
     three fields that contain the client and server  names  fol-
     lowed  by the secret. Often, these three fields are followed
     by IP addresses that are used by clients  to  connect  to  a
     server.


     A secrets file is  parsed  into  words,  with  client  name,
     server  name  and  secrets  fields  allocated one word each.
     Embedded spaces or other special characters  within  a  word
     must  be quoted or escaped. Case is significant in all three
     fields.


     A secret beginning with an at sign ("@") is followed by  the
     name of a file containing the secret. An asterisk (*) as the
     client or server name matches  any  name.  When  choosing  a
     match,  pppd  selects  the  one  with  the fewest wildcards.
     Succeeding words on  a  line  are  interpreted  by  pppd  as
     acceptable  IP  addresses  for that client. IP Addresses are
     disallowed if they appear in lines that contain  only  three
     words  or lines whose first word begins with a hyphen ("-").
     To allow any address, use "*". An address starting  with  an
     exclamation point ("!") indicates that the specified address
     is not acceptable. An address may be followed by "/"  and  a
     number n to indicate a whole subnet (all addresses that have
     the same value in the most  significant  n  bits).  In  this
     form,  the  address  may be followed by a plus sign ("]") to
     indicate that one address from  the  subnet  is  authorized,
     based  on  the  ppp network interface unit number in use. In
     this case, the host part of the address is set to  the  unit
     number, plus one.


     When authenticating the peer, pppd chooses a secret with the
     peer's  name  in the first field of the secrets file and the
     name of the local system in the second field. The local sys-
     tem  name  defaults  to  the  hostname, with the domain name
     appended if the domain option is used. The  default  can  be
     overridden  with  the  name  option  unless  the usehostname
     option is used.


     When authenticating to the peer, pppd first  determines  the
     name  it  will use to identify itself to the peer. This name
     is specified with the user option. If the user option is not
     used,  the  name defaults to the host name of the local sys-
     tem. pppd then selects a secret from  the  secrets  file  by
     searching  for an entry with a local name in the first field
     and the peer's name in the second field. pppd will know  the
     name  of  the  peer  if standard CHAP authentication is used



SunOS 5.11          Last change: 21 Nov 2001                   28






System Administration Commands                           pppd(1M)



     because the peer will have sent it in the Challenge  packet.
     However,  if  MS-CHAP or PAP is being used, pppd must deter-
     mine the peer's name from the options specified by the user.
     The  user  can  specify  the  peer's  name directly with the
     remotename option. Otherwise, if the remote IP  address  was
     specified  by a name, rather than in numeric form, that name
     will be used as the peer's name. If that  fails,  pppd  uses
     the null string as the peer's name.


     When  authenticating  the  peer  with  PAP,   the   supplied
     password     is  compared  with data in the secrets file. If
     the password and  secret  do  not  match,  the  password  is
     encrypted  using  crypt()  and  checked  against  the secret
     again. If the papcrypt option  is  given,  the  first  unen-
     crypted  comparison  is  omitted  for  better  security, and
     entries must thus be in encrypted crypt(3C) form.


     If the login option is specified, the username and  password
     are  also checked against the system password database. This
     allows you to set up the  pap-secrets  file  to  enable  P
     access  only to certain users, and to restrict the set of IP
     addresses available to  users.  Typically,  when  using  the
     login  option,  the  secret in /etc/ppp/pap-secrets would be
     "", which matches any password supplied by  the  peer.  This
     makes having the same secret in two places unnecessary. When
     login is used, the pam option enables access control through
     pam(3PAM).


     Authentication must be completed before IPCP (or other  net-
     work  protocol)  can  be started. If the peer is required to
     authenticate itself and fails,  pppd  closes  LCP  and  ter-
     minates  the  link.  If  IPCP  negotiates an unacceptable IP
     address for the remote host, IPCP is closed. IP packets  are
     sent or received only when IPCP is open.


     To allow hosts that cannot authenticate themselves  to  con-
     nect    and use one of a restricted set of IP addresses, add
     a line to the pap-secrets file specifying the  empty  string
     for the client name and secret.


     Additional pppd options for a given peer may be specified by
     placing  them  at the end of the secrets entry, separated by
     two dashes (--). For example

       peername servername secret ip-address -- novj





SunOS 5.11          Last change: 21 Nov 2001                   29






System Administration Commands                           pppd(1M)



  Routing
     When IPCP negotiation is complete, pppd informs  the  kernel
     of  the  local and remote IP addresses for the P interface
     and creates a host route to the remote end of the link  that
     enables  peers  to  exchange  IP packets. Communication with
     other machines generally requires  further  modification  to
     routing  tables  and/or  Address  Resolution  Protocol (ARP)
     tables. In  most  cases  the  defaultroute  and/or  proxyarp
     options  are  sufficient  for this, but further intervention
     may be necessary. If further intervention is  required,  use
     the /etc/ppp/ip-up script or a routing protocol daemon.


     To add a default route through  the  remote  host,  use  the
     defaultroute  option.  This  option  is  typically  used for
     "client" systems; that is, end-nodes that use the  P  link
     for access to the general Internet.


     In some cases it is desirable to use proxy ARP, for  example
     on a server machine connected to a LAN, to allow other hosts
     to communicate with the remote host. proxyarp instructs pppd
     to  look  for  a network interface on the same subnet as the
     remote host. That is, an interface supporting broadcast  and
     ARP  that  is not a point-to-point or loopback interface and
     that is currently up. If found, pppd  creates  a  permanent,
     published  ARP  entry with the IP address of the remote host
     and the hardware address of the network interface.


     When the demand option is used, the interface  IP  addresses
     are already set at the time when IPCP comes up. If pppd can-
     not negotiate the same addresses it used  to  configure  the
     interface,  it  changes  the  interface  IP addresses to the
     negotiated addresses. This may disrupt existing connections.
     Using  demand  dialing  with  peers  that perform dynamic IP
     address assignment is not recommended.

  Scripts
     pppd invokes scripts at  various  stages  during  processing
     that are used to perform site-specific ancillary processing.
     These scripts may be shell scripts or  executable  programs.
     pppd  does  not  wait for the scripts to finish. The scripts
     are executed as root (with the real  and  effective  user-id
     set  to  0),  enabling  them  to  update routing tables, run
     privileged daemons, or perform other tasks. Be sure that the
     contents  of  these  scripts do not compromise your system's
     security. pppd runs the scripts with standard input,  output
     and  error  redirected to /dev/null, and with an environment
     that is empty except for  some  environment  variables  that
     give  information about the link. The pppd environment vari-
     ables are:



SunOS 5.11          Last change: 21 Nov 2001                   30






System Administration Commands                           pppd(1M)



     DEVICE         Name of the serial tty device.


     IFNAME         Name of the network interface.


     IPLOCAL        IP address for the link's local end. This  is
                    set only when IPCP has started.


     IPREMOTE       IP address for the link's remote end. This is
                    set only when IPCP has started.


     PERNAME       Authenticated name of the peer. This  is  set
                    only if the peer authenticates itself.


     SPED          Baud rate of the tty device.


     ORIGUID       Real user-id of user who invoked pppd.


     PLOGNAME     Username of  the  real  user-id  who  invoked
                    pppd. This is always set.



     pppd also sets the following variables for the  ip-down  and
     auth-down scripts:

     CONECTIME     Number of seconds between the start of  P
                      negotiation and connection termination.


     BYTESENT       Number of bytes sent at the  level  of  the
                      serial port during the connection.


     BYTESRCVD       Number of bytes received at  the  level  of
                      the serial port during the connection.


     LINKNAME         Logical name of  the  link,  set  with  the
                      linkname option.



     If they exist, pppd invokes the following scripts. It is not
     an error if they do not exist.




SunOS 5.11          Last change: 21 Nov 2001                   31






System Administration Commands                           pppd(1M)



     /etc/ppp/auth-up       Program or script executed after  the
                            remote  system successfully authenti-
                            cates itself.  It  is  executed  with
                            five      command-line     arguments:
                            interface-name  peer-name   user-name
                            tty-device   speed.  Note  that  this
                            script is not executed  if  the  peer
                            does  not  authenticate  itself,  for
                            example, when the  noauth  option  is
                            used.


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


     /etc/ppp/ip-up       A program or script  that  is  executed
                          when  the link is available for sending
                          and receiving IP packets (that is, IPCP
                          has  come  up). It is executed with six
                          command-line arguments:  interface-name
                          tty-device    speed    local-IP-address
                          remote-IP-address ipparam.


     /etc/ppp/ip-down     A program or script which  is  executed
                          when  the  link  is no longer available
                          for sending and receiving  IP  packets.
                          This script can be used for undoing the
                          effects of the  /etc/ppp/ip-up  script.
                          It  is  invoked  in the same manner and
                          with the same parameters as  the  ip-up
                          script.


     /etc/ppp/ipv6-up     Similar to /etc/ppp/ip-up, except  that
                          it  is executed when the link is avail-
                          able for  sending  and  receiving  IPv6
                          packets. Executed with six command-line
                          arguments:  interface-name   tty-device
                          speed  local-link-local-address remote-
                          link-local-address ipparam.


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



SunOS 5.11          Last change: 21 Nov 2001                   32






System Administration Commands                           pppd(1M)



EXAMPLES
     Example 1 Using the auth Option


     The following examples assume that the /etc/ppp/options file
     contains the auth option.



     pppd is commonly used to dial out to an ISP. You can do this
     using    the    "pppd    call   isp"   command   where   the
     /etc/ppp/peers/isp file is set up to contain a line  similar
     to the following:


       cua/a 19200 crtscts connect '/usr/bin/chat -f /etc/ppp/chat-isp' noauth



     For this example, chat(1M) is used to dial the  ISP's  modem
     and  process any login sequence required. The /etc/ppp/chat-
     isp file is used by chat and could contain the following:


       ABORT "NO CARIER"
       ABORT "NO DIALTONE"
       ABORT "EROR"
       ABORT "NO ANSWER"
       ABORT "BUSY"
       ABORT "Username/Password Incorrect"
       "" "at"
       OK "at&f&d2&c1"
       OK "atdt2468135"
       "name:" "^Umyuserid"
       "word:" "qmypassword"
       "ispts" "q^Uppp"
       "~-^Uppp-~"



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


     Example 2 Using pppd with proxyarp


     pppd can also provide a dial-in ppp service  for  users.  If
     the  users  already have login accounts, the simplest way to
     set up the ppp service is to let the users log in  to  their
     accounts and run pppd as shown in the following example:





SunOS 5.11          Last change: 21 Nov 2001                   33






System Administration Commands                           pppd(1M)



       example% pppd proxyarp



     Example 3 Providing a User with Access to P Facilities


     To provide a user with access to the P  facilities,  allo-
     cate  an  IP address for the user's machine, create an entry
     in  /etc/ppp/pap-secrets  or   /etc/ppp/chap-secrets.   This
     enables the user's machine to authenticate itself. For exam-
     ple, to enable user "Joe" using machine "joespc" to dial  in
     to  machine "server" and use the IP address "joespc.my.net,"
     add the  following  entry  to  the  /etc/ppp/pap-secrets  or
     /etc/ppp/chap-secrets files:


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




     Alternatively, you can create another username, for  example
     "ppp,"  whose  login  shell  is /usr/bin/pppd and whose home
     directory is /etc/ppp. If you run pppd  this  way,  add  the
     options to the /etc/ppp/.ppprc file.



     If your serial connection is complex, it may  be  useful  to
     escape  such  control  characters as XON (^Q) and XOF (^S),
     using asyncmap a0000. If the path includes a telnet,  escape
     ^]  (asyncmap  200a0000). If the path includes a rlogin com-
     mand, add escape ff option to the  options,  because  rlogin
     removes  the  window-size-change sequence [0xff, 0xff, 0x73,
     0x73, followed by any 8 bytes] from the stream.


EXIT STATUS
     The pppd exit status indicates errors  or  specifies  why  a
     link was terminated. Exit status values are:

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


     1      An immediately fatal error occurred. For example,  an
            essential system call failed.


     2      An error was detected in the options given. For exam-
            ple,  two  mutually  exclusive  options were used, or



SunOS 5.11          Last change: 21 Nov 2001                   34






System Administration Commands                           pppd(1M)



            /etc/ppp/options is missing and the user is not root.


     3      pppd is not setuid-root and the invoking user is  not
            root.


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


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


     6      The serial port could not be locked.


     7      The serial port could not be opened.


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


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


     10     The P negotiation failed because no network  proto-
            cols were able to run.


     11     The peer system failed  or  refused  to  authenticate
            itself.


     12     The link was established successfully, but terminated
            because it was idle.


     13     The link was established successfully, but terminated
            because the connect time limit was reached.


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


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




SunOS 5.11          Last change: 21 Nov 2001                   35






System Administration Commands                           pppd(1M)



     16     The link was terminated by the modem hanging up.


     17     The P negotiation failed  because  serial  loopback
            was detected.


     18     The init script failed because a non-zero exit status
            was returned.


     19     Authentication to the peer failed.


FILES
     /var/run/spppn.pid           Process-ID for pppd process  on
                                  P interface unit n.


     /var/run/ppp-name.pid        Process-ID for pppd process for
                                  logical   link  name  (see  the
                                  linkname option).


     /etc/ppp/pap-secrets         Usernames,  passwords  and   IP
                                  addresses  for  PAP authentica-
                                  tion. This file should be owned
                                  by  root  and  not  readable or
                                  writable  by  any  other  user,
                                  otherwise pppd will log a warn-
                                  ing.


     /etc/ppp/chap-secrets        Names, secrets and IP addresses
                                  for all forms of CHAP authenti-
                                  cation.    The    /etc/ppp/pap-
                                  secrets file should be owned by
                                  root  should  not  readable  or
                                  writable  by  any  other  user,
                                  otherwise,  pppd  will  log   a
                                  warning.


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


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



SunOS 5.11          Last change: 21 Nov 2001                   36






System Administration Commands                           pppd(1M)



     /etc/ppp/options.ttyname     System default options for  the
                                  serial  port in use; read after
                                  $HOME/.ppprc. The ttyname  com-
                                  ponent   of  this  filename  is
                                  formed when the  initial  /dev/
                                  is  stripped from the port name
                                  (if present), and  slashes  (if
                                  any) are converted to dots.


     /etc/ppp/peers               Directory  with  options  files
                                  that   may  contain  privileged
                                  options,  even  if   pppd   was
                                  invoked  by  a  user other than
                                  root. The system  administrator
                                  can  create  options  files  in
                                  this directory to  permit  non-
                                  privileged  users  to  dial out
                                  without requiring the  peer  to
                                  authenticate,  but only to cer-
                                  tain trusted peers.


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Availability                 SUNWpppdu                   
    
     Interface Stability          Evolving                    
    


SEE ALSO
     chat(1M), ifconfig(1M), crypt(3C), pam(3PAM), attributes(5)


     Haskin, D., Allen, E. RFC 2472 - IP Version 6 Over P. Net-
     work Working Group. December 1998.


     Jacobson, V. RFC 1144, Compressing TCP/IP Headers  for  Low-
     Speed Serial Links. Network Working Group. February, 1990


     Lloyd, B., Simpson, W. RFC 1334, P  Authentication  Proto-
     cols. Network Working Group. October 1992.



SunOS 5.11          Last change: 21 Nov 2001                   37






System Administration Commands                           pppd(1M)



     McGregor, G. RFC 1332, The  P  Internet  Protocol  Control
     Protocol (IPCP). Network Working Group. May 1992.


     Rivest, R. RFC 1321, The MD5 Message-Digest Algorithm.  Net-
     work Working Group. April 1992


     Simpson, W. RFC 1661,  The  Point-to-Point  Protocol  (P).
     Network Working Group. July 1994.


     Simpson, W. RFC 1662, HDLC-like Framing  .  Network  Working
     Group. July 1994.

NOTES
     These signals affect pppd behavior:

     SIGINT, SIGTERM     Terminate the link, restore  the  serial
                         device settings and exit.


     SIGHUP              Terminate the link, restore  the  serial
                         device  settings  and  close  the serial
                         device. If the persist or demand  option
                         is  specified,  pppd  attempts to reopen
                         the serial device and start another con-
                         nection after the holdoff period. Other-
                         wise pppd exits. If received during  the
                         holdoff  period,  SIGHUP  causes pppd to
                         end the holdoff period immediately.


     SIGUSR1             Toggles the state of  the  debug  option
                         and  prints  link  status information to
                         the log.


     SIGUSR2             Causes pppd to renegotiate  compression.
                         This  is useful to re-enable compression
                         after it has been disabled as  a  result
                         of  a  fatal decompression error. (Fatal
                         decompression errors generally  indicate
                         a bug in an implementation.)


DIAGNOSTICS
     Messages are  sent  to  the  syslog  daemon  using  facility
     LOGDAEMON.  To  see  error  and  debug  messages,  edit the
     /etc/syslog.conf file to direct the messages to the  desired
     output  device  or  file,  or  use  the  updetach or logfile
     options.



SunOS 5.11          Last change: 21 Nov 2001                   38






System Administration Commands                           pppd(1M)



     The debug option causes the contents of all LCP,  PAP,  CHAP
     or  IPCP control packets sent or received to be logged. This
     is useful if P negotiation does not succeed or if  authen-
     tication fails.


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















































SunOS 5.11          Last change: 21 Nov 2001                   39
OpenSolaris man pages main menu