Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PPP(8)                  FreeBSD System Manager's Manual                 PPP(8)

NAME
     ppp - Point to Point Protocol (a.k.a. user-ppp)

SYNOPSIS
     ppp [-auto | -background | -ddial | -direct | -dedicated] [-alias]
         [system ...]

DESCRIPTION
     This is a user process PPP software package.  Normally, PPP is
     implemented as a part of the kernel (e.g. as managed by pppd(8)) and it's
     thus somewhat hard to debug and/or modify its behaviour.  However, in
     this implementation PPP is done as a user process with the help of the
     tunnel device driver (tun).

Major Features
     Provides interactive user interface.  Using its command mode, the user
     can easily enter commands to establish the connection with the remote
     end, check the status of connection and close the connection.  All
     functions can also be optionally password protected for security.

     Supports both manual and automatic dialing.  Interactive mode has a
     ``term'' command which enables you to talk to your modem directly.  When
     your modem is connected to the remote peer and it starts to talk PPP, ppp
     detects it and switches to packet mode automatically.  Once you have
     determined the proper sequence for connecting with the remote host, you
     can write a chat script to define the necessary dialing and login
     procedure for later convenience.

     Supports on-demand dialup capability.  By using -auto mode, ppp will act
     as a daemon and wait for a packet to be sent over the PPP link.  When
     this happens, the daemon automatically dials and establishes the
     connection.  In almost the same manner -ddial mode (direct-dial mode)
     also automatically dials and establishes the connection.  However, it
     differs in that it will dial the remote site any time it detects the link
     is down, even if there are no packets to be sent.  This mode is useful
     for full-time connections where we worry less about line charges and more
     about being connected full time.  A third -dedicated mode is also
     available.  This mode is targeted at a dedicated link between two
     machines.  Ppp will never voluntarily quit from dedicated mode - you must
     send it the ``quit all'' command via its diagnostic socket.  A SIGHUP
     will force an LCP renegotiation, and a SIGTERM will force it to exit.

     Supports client callback.  Ppp can use either the standard LCP callback
     protocol or the Microsoft CallBack Control Protocol
     (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt).

     Supports packet aliasing.  Packet aliasing (a.k.a. IP masquerading)
     allows computers on a private, unregistered network to access the
     Internet.  The PPP host acts as a masquerading gateway.  IP addresses as
     well as TCP and UDP port numbers are aliased for outgoing packets and de-
     aliased for returning packets.

     Supports background PPP connections.  In background mode, if ppp
     successfully establishes the connection, it will become a daemon.
     Otherwise, it will exit with an error.  This allows the setup of scripts
     that wish to execute certain commands only if the connection is
     successfully established.

     Supports server-side PPP connections.  In direct mode, ppp acts as server
     which accepts incoming PPP connections on stdin/stdout.

     Supports PAP and CHAP authentication.  With PAP or CHAP, it is possible
     to skip the Unix style login(1) procedure, and use the PPP protocol for
     authentication instead.  If the peer requests Microsoft CHAP
     authentication and ppp is compiled with DES support, an appropriate
     MD4/DES response will be made.

     Supports Proxy Arp.  When PPP is set up as server, you can also configure
     it to do proxy arp for your connection.

     Supports packet filtering.  User can define four kinds of filters: the in
     filter for incoming packets, the out filter for outgoing packets, the
     dial filter to define a dialing trigger packet and the alive filter for
     keeping a connection alive with the trigger packet.

     Tunnel driver supports bpf.  The user can use tcpdump(1) to check the
     packet flow over the PPP link.

     Supports PPP over TCP capability.  If a device name is specified as
     host:port, ppp will open a TCP connection for transporting data rather
     than using a conventional serial device.

     Supports IETF draft Predictor-1 and DEFLATE compression.  ppp supports
     not only VJ-compression but also Predictor-1 and DEFLATE compression.
     Normally, a modem has built-in compression (e.g. v42.bis) and the system
     may receive higher data rates from it as a result of such compression.
     While this is generally a good thing in most other situations, this
     higher speed data imposes a penalty on the system by increasing the
     number of serial interrupts the system has to process in talking to the
     modem and also increases latency.  Unlike VJ-compression, Predictor-1 and
     DEFLATE compression pre-compresses all network traffic flowing through
     the link, thus reducing overheads to a minimum.

     Supports Microsoft's IPCP extensions.  Name Server Addresses and NetBIOS
     Name Server Addresses can be negotiated with clients using the Microsoft
     PPP stack (ie. Win95, WinNT)

     Supports Multi-link PPP  It is possible to configure ppp to open more
     than one physical connection to the peer, combining the bandwidth of all
     links for better throughput.

PERMISSIONS
     Ppp is installed as user root and group network, with permissions 4554.
     By default, ppp will not run if the invoking user id is not zero.  This
     may be overridden by using the ``allow users'' command in
     /etc/ppp/ppp.conf.  When running as a normal user, ppp switches to user
     id 0 in order to alter the system routing table, set up system lock files
     and read the ppp configuration files.  All external commands (executed
     via the "shell" or "!bg" commands) are executed as the user id that
     invoked ppp.  Refer to the `ID0' logging facility if you're interested in
     what exactly is done as user id zero.

GETTING STARTED
     The following command line switches are understood by ppp:

        -auto
             Ppp opens the tun interface, configures it then goes into the
             background.  The link isn't brought up until outgoing data is
             detected on the tun interface at which point ppp attempts to
             bring up the link.  Packets received (including the first one)
             while ppp is trying to bring the link up will remain queued for a
             default of 2 minutes.  See the ``set choked'' command below.

             At least one ``system'' must be given on the command line (see
             below) and a ``set ifaddr'' must be done in the system profile
             that specifies a peer IP address to use when configuring the
             interface.  Something like ``10.0.0.1/0'' is usually appropriate.
             See the ``pmdemand'' system in /etc/ppp/ppp.conf.sample for an
             example.

        -background
             Here, ppp attempts to establish a connection with the peer
             immediately.  If it succeeds, ppp goes into the background and
             the parent process returns an exit code of 0.  If it fails, ppp
             exits with a non-zero result.

        -direct
             This is used for receiving incoming connections.  Ppp ignores the
             ``set device'' line and uses descriptor 0 as the link.

             If callback is configured, ppp will use the ``set device''
             information when dialing back.

        -dedicated
             This option is designed for machines connected with a dedicated
             wire.  Ppp will always keep the device open and will never use
             any configured chat scripts.

        -ddial
             This mode is equivalent to -auto mode except that ppp will bring
             the link back up any time it's dropped for any reason.

        -interactive
             This is a no-op, and gives the same behaviour as if none of the
             above flags have been specified.  Ppp loads any systems specified
             on the command line then provides an interactive prompt.

        -alias
             This flag doesn't control ppp's mode.  It does the equivalent of
             an ``enable alias yes''.  Additionally, if the -auto flag is also
             specified, an implicit ``enable iface-alias'' is done.  See below
             for details.

             Enabling IP aliasing allows ppp to act as a NAT or masquerading
             engine for all machines on an internal LAN.  Refer to libalias(3)
             for details.

     Additionally, one or more systems may be specified on the command line.
     A `system' is a configuration entry in /etc/ppp/ppp.conf.  Ppp will read
     the ``default'' system from /etc/ppp/ppp.conf at startup, followed by
     each of the systems specifed on the command line.

     Only one of the -auto, -background, -ddial, -direct, -dedicated and
     -interactive switches may be specified.  Ppp's `mode' may subsequently be
     changed with the ``set mode'' command (see below).

     For now, we'll stick to using interactive mode.

     When you first run ppp you may need to deal with some initial
     configuration details.

     +o   Your kernel must include a tunnel device (the GENERIC kernel includes
         one by default).  If it doesn't, or if you require more than one tun
         interface, you'll need to rebuild your kernel with the following line
         in your kernel configuration file:

               pseudo-device tun N

         where N is the maximum number of PPP connections you wish to support.

     +o   Check your /dev directory for the tunnel device entries /dev/tunN,
         where `N' represents the number of the tun device, starting at zero.
         If they don't exist, you can create them by running "sh ./MAKEDEV
         tunN".  This will create tun devices 0 through N.

     +o   Make sure that your system has a group named ``network'' in the
         /etc/group file and that that group contains the names of all users
         expected to use ppp.  Refer to the group(5) manual page for details.
         Each of these users must also be given access using the ``allow
         users'' command in /etc/ppp/ppp.conf.

     +o   Create a log file.  Ppp uses syslog(3) to log information.  A common
         log file name is /var/log/ppp.log.  To make output go to this file,
         put the following lines in the /etc/syslog.conf file:

               !ppp
               *.*<TAB>/var/log/ppp.log

         It is possible to have more than one PPP log file by creating a link
         to the ppp executable:

               # cd /usr/sbin
               # ln ppp ppp0

         and using

               !ppp0
               *.*<TAB>/var/log/ppp0.log

         in /etc/syslog.conf.  Don't forget to send a HUP signal to syslogd(8)
         after altering /etc/syslog.conf.

     +o   Although not strictly relevant to ppps operation, you should
         configure your resolver so that it works correctly.  This can be done
         by configuring a local DNS (using named(8)) or by adding the correct
         `name-server' lines to the file /etc/resolv.conf.  Refer to the
         resolv.conf(5) manual page for details.

         Alternatively, if the peer supports it, ppp can be configured to ask
         the peer for the nameserver address(es) and to update
         /etc/resolv.conf automatically.  Refer to the ``enable dns'' command
         below for details.

MANUAL DIALING
     In the following examples, we assume that your machine name is awfulhak.
     when you invoke ppp (see PERMISSIONS above) with no arguments, you are
     presented with a prompt:

           ppp ON awfulhak>

     The `ON' part of your prompt should always be in upper case.  If it is in
     lower case, it means that you must supply a password using the ``passwd''
     command.  This only ever happens if you connect to a running version of
     ppp and have not authenticated yourself using the correct password.

     You can start by specifying the device name, speed and parity for your
     modem, and whether CTS/RTS signalling should be used (CTS/RTS is used by
     default).  If your hardware does not provide CTS/RTS lines (as may happen
     when you are connected directly to certain PPP-capable terminal servers),
     ppp will never send any output through the port; it waits for a signal
     which never comes.  Thus, if you have a direct line and can't seem to
     make a connection, try turning CTS/RTS off:

           ppp ON awfulhak> set line /dev/cuaa0
           ppp ON awfulhak> set speed 38400
           ppp ON awfulhak> set parity even
           ppp ON awfulhak> set ctsrts on
           ppp ON awfulhak> show modem
           * Modem related information is shown here *
           ppp ON awfulhak>

     The term command can now be used to talk directly with your modem:

           ppp ON awfulhak> term
           at
           OK
           atdt123456
           CONNECT
           login: ppp
           Password:
           Protocol: ppp

     When the peer starts to talk in PPP, ppp detects this automatically and
     returns to command mode.

           ppp ON awfulhak>               # No link has been established
           Ppp ON awfulhak>               # We've connected & finished LCP
           PPp ON awfulhak>               # We've authenticated
           PPP ON awfulhak>               # We've agreed IP numbers

     If it does not, it's possible that the peer is waiting for your end to
     start negotiating or that ppp can't identify the incoming packets as
     being PPP packets, perhaps due to your parity settings.  To force ppp to
     start sending PPP configuration packets to the peer, use the ``~p''
     command to enter packet mode.

     You are now connected!  Note that `PPP' in the prompt has changed to
     capital letters to indicate that you have a peer connection.  If only
     some of the three Ps go uppercase, wait 'till either everything is
     uppercase or lowercase.  If they revert to lowercase, it means that ppp
     couldn't successfully negotiate with the peer.  This is probably because
     your PAP or CHAP authentication name or key is incorrect.  A good first
     step for troubleshooting at this point would be to ``set log local
     phase''.  Refer to the ``set log'' command description below for further
     details.

     When the link is established, the show command can be used to see how
     things are going:

           PPP ON awfulhak> show modem
           * Modem related information is shown here *
           PPP ON awfulhak> show ccp
           * CCP (compression) related information is shown here *
           PPP ON awfulhak> show lcp
           * LCP (line control) related information is shown here *
           PPP ON awfulhak> show ipcp
           * IPCP (IP) related information is shown here *
           PPP ON awfulhak> show link
           * Link (high level) related information is shown here *
           PPP ON awfulhak> show bundle
           * Logical (high level) connection related information is shown here *

     At this point, your machine has a host route to the peer.  This means
     that you can only make a connection with the host on the other side of
     the link.  If you want to add a default route entry (telling your machine
     to send all packets without another routing entry to the other side of
     the PPP link), enter the following command:

           PPP ON awfulhak> add default HISADDR

     The string `HISADDR' represents the IP address of the connected peer.  If
     the ``add'' command fails due to an existing route, you can overwrite the
     existing route using

           PPP ON awfulhak> add! default HISADDR

     You can now use your network applications (ping, telnet, ftp etc.)  in
     other windows on your machine.  Refer to the PPP COMMAND LIST section for
     details on all available commands.

AUTOMATIC DIALING
     To use automatic dialing, you must prepare some Dial and Login chat
     scripts.  See the example definitions in /etc/ppp/ppp.conf.sample (the
     format of /etc/ppp/ppp.conf is pretty simple).  Each line contains one
     comment, inclusion, label or command:

     +o   A line starting with a (``#'') character is treated as a comment
         line.  Leading whitespace are ignored when identifying comment lines.

     +o   An inclusion is a line beginning with the word `!include'.  It must
         have one argument - the file to include.  You may wish to ``!include
         ~/.ppp.conf'' for compatibility with older versions of ppp.

     +o   A label name starts in the first column and is followed by a colon
         (``:'').

     +o   A command line must contain a space or tab in the first column.

     The /etc/ppp/ppp.conf file should consist of at least a ``default''
     section.  This section is always executed.  It should also contain one or
     more sections, named according to their purpose, for example, ``MyISP''
     would represent your ISP, and ``ppp-in'' would represent an incoming ppp
     configuration.  You can now specify the destination label name when you
     invoke ppp.  Commands associated with the ``default'' label are executed,
     followed by those associated with the destination label provided.  When
     ppp is started with no arguments, the ``default'' section is still
     executed.  The load command can be used to manually load a section from
     the /etc/ppp/ppp.conf file:

           PPP ON awfulhak> load MyISP

     Once the connection is made, the `ppp' portion of the prompt will change
     to `PPP':

           # ppp MyISP
           ...
           ppp ON awfulhak> dial
           Ppp ON awfulhak>
           PPp ON awfulhak>
           PPP ON awfulhak>

     The Ppp prompt indicates that ppp has entered the authentication phase.
     The PPp prompt indicates that ppp has entered the network phase.  The PPP
     prompt indicates that ppp has successfully negotiated a network layer
     protocol and is in a usable state.

     If the /etc/ppp/ppp.linkup file is available, its contents are executed
     when the PPP connection is established.  See the provided ``pmdemand''
     example in /etc/ppp/ppp.conf.sample which runs a script in the background
     after the connection is established (refer to the ``shell'' and ``bg''
     commands below for a description of possible substition strings).
     Similarly, when a connection is closed, the contents of the
     /etc/ppp/ppp.linkdown file are executed.  Both of these files have the
     same format as /etc/ppp/ppp.conf.

     In previous versions of ppp, it was necessary to re-add routes such as
     the default route in the ppp.linkup file.  Ppp now supports `sticky
     routes', where all routes that contain the HISADDR or MYADDR literals
     will automatically be updated when the values of HISADDR and/or MYADDR
     change.

BACKGROUND DIALING
     If you want to establish a connection using ppp non-interactively (such
     as from a crontab(5) entry or an at(1) job) you should use the
     -background option.  When -background is specified, ppp attempts to
     establish the connection immediately.  If multiple phone numbers are
     specified, each phone number will be tried once.  If the attempt fails,
     ppp exits immediately with a non-zero exit code.  If it succeeds, then
     ppp becomes a daemon, and returns an exit status of zero to its caller.
     The daemon exits automatically if the connection is dropped by the remote
     system, or it receives a TERM signal.

DIAL ON DEMAND
     Demand dialing is enabled with the -auto or -ddial options.  You must
     also specify the destination label in /etc/ppp/ppp.conf to use.  It must
     contain the ``set ifaddr'' command to define the remote peers IP address.
     (refer to /etc/ppp/ppp.conf.sample)

           # ppp -auto pmdemand

     When -auto or -ddial is specified, ppp runs as a daemon but you can still
     configure or examine its configuration by using the ``set server''
     command in /etc/ppp/ppp.conf, (for example, ``set server +3000
     mypasswd'') and connecting to the diagnostic port as follows:

           # pppctl 3000   (assuming tun0 - see the ``set server'' description)
           Password:
           PPP ON awfulhak> show who
           tcp (127.0.0.1:1028) *

     The ``show who'' command lists users that are currently connected to ppp
     itself.  If the diagnostic socket is closed or changed to a different
     socket, all connections are immediately dropped.

     In -auto mode, when an outgoing packet is detected, ppp will perform the
     dialing action (chat script) and try to connect with the peer.  In -ddial
     mode, the dialing action is performed any time the line is found to be
     down.  If the connect fails, the default behaviour is to wait 30 seconds
     and then attempt to connect when another outgoing packet is detected.
     This behaviour can be changed with

           set redial seconds|random[.nseconds|random] [dial_attempts]

     `Seconds' is the number of seconds to wait before attempting to connect
     again. If the argument is `random', the delay period is a random value
     between 0 and 30 seconds.  `Nseconds' is the number of seconds to wait
     before attempting to dial the next number in a list of numbers (see the
     ``set phone'' command).  The default is 3 seconds.  Again, if the
     argument is `random', the delay period is a random value between 0 and 30
     seconds.  `dial_attempts' is the number of times to try to connect for
     each outgoing packet that is received. The previous value is unchanged if
     this parameter is omitted.  If a value of zero is specified for
     `dial_attempts', ppp will keep trying until a connection is made.

           set redial 10.3 4

     will attempt to connect 4 times for each outgoing packet that is detected
     with a 3 second delay between each number and a 10 second delay after all
     numbers have been tried.  If multiple phone numbers are specified, the
     total number of attempts is still 4 (it does not attempt each number 4
     times).  Modifying the dial delay is very useful when running ppp in
     demand dial mode on both ends of the link. If each end has the same
     timeout, both ends wind up calling each other at the same time if the
     link drops and both ends have packets queued.  At some locations, the
     serial link may not be reliable, and carrier may be lost at inappropriate
     times.  It is possible to have ppp redial should carrier be unexpectedly
     lost during a session.

           set reconnect timeout ntries

     This command tells ppp to re-establish the connection ntries times on
     loss of carrier with a pause of timeout seconds before each try.  For
     example,

           set reconnect 3 5

     tells ppp that on an unexpected loss of carrier, it should wait 3 seconds
     before attempting to reconnect.  This may happen up to 5 times before ppp
     gives up.  The default value of ntries is zero (no reconnect).  Care
     should be taken with this option.  If the local timeout is slightly
     longer than the remote timeout, the reconnect feature will always be
     triggered (up to the given number of times) after the remote side times
     out and hangs up.  NOTE:  In this context, losing too many LQRs
     constitutes a loss of carrier and will trigger a reconnect.  If the
     -background flag is specified, all phone numbers are dialed at most once
     until a connection is made.  The next number redial period specified with
     the ``set redial'' command is honoured, as is the reconnect tries value.
     If your redial value is less than the number of phone numbers specified,
     not all the specified numbers will be tried.  To terminate the program,
     type

           PPP ON awfulhak> close
           ppp ON awfulhak> quit all

     A simple ``quit'' command will terminate the pppctl(8) or telnet(1)
     connection but not the ppp program itself.  You must use ``quit all'' to
     terminate ppp as well.

RECEIVING INCOMING PPP CONNECTIONS (Method 1)
     To handle an incoming PPP connection request, follow these steps:

     1.   Make sure the modem and (optionally) /etc/rc.serial is configured
          correctly.
          +o   Use Hardware Handshake (CTS/RTS) for flow control.
          +o   Modem should be set to NO echo back (ATE0) and NO results string
              (ATQ1).

     2.   Edit /etc/ttys to enable a getty(8) on the port where the modem is
          attached.  For example:

                ttyd1 /usr/libexec/getty std.38400 dialup on secure

          Don't forget to send a HUP signal to the init(8) process to start
          the getty(8):

                # kill -HUP 1

     3.   Create a /usr/local/bin/ppplogin file with the following contents:

                #! /bin/sh
                exec /usr/sbin/ppp -direct incoming

          Direct mode (-direct) lets ppp work with stdin and stdout.  You can
          also use pppctl(8) to connect to a configured diagnostic port, in
          the same manner as with client-side ppp.

          Here, the incoming section must be set up in /etc/ppp/ppp.conf.

          Make sure that the incoming section contains the ``allow users''
          command as appropriate.

     4.   Prepare an account for the incoming user.

          ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin

          Refer to the manual entries for adduser(8) and vipw(8) for details.

     5.   Support for IPCP Domain Name Server and NetBIOS Name Server
          negotiation can be enabled using the ``accept dns'' and ``set nbns''
          commands.  Refer to their descriptions below.

RECEIVING INCOMING PPP CONNECTIONS (Method 2)
     This method differs in that we use ppp to authenticate the connection
     rather than login(1):

     1.   Configure your default section in /etc/gettytab with automatic ppp
          recognition by specifying the ``pp'' capability:

          default:\
                  :pp=/usr/local/bin/ppplogin:\
                  .....

     2.   Configure your serial device(s), enable a getty(8) and create
          /usr/local/bin/ppplogin as in the first three steps for method 1
          above.

     3.   Add either ``enable chap'' or ``enable pap'' (or both) to
          /etc/ppp/ppp.conf under the `incoming' label (or whatever label
          ppplogin uses).

     4.   Create an entry in /etc/ppp/ppp.secret for each incoming user:

          Pfred<TAB>xxxx
          Pgeorge<TAB>yyyy

     Now, as soon as getty(8) detects a ppp connection (by recognising the
     HDLC frame headers), it runs ``/usr/local/bin/ppplogin''.

     It is VITAL that either PAP or CHAP are enabled as above.  If they are
     not, you are allowing anybody to establish ppp session with your machine
     without a password, opening yourself up to all sorts of potential
     attacks.

AUTHENTICATING INCOMING CONNECTIONS
     Normally, the receiver of a connection requires that the peer
     authenticates itself.  This may be done using login(1), but
     alternatively, you can use PAP or CHAP.  CHAP is the more secure of the
     two, but some clients may not support it.  Once you decide which you wish
     to use, add the command `enable chap' or `enable pap' to the relevant
     section of ppp.conf.

     You must then configure the /etc/ppp/ppp.secret file.  This file contains
     one line per possible client, each line containing up to four fields:

           name key [hisaddr [label]]

     The name and key specify the client as expected.  If key is ``*'' and PAP
     is being used, ppp will look up the password database (passwd(5)) when
     authenticating.  If the client does not offer a suitable response based
     on any name / key combination in ppp.secret, authentication fails.

     If authentication is successful, hisaddr (if specified) is used when
     negotiating IP numbers.  See the ``set ifaddr'' command for details.

     If authentication is successful and label is specified, the current
     system label is changed to match the given label.  This will change the
     subsequent parsing of the ppp.linkup and ppp.linkdown files.

PPP OVER TCP (a.k.a Tunnelling)
     Instead of running ppp over a serial link, it is possible to use a TCP
     connection instead by specifying a host and port as the device:

           set device ui-gate:6669

     Instead of opening a serial device, ppp will open a TCP connection to the
     given machine on the given socket.  It should be noted however that ppp
     doesn't use the telnet protocol and will be unable to negotiate with a
     telnet server.  You should set up a port for receiving this PPP
     connection on the receiving machine (ui-gate).  This is done by first
     updating /etc/services to name the service:

           ppp-in 6669/tcp # Incoming PPP connections over TCP

     and updating /etc/inetd.conf to tell inetd(8) how to deal with incoming
     connections on that port:

           ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in

     Don't forget to send a HUP signal to inetd(8) after you've updated
     /etc/inetd.conf.  Here, we use a label named ``ppp-in''.  The entry in
     /etc/ppp/ppp.conf on ui-gate (the receiver) should contain the following:

           ppp-in:
            set timeout 0
            set ifaddr 10.0.4.1 10.0.4.2
            add 10.0.1.0/24 10.0.4.2

     You may also want to enable PAP or CHAP for security.  To enable PAP, add
     the following line:

            enable PAP

     You'll also need to create the following entry in /etc/ppp/ppp.secret:

           MyAuthName MyAuthPasswd

     If MyAuthPasswd is a (``*''), the password is looked up in the passwd(5)
     database.

     The entry in /etc/ppp/ppp.conf on awfulhak (the initiator) should contain
     the following:

           ui-gate:
            set escape 0xff
            set device ui-gate:ppp-in
            set dial
            set timeout 30
            set log Phase Chat Connect hdlc LCP IPCP CCP tun
            set ifaddr 10.0.4.2 10.0.4.1
            add 10.0.2.0/24 10.0.4.1

     Again, if you're enabling PAP, you'll also need:

            set authname MyAuthName
            set authkey MyAuthKey

     We're assigning the address of 10.0.4.1 to ui-gate, and the address
     10.0.4.2 to awfulhak.  To open the connection, just type

           awfulhak # ppp -background ui-gate

     The result will be an additional "route" on awfulhak to the 10.0.2.0/24
     network via the TCP connection, and an additional "route" on ui-gate to
     the 10.0.1.0/24 network.  The networks are effectively bridged - the
     underlying TCP connection may be across a public network (such as the
     Internet), and the PPP traffic is conceptually encapsulated (although not
     packet by packet) inside the TCP stream between the two gateways.  The
     major disadvantage of this mechanism is that there are two "guaranteed
     delivery" mechanisms in place - the underlying TCP stream and whatever
     protocol is used over the PPP link - probably TCP again.  If packets are
     lost, both levels will get in each others way trying to negotiate sending
     of the missing packet.

PACKET ALIASING
     The -alias command line option enables packet aliasing.  This allows the
     ppp host to act as a masquerading gateway for other computers over a
     local area network.  Outgoing IP packets are aliased so that they appear
     to come from the ppp host, and incoming packets are de-aliased so that
     they are routed to the correct machine on the local area network.  Packet
     aliasing allows computers on private, unregistered subnets to have
     Internet access, although they are invisible from the outside world.  In
     general, correct ppp operation should first be verified with packet
     aliasing disabled.  Then, the -alias option should be switched on, and
     network applications (web browser, telnet(1), ftp(1), ping(8),
     traceroute(8)) should be checked on the ppp host.  Finally, the same or
     similar applications should be checked on other computers in the LAN.  If
     network applications work correctly on the ppp host, but not on other
     machines in the LAN, then the masquerading software is working properly,
     but the host is either not forwarding or possibly receiving IP packets.
     Check that IP forwarding is enabled in /etc/rc.conf and that other
     machines have designated the ppp host as the gateway for the LAN.

PACKET FILTERING
     This implementation supports packet filtering. There are four kinds of
     filters; the in filter, the out filter, the dial filter and the alive
     filter.  Here are the basics:

     +o   A filter definition has the following syntax:

         set filter name rule-no action [src_addr[/width]] [dst_addr[/width]]
         [ proto [src [cmp port]] [dst [cmp port]] [estab] [syn] [finrst] ]

         1.   Name should be one of `in', `out', `dial' or `alive'.

         2.   Rule-no is a numeric value between `0' and `19' specifying the
              rule number.  Rules are specified in numeric order according to
              rule-no, but only if rule `0' is defined.

         3.   Action is either `permit' or `deny'.  If a given packet matches
              the rule, the associated action is taken immediately.

         4.   [src_addr[/width]] and [dst_addr[/width]] are the source and
              destination IP number specifications.  If [/width] is specified,
              it gives the number of relevant netmask bits, allowing the
              specification of an address range.

         5.   Proto must be one of `icmp', `udp' or `tcp'.

         6.   Cmp is one of `lt', `eq' or `gt', meaning less-than, equal and
              greater-than respectively.  Port can be specified as a numeric
              port or by service name from /etc/services.

         7.   The `estab', `syn', and `finrst' flags are only allowed when
              proto is set to `tcp', and represent the TH_ACK, TH_SYN and
              TH_FIN or TH_RST TCP flags respectively.

     +o   Each filter can hold up to 40 rules, starting from rule 0.  The
         entire rule set is not effective until rule 0 is defined, ie. the
         default is to allow everything through.

     +o   If no rule is matched to a packet, that packet will be discarded
         (blocked).

     +o   Use ``set filter name -1'' to flush all rules.

     See /etc/ppp/ppp.conf.sample.

SETTING THE IDLE TIMER
     To check/set the idle timer, use the ``show bundle'' and ``set timeout''
     commands:

           ppp ON awfulhak> set timeout 600

     The timeout period is measured in seconds, the  default value for which
     is 180 seconds (or 3 min).  To disable the idle timer function, use the
     command

           ppp ON awfulhak> set timeout 0

     In -ddial and -dedicated modes, the idle timeout is ignored.  In -auto
     mode, when the idle timeout causes the PPP session to be closed, the ppp
     program itself remains running.  Another trigger packet will cause it to
     attempt to re-establish the link.

PREDICTOR-1 and DEFLATE COMPRESSION
     Ppp supports both Predictor type 1 and deflate compression.  By default,
     ppp will attempt to use (or be willing to accept) both compression
     protocols when the peer agrees (or requests them).  The deflate protocol
     is preferred by ppp.  Refer to the ``disable'' and ``deny'' commands if
     you wish to disable this functionality.

     It is possible to use a different compression algorithm in each direction
     by using only one of ``disable deflate'' and ``deny deflate'' (assuming
     that the peer supports both algorithms).

     By default, when negotiating DEFLATE, ppp will use a window size of 15.
     Refer to the ``set deflate'' command if you wish to change this
     behaviour.

     A special algorithm called DEFLATE24 is also available, and is disabled
     and denied by default.  This is exactly the same as DEFLATE except that
     it uses CCP ID 24 to negotiate.  This allows ppp to successfully
     negotiate DEFLATE with pppd version 2.3.*.

CONTROLLING IP ADDRESS
     ppp uses IPCP to negotiate IP addresses. Each side of the connection
     specifies the IP address that it's willing to use, and if the requested
     IP address is acceptable then ppp returns ACK to the requester.
     Otherwise, ppp returns NAK to suggest that the peer use a different IP
     address. When both sides of the connection agree to accept the received
     request (and send ACK), IPCP is set to the open state and a network level
     connection is established.  To control this IPCP behaviour, this
     implementation has the ``set ifaddr'' command for defining the local and
     remote IP address:

           set ifaddr [src_addr [dst_addr [netmask [trigger_addr]]]]

     where, `src_addr' is the IP address that the local side is willing to
     use, `dst_addr' is the IP address which the remote side should use and
     `netmask' is the netmask that should be used.  `Src_addr' defaults to the
     current hostname(1), `dst_addr' defaults to 0.0.0.0, and `netmask'
     defaults to whatever mask is appropriate for `src_addr'.  It is only
     possible to make `netmask' smaller than the default.  The usual value is
     255.255.255.255, as most kernels ignore the netmask of a POINTOPOINT
     interface.

     Some incorrect PPP implementations require that the peer negotiates a
     specific IP address instead of `src_addr'.  If this is the case,
     `trigger_addr' may be used to specify this IP number.  This will not
     affect the routing table unless the other side agrees with this proposed
     number.

           set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0

     The above specification means:

     +o   I will first suggest that my IP address should be 0.0.0.0, but I will
         only accept an address of 192.244.177.38.
     +o   I strongly insist that the peer uses 192.244.177.2 as his own address
         and won't permit the use of any IP address but 192.244.177.2.  When
         the peer requests another IP address, I will always suggest that it
         uses 192.244.177.2.
     +o   The routing table entry will have a netmask of 0xffffffff.

     This is all fine when each side has a pre-determined IP address, however
     it is often the case that one side is acting as a server which controls
     all IP addresses and the other side should obey the direction from it.
     In order to allow more flexible behaviour, `ifaddr' variable allows the
     user to specify IP address more loosely:

           set ifaddr 192.244.177.38/24 192.244.177.2/20

     A number followed by a slash (/) represent the number of bits significant
     in the IP address.  The above example signifies that:

     +o   I'd like to use 192.244.177.38 as my address if it is possible, but
         I'll also accept any IP address between 192.244.177.0 and
         192.244.177.255.
     +o   I'd like to make him use 192.244.177.2 as his own address, but I'll
         also permit him to use any IP address between 192.244.176.0 and
         192.244.191.255.
     +o   As you may have already noticed, 192.244.177.2 is equivalent to
         saying 192.244.177.2/32.
     +o   As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
         preferred IP address and will obey the remote peers selection.  When
         using zero, no routing table entries will be made until a connection
         is established.
     +o   192.244.177.2/0 means that I'll accept/permit any IP address but I'll
         try to insist that 192.244.177.2 be used first.

CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
     The following steps should be taken when connecting to your ISP:

     1.   Describe your providers phone number(s) in the dial script using the
          ``set phone'' command.  This command allows you to set multiple
          phone numbers for dialing and redialing separated by either a pipe
          (|) or a colon (:)

                set phone "111[|222]...[:333[|444]...]...

          Numbers after the first in a pipe-separated list are only used if
          the previous number was used in a failed dial or login script.
          Numbers separated by a colon are used sequentially, irrespective of
          what happened as a result of using the previous number.  For
          example:

                set phone "1234567|2345678:3456789|4567890"

          Here, the 1234567 number is attempted.  If the dial or login script
          fails, the 2345678 number is used next time, but *only* if the dial
          or login script fails.  On the dial after this, the 3456789 number
          is used.  The 4567890 number is only used if the dial or login
          script using the 3456789 fails.  If the login script of the 2345678
          number fails, the next number is still the 3456789 number.  As many
          pipes and colons can be used as are necessary (although a given site
          would usually prefer to use either the pipe or the colon, but not
          both).  The next number redial timeout is used between all numbers.
          When the end of the list is reached, the normal redial period is
          used before starting at the beginning again.  The selected phone
          number is substituted for the \\T string in the ``set dial'' command
          (see below).

     2.   Set up your redial requirements using ``set redial''.  For example,
          if you have a bad telephone line or your provider is usually engaged
          (not so common these days), you may want to specify the following:

                set redial 10 4

          This says that up to 4 phone calls should be attempted with a pause
          of 10 seconds before dialing the first number again.

     3.   Describe your login procedure using the ``set dial'' and ``set
          login'' commands.  The ``set dial'' command is used to talk to your
          modem and establish a link with your ISP, for example:

                set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 4 \"\" \
                  ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT"

          This modem "chat" string means:

          +o   Abort if the string "BUSY" or "NO CARRIER" are received.

          +o   Set the timeout to 4 seconds.

          +o   Expect nothing.

          +o   Send ATZ.

          +o   Expect OK.  If that's not received within the 4 second timeout,
              send ATZ and expect OK.

          +o   Send ATDTxxxxxxx where xxxxxxx is the next number in the phone
              list from above.

          +o   Set the timeout to 60.

          +o   Wait for the CONNECT string.

          Once the connection is established, the login script is executed.
          This script is written in the same style as the dial script, but
          care should be taken to avoid having your password logged:

                set authkey MySecret
                set login "TIMEOUT 15 login:-\\r-login: awfulhak \
                  word: \\P ocol: PPP HELLO"

          This login "chat" string means:

          +o   Set the timeout to 15 seconds.

          +o   Expect "login:".  If it's not received, send a carriage return
              and expect "login:" again.

          +o   Send "awfulhak"

          +o   Expect "word:" (the tail end of a "Password:" prompt).

          +o   Send whatever our current authkey value is set to.

          +o   Expect "ocol:" (the tail end of a "Protocol:" prompt).

          +o   Send "PPP".

          +o   Expect "HELLO".

          The ``set authkey'' command is logged specially (when using command
          logging) so that the actual password is not compromised (it is
          logged as `********'), and the '\P' is logged when chat logging is
          active rather than the actual password.

          Login scripts vary greatly between ISPs.  If you're setting one up
          for the first time, ENABLE CHAT LOGGING so that you can see if your
          script is behaving as you expect.

     4.   Use ``set line'' and ``set speed'' to specify your serial line and
          speed, for example:

                set line /dev/cuaa0
                set speed 115200

          Cuaa0 is the first serial port on FreeBSD.  If you're running ppp on
          OpenBSD, cua00 is the first.  A speed of 115200 should be specified
          if you have a modem capable of bit rates of 28800 or more.  In
          general, the serial speed should be about four times the modem
          speed.

     5.   Use the ``set ifaddr'' command to define the IP address.

          +o   If you know what IP address your provider uses, then use it as
              the remote address (dst_addr), otherwise choose something like
              10.0.0.2/0 (see below).

          +o   If your provider has assigned a particular IP address to you,
              then use it as your address (src_addr).

          +o   If your provider assigns your address dynamically, choose a
              suitably unobtrusive and unspecific IP number as your address.
              10.0.0.1/0 would be appropriate.  The bit after the / specifies
              how many bits of the address you consider to be important, so if
              you wanted to insist on something in the class C network
              1.2.3.0, you could specify 1.2.3.1/24.

          +o   If you find that your ISP accepts the first IP number that you
              suggest, specify third and forth arguments of ``0.0.0.0''.  This
              will force your ISP to assign a number.  (The third argument
              will be ignored as it is less restrictive than the default mask
              for your `src_addr'.

          An example for a connection where you don't know your IP number or
          your ISPs IP number would be:

                set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0

     6.   In most cases, your ISP will also be your default router.  If this
          is the case, add the line

                add default HISADDR

          to /etc/ppp/ppp.conf.

          This tells ppp to add a default route to whatever the peer address
          is (10.0.0.2 in this example).  This route is `sticky', meaning that
          should the value of HISADDR change, the route will be updated
          accordingly.

          Previous versions of ppp required a similar entry in the
          /etc/ppp/ppp.linkup file.  Since the advent of `sticky routes', this
          is no longer required.

     7.   If your provider requests that you use PAP/CHAP authentication
          methods, add the next lines to your /etc/ppp/ppp.conf file:

                set authname MyName
                set authkey MyPassword

          Both are accepted by default, so ppp will provide whatever your ISP
          requires.

          It should be noted that a login script is rarely (if ever) required
          when PAP or CHAP are in use.

     8.   Ask your ISP to authenticate your nameserver address(es) with the
          line

                enable dns
          Do NOT do this if you are running an local DNS, as ppp will simply
          circumvent its use by entering some nameserver lines in
          /etc/resolv.conf.

     Please refer to /etc/ppp/ppp.conf.sample and /etc/ppp/ppp.linkup.sample
     for some real examples.  The pmdemand label should be appropriate for
     most ISPs.

LOGGING FACILITY
     Ppp is able to generate the following log info either via syslog(3) or
     directly to the screen:

        Async      Dump async level packet in hex.
        CBCP       Generate CBCP (CallBack Control Protocol) logs.
        CCP        Generate a CCP packet trace.
        Chat       Generate `dial', `login' and `hangup' chat script trace
                   logs.
        Command    Log commands executed either from the command line or any
                   of the configuration files.
        Connect    Log Chat lines containing the string "CONNECT".
        Debug      Log debug information.
        HDLC       Dump HDLC packet in hex.
        ID0        Log all function calls specifically made as user id 0.
        IPCP       Generate an IPCP packet trace.
        LCP        Generate an LCP packet trace.
        LQM        Generate LQR reports.
        Phase      Phase transition log output.
        TCP/IP     Dump all TCP/IP packets.
        Timer      Log timer manipulation.
        TUN        Include the tun device on each log line.
        Warning    Output to the terminal device.  If there is currently no
                   terminal, output is sent to the log file using syslogs
                   LOG_WARNING.
        Error      Output to both the terminal device and the log file using
                   syslogs LOG_ERROR.
        Alert      Output to the log file using LOG_ALERT.

     The ``set log'' command allows you to set the logging output level.
     Multiple levels can be specified on a single command line.  The default
     is equivalent to ``set log Phase''.

     It is also possible to log directly to the screen.  The syntax is the
     same except that the word ``local'' should immediately follow ``set
     log''.  The default is ``set log local'' (ie. only the un-maskable
     warning, error and alert output).

     If The first argument to ``set log [local]'' begins with a '+' or a '-'
     character, the current log levels are not cleared, for example:

           PPP ON awfulhak> set log phase
           PPP ON awfulhak> show log
           Log:   Phase Warning Error Alert
           Local: Warning Error Alert
           PPP ON awfulhak> set log +tcp/ip -warning
           PPP ON awfulhak> set log local +command
           PPP ON awfulhak> show log
           Log:   Phase TCP/IP Warning Error Alert
           Local: Command Warning Error Alert

     Log messages of level Warning, Error and Alert are not controllable using
     ``set log [local]''.

     The Warning level is special in that it will not be logged if it can be
     displayed locally.

SIGNAL HANDLING
     Ppp deals with the following signals:

     INT
         Receipt of this signal causes the termination of the current
         connection (if any).  This will cause ppp to exit unless it is in
         -auto or -ddial mode.

     HUP, TERM & QUIT
         These signals tell ppp to exit.

     USR2
         This signal, tells ppp to close any existing server socket, dropping
         all existing diagnostic connections.

MULTI-LINK PPP
     If you wish to use more than one physical link to connect to a PPP peer,
     that peer must also understand the MULTI-LINK PPP protocol.  Refer to RFC
     1990 for specification details.

     The peer is identified using a combination of his ``endpoint
     discriminator'' and his ``authentication id''.  Either or both of these
     may be specified.  It is recommended that at least one is specified,
     otherwise there is no way of ensuring that all links are actually
     connected to the same peer program, and some confusing lock-ups may
     result.  Locally, these identification variables are specified using the
     ``set enddisc'' and ``set authname'' commands.  The `authname' (and
     `authkey') must be agreed in advance with the peer.

     Multi-link capabilities are enabled using the ``set mrru'' command (set
     maximum reconstructed receive unit).  Once multi-link is enabled, ppp
     will attempt to negotiate a multi-link connection with the peer.

     By default, only one `link' is available (called `deflink').  To create
     more links, the ``clone'' command is used.  This command will clone
     existing links, where all characteristics are the same except:

     1.   The new link has its own name as specified on the ``clone'' command
          line.

     2.   The new link is an `interactive' link.  It's mode may subsequently
          be changed using the ``set mode'' command.

     3.   The new link is in a `closed' state.

     A summary of all available links can be seen using the ``show links''
     command.

     Once a new link has been created, command usage varies.  All link
     specific commands must be prefixed with the ``link name'' command,
     specifying on which link the command is to be applied.  When only a
     single link is available, ppp is smart enough not to require the ``link
     name'' prefix.

     Some commands can still be used without specifying a link - resulting in
     an operation at the `bundle' level.  For example, once two or more links
     are available, the command ``show ccp'' will show CCP configuration and
     statistics at the multi-link level, and ``link deflink show ccp'' will
     show the same information at the ``deflink'' link level.

     Armed with this information, the following configuration might be used:

           mp:
            set timeout 0
            set log phase chat
            set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2
            set phone "123456789"
            set dial "ABORT BUSY ABORT NO\sCARRIER TIMEOUT 5 \"\" ATZ \
                      OK-AT-OK \\dATDT\\T TIMEOUT 45 CONNECT"
            set login
            set ifaddr 10.0.0.1/0 10.0.0.2/0
            set authname ppp
            set authkey ppppassword

            set mrru 1500
            clone 1,2,3
            link deflink remove

     Note how all cloning is done at the end of the configuration.  Usually,
     the link will be configured first, then cloned.  If you wish all links to
     be up all the time, you can add the following line to the end of your
     configuration.

             link 1,2,3 set mode ddial

     If you want the links to dial on demand, this command could be used:

             link * set mode auto

     Links may be tied to specific names by removing the ``set device'' line
     above, and specifying the following after the ``clone'' command:

            link 1 set device /dev/cuaa0
            link 2 set device /dev/cuaa1
            link 3 set device /dev/cuaa2

     Use the ``help'' command to see which commands require context (using the
     ``link'' command), which have optional context and which should not have
     any context.

     When ppp has negotiated MULTI-LINK mode with the peer, it creates a local
     domain socket in the /var/run directory.  This socket is used to pass
     link information (including the actual link file descriptor) between
     different ppp invocations.  This facilitates ppps ability to be run from
     a getty(8) or directly from /etc/gettydefs (using the `pp=' capability),
     without needing to have initial control of the serial line.  Once ppp
     negotiates multi-link mode, it will pass its open link to any already
     running process.  If there is no already running process, ppp will act as
     the master, creating the socket and listening for new connections.

PPP COMMAND LIST
     This section lists the available commands and their effect.  They are
     usable either from an interactive ppp session, from a configuration file
     or from a pppctl(8) or telnet(1) session.

     accept|deny|enable|disable option....
         These directives tell ppp how to negotiate the initial connection
         with the peer.  Each ``option'' has a default of either accept or
         deny and enable or disable.  ``Accept'' means that the option will be
         ACK'd if the peer asks for it.  ``Deny'' means that the option will
         be NAK'd if the peer asks for it.  ``Enable'' means that the option
         will be requested by us.  ``Disable'' means that the option will not
         be requested by us.

         ``Option'' may be one of the following:

         acfcomp
             Default: Enabled and Accepted.  ACFComp stands for Address and
             Control Field Compression.  Non LCP packets usually have very
             similar address and control fields - making them easily
             compressible.

         chap
             Default: Disabled and Accepted.  CHAP stands for Challenge
             Handshake Authentication Protocol.  Only one of CHAP and PAP
             (below) may be negotiated.  With CHAP, the authenticator sends a
             "challenge" message to its peer.  The peer uses a one-way hash
             function to encrypt the challenge and sends the result back.  The
             authenticator does the same, and compares the results.  The
             advantage of this mechanism is that no passwords are sent across
             the connection.  A challenge is made when the connection is first
             made.  Subsequent challenges may occur.  If you want to have your
             peer authenticate itself, you must ``enable chap''.  in
             /etc/ppp/ppp.conf, and have an entry in /etc/ppp/ppp.secret for
             the peer.

             When using CHAP as the client, you need only specify ``AuthName''
             and ``AuthKey'' in /etc/ppp/ppp.conf.  CHAP is accepted by
             default.  Some PPP implementations use "MS-CHAP" rather than MD5
             when encrypting the challenge.  MS-CHAP is a combination of MD4
             and DES.  If ppp was built on a machine with DES libraries
             available, it will respond to MS-CHAP authentication requests,
             but will never request them.

         deflate
             Default: Enabled and Accepted.  This option decides if deflate
             compression will be used by the Compression Control Protocol
             (CCP).  This is the same algorithm as used by the gzip(1)
             program.  Note: There is a problem negotiating deflate
             capabilities with pppd(8) - a PPP implementation available under
             many operating systems.  Pppd (version 2.3.1) incorrectly
             attempts to negotiate deflate compression using type 24 as the
             CCP configuration type rather than type 26 as specified in
             rfc1979.  Type 24 is actually specified as ``PPP Magna-link
             Variable Resource Compression'' in rfc1975!  Ppp is capable of
             negotiating with pppd, but only if ``deflate24'' is enabled and
             accepted.

         deflate24
             Default: Disabled and Denied.  This is a variance of the deflate
             option, allowing negotiation with the pppd(8) program.  Refer to
             the deflate section above for details.  It is disabled by default
             as it violates rfc1975.

         dns
             Default: Disabled and Denied.  This option allows DNS
             negotiation.

             If ``enabled,'' ppp will request that the peer confirms the
             entries in /etc/resolv.conf.  If the peer NAKs our request
             (suggesting new IP numbers), /etc/resolv.conf is updated and
             another request is sent to confirm the new entries.

             If ``accepted,'' ppp will answer any DNS queries requested by the
             peer rather than rejecting them.  The answer is taken from
             /etc/resolv.conf unless the ``set dns'' command is used as an
             override.

         lqr
             Default: Disabled and Accepted.  This option decides if Link
             Quality Requests will be sent or accepted.  LQR is a protocol
             that allows ppp to determine that the link is down without
             relying on the modems carrier detect.  When LQR is enabled, ppp
             sends the QUALPROTO option (see ``set lqrperiod'' below) as part
             of the LCP request.  If the peer agrees, both sides will exchange
             LQR packets at the agreed frequency, allowing detailed link
             quality monitoring by enabling LQM logging.  If the peer doesn't
             agree, ppp will send ECHO LQR requests instead.  These packets
             pass no information of interest, but they MUST be replied to by
             the peer.

             Whether using LQR or ECHO LQR, ppp will abruptly drop the
             connection if 5 unacknowledged packets have been sent rather than
             sending a 6th.  A message is logged at the PHASE level, and any
             appropriate ``reconnect'' values are honoured as if the peer were
             responsible for dropping the connection.

         pap
             Default: Disabled and Accepted.  PAP stands for Password
             Authentication Protocol.  Only one of PAP and CHAP (above) may be
             negotiated.  With PAP, the ID and Password are sent repeatedly to
             the peer until authentication is acknowledged or the connection
             is terminated.  This is a rather poor security mechanism.  It is
             only performed when the connection is first established.  If you
             want to have your peer authenticate itself, you must ``enable
             pap''.  in /etc/ppp/ppp.conf, and have an entry in
             /etc/ppp/ppp.secret for the peer (although see the ``passwdauth''
             option below).

             When using PAP as the client, you need only specify ``AuthName''
             and ``AuthKey'' in /etc/ppp/ppp.conf.  PAP is accepted by
             default.

         pred1
             Default: Enabled and Accepted.  This option decides if Predictor
             1 compression will be used by the Compression Control Protocol
             (CCP).

         protocomp
             Default: Enabled and Accepted.  This option is used to negotiate
             PFC (Protocol Field Compression), a mechanism where the protocol
             field number is reduced to one octet rather than two.

         shortseq
             Default: Enabled and Accepted.  This option determines if ppp
             will request and accept requests for short (12 bit) sequence
             numbers when negotiating multi-link mode.  This is only
             applicable if our MRRU is set (thus enabling multi-link).

         vjcomp
             Default: Enabled and Accepted.  This option determines if Van
             Jacobson header compression will be used.

         The following options are not actually negotiated with the peer.
         Therefore, accepting or denying them makes no sense.

         idcheck
             Default: Enabled.  When ppp exchanges low-level LCP, CCP and IPCP
             configuration traffic, the Identifier field of any replies is
             expected to be the same as that of the request.  By default, ppp
             drops any reply packets that do not contain the expected
             identifier field, reporting the fact at the respective log level.
             If idcheck is disabled, ppp will ignore the identifier field.

         loopback
             Default: Enabled.  When loopback is enabled, ppp will
             automatically loop back packets being sent out with a destination
             address equal to that of the PPP interface.  If disabled, ppp
             will send the packet, probably resulting in an ICMP redirect from
             the other end.  It is convenient to have this option enabled when
             the interface is also the default route as it avoids the
             necessity of a loopback route.

         passwdauth
             Default: Disabled.  Enabling this option will tell the PAP
             authentication code to use the password database (see passwd(5))
             to authenticate the caller if they cannot be found in the
             /etc/ppp/ppp.secret file.  /etc/ppp/ppp.secret is always checked
             first.  If you wish to use passwords from passwd(5), but also to
             specify an IP number or label for a given client, use ``*'' as
             the client password in /etc/ppp/ppp.secret.

         proxy
             Default: Disabled.  Enabling this option will tell ppp to proxy
             ARP for the peer.

         proxyall
             Default: Disabled.  Enabling this will tell ppp to add proxy arp
             entries for every IP address in all class C or smaller subnets
             routed via the tun interface.

         sroutes
             Default: Enabled.  When the ``add'' command is used with the
             HISADDR or MYADDR values, entries are stored in the `stick route'
             list.  Each time HISADDR or MYADDR change, this list is re-
             applied to the routing table.

             Disabling this option will prevent the re-application of sticky
             routes, although the `stick route' list will still be maintained.

         throughput
             Default: Enabled.  This option tells ppp to gather throughput
             statistics.  Input and output is sampled over a rolling 5 second
             window, and current, best and total figures are retained.  This
             data is output when the relevant PPP layer shuts down, and is
             also available using the ``show'' command.  Throughput statistics
             are available at the ``IPCP'' and ``modem'' levels.

         utmp
             Default: Enabled.  Normally, when a user is authenticated using
             PAP or CHAP, and when ppp is running in -direct mode, an entry is
             made in the utmp and wtmp files for that user.  Disabling this
             option will tell ppp not to make any utmp or wtmp entries.  This
             is usually only necessary if you require the user to both login
             and authenticate themselves.

         iface-alias
             Default: Enabled if -alias is specified.  This option simply
             tells ppp to add new interface addresses to the interface rather
             than replacing them.  The option can only be enabled if IP
             aliasing is enabled (``alias enable yes'').

             With this option enabled, ppp will pass traffic for old interface
             addresses through the IP alias engine (see libalias(5)),
             resulting in the ability (in -auto mode) to properly connect the
             process that caused the PPP link to come up in the first place.

             Disabling IP aliasing with ``alias enable off'' will also disable
             `iface-alias'.

     add[!] dest[/nn] [mask] gateway
         Dest is the destination IP address.  The netmask is specified either
         as a number of bits with /nn or as an IP number using mask.  0 0 or
         simply 0 with no mask refers to the default route.  It is also
         possible to use the literal name `default' instead of 0.  Gateway is
         the next hop gateway to get to the given dest machine/network.  Refer
         to the route(8) command for further details.

         It is possible to use the symbolic names `MYADDR' or `HISADDR' as the
         destination, and `HISADDR' as the gateway.  `MYADDR' is replaced with
         the interface address and `HISADDR' is replaced with the interface
         destination (peer) address.

         If the add! command is used (note the trailing ``!''), then if the
         route already exists, it will be updated as with the `route change'
         command (see route(8) for further details).

         Routes that contain the ``HISADDR'' or ``MYADDR'' constants are
         considered `sticky'.  They are stored in a list (use ``show ipcp'' to
         see the list), and each time the value of HISADDR or MYADDR changes,
         the appropriate routing table entries are updated.  This facility may
         be disabled using ``disable sroutes''.

     allow command [args]
         This command controls access to ppp and its configuration files.  It
         is possible to allow user-level access, depending on the
         configuration file label and on the mode that ppp is being run in.
         For example, you may wish to configure ppp so that only user `fred'
         may access label `fredlabel' in -background mode.

         User id 0 is immune to these commands.

         allow user[s] logname...
             By default, only user id 0 is allowed access to ppp.  If this
             command is used, all of the listed users are allowed access to
             the section in which the ``allow users'' command is found.  The
             `default' section is always checked first (even though it is only
             ever automatically loaded at startup).  Each successive ``allow
             users'' command overrides the previous one, so it's possible to
             allow users access to everything except a given label by
             specifying default users in the `default' section, and then
             specifying a new user list for that label.

             If user `*' is specified, access is allowed to all users.

         allow mode[s] modelist...
             By default, access using any ppp mode is possible.  If this
             command is used, it restricts the access mode allowed to load the
             label under which this command is specified.  Again, as with the
             ``allow users'' command, each ``allow modes'' command overrides
             the previous, and the `default' section is always checked first.

             Possible modes are: `interactive', `auto', `direct', `dedicated',
             `ddial', `background' and `*'.

             When running in multi-link mode, a section can be loaded if it
             allows any of the currently existing line modes.

     alias command [args]
         This command allows the control of the aliasing (or masquerading)
         facilities that are built into ppp.  If aliasing is enabled on your
         system (it may be omitted at compile time), the following commands
         are possible:

         alias enable [yes|no]
             This command either switches aliasing on or turns it off.  The
             -alias command line flag is synonymous with ``alias enable yes''.

         alias port [proto targetIP:targetPORT [aliasIP:]aliasPORT]
             This command allows us to redirect connections arriving at
             aliasPORT for machine aliasIP to targetPORT on targetIP.  Proto
             may be either `tcp' or `udp', and only connections of the given
             protocol are matched.  This option is useful if you wish to run
             things like Internet phone on the machines behind your gateway.

         alias addr [addr_local addr_alias]
             This command allows data for addr_alias to be redirected to
             addr_local.  It is useful if you own a small number of real IP
             numbers that you wish to map to specific machines behind your
             gateway.

         alias deny_incoming [yes|no]
             If set to yes, this command will refuse all incoming connections
             by dropping the packets in much the same way as a firewall would.

         alias help|?
             This command gives a summary of available alias commands.

         alias log [yes|no]
             This option causes various aliasing statistics and information to
             be logged to the file /var/log/alias.log.

         alias same_ports [yes|no]
             When enabled, this command will tell the alias library attempt to
             avoid changing the port number on outgoing packets.  This is
             useful if you want to support protocols such as RPC and LPD which
             require connections to come from a well known port.

         alias use_sockets [yes|no]
             When enabled, this option tells the alias library to create a
             socket so that it can guarantee a correct incoming ftp data or
             IRC connection.

         alias unregistered_only [yes|no]
             Only alter outgoing packets with an unregistered source ad-
             dress.  According to RFC 1918, unregistered source addresses are
             10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.

         These commands are also discussed in the file README.alias which
         comes with the source distribution.

     [!]bg command
         The given command is executed in the background with the following
         words replaced:

         AUTHNAME      This is replaced with the local authname value.  See
                       the ``set authname'' command below.

         ENDDISC       This is replaced with the local endpoint discriminator
                       value.  See the ``set enddisc'' command below.

         HISADDR       This is replaced with the peers IP number.

         INTERFACE     This is replaced with the name of the interface that's
                       in use.

         LABEL         This is replaced with the last label name used.  A
                       label may be specified on the ppp command line, via the
                       ``load'' or ``dial'' commands and in the ppp.secret
                       file.

         MYADDR        This is replaced with the IP number assigned to the
                       local interface.

         PEER_ENDDISC  This is replaced with the value of the peers endpoint
                       discriminator.

         PROCESSID     This is replaced with the current process id.

         USER          This is replaced with the username that has been
                       authenticated with PAP or CHAP.  Normally, this
                       variable is assigned only in -direct mode.  This value
                       is available irrespective of whether utmp logging is
                       enabled.

         These substitutions are also done by the ``set proctitle'' command.

         If you wish to pause ppp while the command executes, use the
         ``shell'' command instead.

     clear modem|ipcp [current|overall|peak...]
         Clear the specified throughput values at either the ``modem'' or
         ``ipcp'' level.  If ``modem'' is specified, context must be given
         (see the ``link'' command below).  If no second argument is given,
         all values are cleared.

     clone name[,name]...
         Clone the specified link, creating one or more new links according to
         the name argument(s).  This command must be used from the ``link''
         command below unless you've only got a single link (in which case
         that link  becomes the default).  Links may be removed using the
         ``remove'' command below.

         The default link name is ``deflink''.

     close [lcp|ccp[!]]
         If no arguments are given, the relevant protocol layers will be
         brought down and the link will be closed.  If ``lcp'' is specified,
         the LCP layer is brought down, but ppp will not bring the link
         offline.  It is subsequently possible to use ``term'' (see below) to
         talk to the peer machine if, for example, something like ``slirp'' is
         being used.  If ``ccp'' is specified, only the relevant compression
         layer is closed.  If the ``!'' is used, the compression layer will
         remain in the closed state, otherwise it will re-enter the STOPPED
         state, waiting for the peer to initiate further CCP negotiation.  In
         any event, this command does not disconnect the user from ppp or exit
         ppp.  See the ``quit'' command below.

     delete[!] dest
         This command deletes the route with the given dest IP address.  If
         dest is specified as `ALL', all non-direct entries in the routing
         table for the current interface, and all `sticky route' entries are
         deleted.  If dest is specified as `default', the default route is
         deleted.

         If the delete! command is used (note the trailing ``!''), ppp will
         not complain if the route does not already exist.

     dial|call [label]
         When used with no argument, this command is the same as the ``open''
         command.  When one or more label is specified, a ``load'' will be
         done first.

     down [lcp|ccp]
         Bring the relevant layer down ungracefully, as if the underlying
         layer had become unavailable.  It's not considered polite to use this
         command on a Finite State Machine that's in the OPEN state.  If no
         arguments are supplied, the entire link is closed (or if no context
         is given, all links are terminated).  If `lcp' is specified, the LCP
         layer is terminated but the modem is not brought offline and the link
         is not closed.  If `ccp' is specified, only the relevant compression
         layer(s) are terminated.

     help|? [command]
         Show a list of available commands.  If command is specified, show the
         usage string for that command.

     iface command [args]
         This command is used to control the interface used by ppp.  Command
         may be one of the following:

         iface add[!] addr[[/bits| mask] peer]
             Add the given addr mask peer combination to the interface.
             Instead of specifying mask, /bits can be used (with no space
             between it and addr).  If the given address already exists, the
             command fails unless the ``!'' is used - in which case the
             previous interface address entry is overwritten with the new one,
             allowing a change of netmask or peer address.

             If only addr is specified, bits defaults to ``32'' and peer
             defaults to ``255.255.255.255''.  This address (the broadcast
             address) is the only duplicate peer address that ppp allows.

         iface clear
             If this command is used while ppp is in the OPENED state or while
             in -auto mode, all addresses except for the IPCP negotiated
             address are deleted from the interface.  If ppp is not in the
             OPENED state and is not in -auto mode, all interface addresses
             are deleted.

         iface delete[!]|rm[!] addr
             This command deletes the given addr from the interface.  If the
             ``!'' is used, no error is given if the address isn't currently
             assigned to the interface (and no deletion takes place).

         iface show
             Shows the current state and current addresses for the interface.
             It is much the same as running ``ifconfig INTERFACE''.

         iface help [sub-command]
             This command, when invoked without sub-command, will show a list
             of possbile ``iface'' sub-commands and a brief synopsis for each.
             When invoked with sub-command, only the synopsis for the given
             sub-command is shown.

     [data]link name[,name...] command [args]
         This command may prefix any other command if the user wishes to
         specify which link the command should affect.  This is only
         applicable after multiple links have been created in Multi-link mode
         using the ``clone'' command.

         Name specifies the name of an existing link.  If name is a comma
         separated list, command is executed on each link.  If name is ``*'',
         command is executed on all links.

     load [label ...]
         Load the given label(s) from the ppp.conf file.  If label is not
         given, the default label is used.

     open [lcp|ccp|ipcp]
         This is the opposite of the ``close'' command.  Using ``open'' with
         no arguments is the same as using ``dial'' with no arguments, where
         all closed links are brought up (some auto links may not come up
         based on the ``set autoload'' command) using the current
         configuration.

         If the ``lcp'' while the LCP layer is already open, LCP will be
         renegotiated.  This allows various LCP options to be changed, after
         which ``open lcp'' can be used to put them into effect.  After
         renegotiating LCP, any agreed authentication will also take place.

         If the ``ccp'' argument is used, the relevant compression layer is
         opened.  Again, if it is already open, it will be renegotiated.

         If the ``ipcp'' argument is used, the link will be brought up as
         normal, but if IPCP is already open, it will be renegotiated and the
         network interface will be reconfigured.

         It is probably not good practice to re-open the PPP state machines
         like this as it's possible that the peer will not behave correctly.
         It is however useful as a way of forcing the CCP or VJ dictionaries
         to be reset.

     passwd pass
         Specify the password required for access to the full ppp command set.
         This password is required when connecting to the diagnostic port (see
         the ``set server'' command).  Pass is specified on the ``set server''
         command line.  The value of pass is not logged when command logging
         is active, instead, the literal string `********' is logged.

     quit|bye [all]
         If ``quit'' is executed from the controlling connection or from a
         command file, ppp will exit after closing all connections.
         Otherwise, if the user is connected to a diagnostic socket, the
         connection is simply dropped.

         If the all argument is given, ppp will exit despite the source of the
         command after closing all existing connections.

     remove|rm
         This command removes the given link.  It is only really useful in
         multi-link mode.  A link must be in the CLOSED state before it is
         removed.

     rename|mv name
         This command renames the given link to name.  It will fail if name is
         already used by another link.

         The default link name is `deflink'.  Renaming it to `modem', `cuaa0'
         or `USR' may make the log file more readable.

     save
         This option is not (yet) implemented.

     set[up] var value
         This option allows the setting of any of the following variables:

         set accmap hex-value
             ACCMap stands for Asynchronous Control Character Map.  This is
             always negotiated with the peer, and defaults to a value of
             00000000 in hex.  This protocol is required to defeat hardware
             that depends on passing certain characters from end to end (such
             as XON/XOFF etc).

             For the XON/XOFF scenario, use ``set accmap 000a0000''.

         set authkey|key value
             This sets the authentication key (or password) used in client
             mode PAP or CHAP negotiation to the given value.  It can also be
             used to specify the password to be used in the dial or login
             scripts in place of the '\P' sequence, preventing the actual
             password from being logged.  If command logging is in effect,
             value is logged as `********' for security reasons.

         set authname id
             This sets the authentication id used in client mode PAP or CHAP
             negotiation.

             If used in -direct mode with PAP or CHAP enabled, id is used in
             the initial authentication request and is normally set to the
             local machine name.

         set autoload max-duration max-load [min-duration min-load]
             These settings apply only in multi-link mode and all default to
             zero.  When more than one demand-dial (also known as -auto) mode
             link is available, only the first link is made active when ppp
             first reads data from the tun device.  The next demand-dial link
             will be opened only when at least max-load packets have been in
             the send queue for max-duration seconds.  Because both values
             default to zero, demand-dial links will simply come up one at a
             time by default.

             If two or more links are open, at least one of which is a
             demand-dial link, a demand-dial link will be closed when there is
             less than min-packets in the queue for more than min-duration.
             If min-duration is zero, this timer is disabled.  Because both
             values default to zero, demand-dial links will stay active until
             the bundle idle timer expires.

         set callback [none|auth|cbcp|E.164 *|number[,number]...]...
             If no arguments are given, callback is disabled, otherwise, ppp
             will request (or in -direct mode, will accept) one of the given
             protocols.  In client mode, if a request is NAK'd ppp will
             request another, until no options remain at which point ppp will
             terminate negotiations.  In server mode, ppp will accept any of
             the given protocols - but the client must request one of them.
             If you wish callback to be optional, you must include none as an
             option.

             The options are as follows (in this order of preference):

             auth   The callee is expected to decide the callback number based
                    on authentication.  If ppp is the callee, the number
                    should be specified as the fifth field of the peers entry
                    in /etc/ppp/ppp.secret.

             cbcp   Microsofts callback control protocol is used.  See ``set
                    cbcp'' below.

             E.164 *|number[,number]...
                    The caller specifies the number.  If ppp is the callee,
                    number should be either a comma seperated list of
                    allowable numbers or a ``*'', meaning any number is
                    permitted.  If ppp is the caller, only a single number
                    should be specified.

                    Note, this option is very unsafe when used with a ``*'' as
                    a malicious caller can tell ppp to call any (possibly
                    international) number without first authenticating
                    themselves.

             none   If the peer does not wish to do callback at all, ppp will
                    accept the fact and continue without callback rather than
                    terminating the connection.  This is required if you wish
                    callback to be optional.

         set cbcp [*|number[,number]... [delay [retry]]]
             If no arguments are given, CBCP (Microsofts CallBack Control
             Protocol) is disabled - ie, configuring CBCP in the ``set
             callback'' command will result in ppp requesting no callback in
             the CBCP phase.  Otherwise, ppp attempts to use the given phone
             number(s).

             In server mode (-direct), ppp will insist that the client uses
             one of these numbers, unless ``*'' is used in which case the
             client is expected to specify the number.

             In client mode, ppp will attempt to use one of the given numbers
             (whichever it finds to be agreeable with the peer), or if ``*''
             is specified, ppp will expect the peer to specify the number.

         set choked [timeout]
             This sets the number of seconds that ppp will keep a choked
             output queue before dropping all pending output packets.  If
             timeout is less than or equal to zero or if timeout isn't
             specified, it is set to the default value of 120 seconds.

             A choked output queue occurs when ppp has read a certain number
             of packets from the local network for transmission, but cannot
             send the data due to link failure (the peer is busy etc.).  Ppp
             will not read packets indefinitely.  Instead, it reads up to 20
             packets (or 20 + nlinks * 2 packets in multi-link mode), then
             stops reading the network interface until either timeout seconds
             have passed or at least one packet has been sent.

             If timeout seconds pass, all pending output packets are dropped.

         set ctsrts|crtscts on|off
             This sets hardware flow control.  Hardware flow control is on by
             default.

         set deflate out-winsize [in-winsize]
             This sets the DEFLATE algorithms default outgoing and incoming
             window sizes.  Both out-winsize and in-winsize must be values
             between 8 and 15.  If in-winsize is specified, ppp will insist
             that this window size is used and will not accept any other
             values from the peer.

         set dns [primary [secondary]]
             This command specifies DNS overrides for the ``accept dns''
             command.  Refer to the ``accept'' command description above for
             details.  This command does not affect the IP numbers requested
             using ``enable dns''.

         set device|line value[,value...]
             This sets the device(s) to which ppp will talk to the given
             ``value''.  All serial device names are expected to begin with
             /dev/.  If ``value'' does not begin with /dev/, it must either
             begin with an exclamation mark (``!'') or be of the format
             ``host:port''.

             If it begins with an exclamation mark, the rest of the device
             name is treated as a program name, and that program is executed
             when the device is opened.  Standard input, output and error are
             fed back to ppp and are read and written as if they were a
             regular device.

             If a ``host:port'' pair is given, ppp will attempt to connect to
             the given ``host'' on the given ``port''.  Refer to the section
             on PPP OVER TCP above for further details.

             If multiple ``values'' are specified, ppp will attempt to open
             each one in turn until it succeeds or runs out of devices.

         set dial chat-script
             This specifies the chat script that will be used to dial the
             other side.  See also the ``set login'' command below.  Refer to
             chat(8) and to the example configuration files for details of the
             chat script format.  It is possible to specify some special
             `values' in your chat script as follows:

         \\\\c
             When used as the last character in a `send' string, this
             indicates that a newline should not be appended.

         \\\\d
             When the chat script encounters this sequence, it delays two
             seconds.

         \\\\p
             When the chat script encounters this sequence, it delays for one
             quarter of a second.

         \\\\n
             This is replaced with a newline character.

         \\\\r
             This is replaced with a carriage return character.

         \\\\s
             This is replaced with a space character.

         \\\\t
             This is replaced with a tab character.

         \\\\T
             This is replaced by the current phone number (see ``set phone''
             below).

         \\\\P
             This is replaced by the current authkey value (see ``set
             authkey'' above).

         \\\\U
             This is replaced by the current authname value (see ``set
             authname'' above).

             Note that two parsers will examine these escape sequences, so in
             order to have the `chat parser' see the escape character, it is
             necessary to escape it from the `command parser'.  This means
             that in practice you should use two escapes, for example:

                   set dial "... ATDT\\T CONNECT"

             It is also possible to execute external commands from the chat
             script.  To do this, the first character of the expect or send
             string is an exclamation mark (``!'').  When the command is
             executed, standard input and standard output are directed to the
             modem device (see the ``set device'' command), and standard error
             is read by ppp and substituted as the expect or send string.  If
             ppp is running in interactive mode, file descriptor 3 is attached
             to /dev/tty.

             For example (wrapped for readability);

                   set login "TIMEOUT 5 \"\" \"\" login:--login: ppp \
                   word: ppp \"!sh \\\\-c \\\"echo \\\\-n label: >&2\\\"\" \
                   \"!/bin/echo in\" HELLO"

             would result in the following chat sequence (output using the
             `set log local chat' command before dialing):

                   Dial attempt 1 of 1
                   dial OK!
                   Chat: Expecting:
                   Chat: Sending:
                   Chat: Expecting: login:--login:
                   Chat: Wait for (5): login:
                   Chat: Sending: ppp
                   Chat: Expecting: word:
                   Chat: Wait for (5): word:
                   Chat: Sending: ppp
                   Chat: Expecting: !sh \-c "echo \-n label: >&2"
                   Chat: Exec: sh -c "echo -n label: >&2"
                   Chat: Wait for (5): !sh \-c "echo \-n label: >&2" --> label:
                   Chat: Exec: /bin/echo in
                   Chat: Sending:
                   Chat: Expecting: HELLO
                   Chat: Wait for (5): HELLO
                   login OK!

             Note (again) the use of the escape character, allowing many
             levels of nesting.  Here, there are four parsers at work.  The
             first parses the original line, reading it as three arguments.
             The second parses the third argument, reading it as 11 arguments.
             At this point, it is important that the ``-'' signs are escaped,
             otherwise this parser will see them as constituting an expect-
             send-expect sequence.  When the ``!'' character is seen, the
             execution parser reads the first command as three arguments, and
             then sh(1) itself expands the argument after the -c.  As we wish
             to send the output back to the modem, in the first example we
             redirect our output to file descriptor 2 (stderr) so that ppp
             itself sends and logs it, and in the second example, we just
             output to stdout, which is attached directly to the modem.

             This, of course means that it is possible to execute an entirely
             external ``chat'' command rather than using the internal one.
             See chat(8) for a good alternative.

         set enddisc [label|IP|MAC|magic|psn value]
             This command sets our local endpoint discriminator.  If set prior
             to LCP negotiation, ppp will send the information to the peer
             using the LCP endpoint discriminator option.  The following
             discriminators may be set:

         label
             The current label is used.

         IP  Our local IP number is used.  As LCP is negotiated prior to IPCP,
             it is possible that the IPCP layer will subsequently change this
             value.  If it does, the endpoint discriminator stays at the old
             value unless manually reset.

         MAC
             This is similar to the IP option above, except that the MAC
             address associated with the local IP number is used.  If the
             local IP number is not resident on any Ethernet interface, the
             command will fail.

             As the local IP number defaults to whatever the machine host name
             is, ``set enddisc mac'' is usually done prior to any ``set
             ifaddr'' commands.

         magic
             A 20 digit random number is used.

         psn value
             The given value is used.  Value should be set to an absolute
             public switched network number with the country code first.

             If no arguments are given, the endpoint discriminator is reset.

         set escape value...
             This option is similar to the ``set accmap'' option above.  It
             allows the user to specify a set of characters that will be
             `escaped' as they travel across the link.

         set filter dial|alive|in|out rule-no permit|deny [src_addr/width]
             [dst_addr/width] [proto [src [lt|eq|gt port]] [dst [lt|eq|gt
             port]] [estab] [syn] [finrst]]
             Ppp supports four filter sets.  The alive filter specifies
             packets that keep the connection alive - reseting the idle timer.
             The dial filter specifies packets that cause ppp to dial when in
             -auto mode.  The in filter specifies packets that are allowed to
             travel into the machine and the out filter specifies packets that
             are allowed out of the machine.

             Filtering is done prior to any IP alterations that might be done
             by the alias engine.  By default all filter sets allow all
             packets to pass.  Rules are processed in order according to
             rule-no.  Up to 40 rules may be given for each set.  If a packet
             doesn't match any of the rules in a given set, it is discarded.
             In the case of in and out filters, this means that the packet is
             dropped.  In the case of alive filters it means that the packet
             will not reset the idle timer and in the case of dial filters it
             means that the packet will not trigger a dial.  A packet failing
             to trigger a dial will be dropped rather than queued.  Refer to
             the section on PACKET FILTERING above for further details.

         set hangup chat-script
             This specifies the chat script that will be used to reset the
             modem before it is closed.  It should not normally be necessary,
             but can be used for devices that fail to reset themselves
             properly on close.

         set help|? [command]
             This command gives a summary of available set commands, or if
             command is specified, the command usage is shown.

         set ifaddr [myaddr [hisaddr [netmask [triggeraddr]]]]
             This command specifies the IP addresses that will be used during
             IPCP negotiation.  Addresses are specified using the format

                   a.b.c.d/n

             Where a.b.c.d is the preferred IP, but n specifies how many bits
             of the address we will insist on.  If /n is omitted, it defaults
             to /32 unless the IP address is 0.0.0.0 in which case it defaults
             to /0.

             Hisaddr may also be specified as a range of IP numbers in the
             format

                   a.b.c.d[-d.e.f.g][,h.i.j.k[-l,m,n,o]]...

             for example:

                   set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20

             will only negotiate 10.0.0.1 as the local IP number, but may
             assign any of the given 10 IP numbers to the peer.  If the peer
             requests one of these numbers, and that number is not already in
             use, ppp will grant the peers request.  This is useful if the
             peer wants to re-establish a link using the same IP number as was
             previously allocated (thus maintaining any existing tcp
             connections).

             If the peer requests an IP number that's either outside of this
             range or is already in use, ppp will suggest a random unused IP
             number from the range.

             If triggeraddr is specified, it is used in place of myaddr in the
             initial IPCP negotiation.  However, only an address in the myaddr
             range will be accepted.  This is useful when negotiating with
             some PPP implementations that will not assign an IP number unless
             their peer requests 0.0.0.0.

             It should be noted that in -auto mode, ppp will configure the
             interface immediately upon reading the ``set ifaddr'' line in the
             config file.  In any other mode, these values are just used for
             IPCP negotiations, and the interface isn't configured until the
             IPCP layer is up.

             Note that the HISADDR argument may be overridden by the third
             field in the ppp.secret file once the client has authenticated
             itself (if PAP or CHAP are ``enabled'').  Refer to the
             AUTHENTICATING INCOMING CONNECTIONS section for details.

             In all cases, if the interface is already configured, ppp will
             try to maintain the interface IP numbers so that any existing
             bound sockets will remain valid.

         set ccpretry period

         set chapretry period

         set ipcpretry period

         set lcpretry period

         set papretry period
             These commands set the number of seconds that ppp will wait
             before resending Finite State Machine (FSM) Request packets.  The
             default period for all FSMs is 3 seconds (which should suffice in
             most cases).

         set log [local] [+|-]value...
             This command allows the adjustment of the current log level.
             Refer to the Logging Facility section for further details.

         set login chat-script
             This chat-script compliments the dial-script.  If both are
             specified, the login script will be executed after the dial
             script.  Escape sequences available in the dial script are also
             available here.

         set lqrperiod frequency
             This command sets the frequency in seconds at which LQR or ECHO
             LQR packets are sent.  The default is 30 seconds.  You must also
             use the ``enable lqr'' command if you wish to send LQR requests
             to the peer.

         set mode interactive|auto|ddial|background
             This command allows you to change the `mode' of the specified
             link.  This is normally only useful in multi-link mode, but may
             also be used in uni-link mode.

             It is not possible to change a link that is `direct' or
             `dedicated'.

             Note: If you issue the command ``set mode auto'', and have IP
             aliasing enabled, it may be useful to ``enable iface-alias''
             afterwards.  This will allow ppp to do the necessary address
             translations to enable the process that triggers the connection
             to connect once the link is up despite the peer assigning us a
             new (dynamic) IP address.

         set mrru [value]
             Setting this option enables Multi-link PPP negotiations, also
             known as Multi-link Protocol or MP.  There is no default MRRU
             (Maximum Reconstructed Receive Unit) value.  If no argument is
             given, multi-link mode is disabled.

         set mru [value]
             The default MRU (Maximum Receive Unit) is 1500.  If it is
             increased, the other side *may* increase its mtu.  There is no
             point in decreasing the MRU to below the default as the PPP
             protocol *must* be able to accept packets of at least 1500
             octets.  If no argument is given, 1500 is assumed.

         set mtu [value]
             The default MTU is 1500.  At negotiation time, ppp will accept
             whatever MRU or MRRU that the peer wants (assuming it's not less
             than 296 bytes).  If the MTU is set, ppp will not accept MRU/MRRU
             values less than value.  When negotiations are complete, the MTU
             is assigned to the interface, even if the peer requested a higher
             value MRU/MRRU.  This can be useful for limiting your packet size
             (giving better bandwidth sharing at the expense of more header
             data).

             If no value is given, 1500, or whatever the peer asks for is
             used.

         set nbns [x.x.x.x [y.y.y.y]]
             This option allows the setting of the Microsoft NetBIOS name
             server values to be returned at the peers request.  If no values
             are given, ppp will reject any such requests.

         set openmode active|passive [delay]
             By default, openmode is always active with a one second delay.
             That is, ppp will always initiate LCP/IPCP/CCP negotiation one
             second after the line comes up.  If you want to wait for the peer
             to initiate negotiations, you can use the value passive.  If you
             want to initiate negotiations immediately or after more than one
             second, the appropriate delay may be specified here in seconds.

         set parity odd|even|none|mark
             This allows the line parity to be set.  The default value is
             none.

         set phone telno[|telno]...[:telno[|telno]...]...
             This allows the specification of the phone number to be used in
             place of the \\T string in the dial and login chat scripts.
             Multiple phone numbers may be given separated by a pipe (|) or a
             colon (:).  Numbers after the pipe are only dialed if the dial or
             login script for the previous number failed.  Numbers separated
             by a colon are tried sequentially, irrespective of the reason the
             line was dropped.  If multiple numbers are given, ppp will dial
             them according to these rules until a connection is made,
             retrying the maximum number of times specified by ``set redial''
             below.  In -background mode, each number is attempted at most
             once.

         set [proc]title [value]
             The current process title as displayed by ps(1) is changed
             according to value.  If value is not specified, the original
             process title is restored.  All the word replacements done by the
             shell commands (see the ``bg'' command above) are done here too.

             Note, if USER is required in the process title, the ``set
             proctitle'' command must appear in ppp.linkup, as it is not known
             when the commands in ppp.conf are executed.

         set reconnect timeout ntries
             Should the line drop unexpectedly (due to loss of CD or LQR
             failure), a connection will be re-established after the given
             timeout.  The line will be re-connected at most ntries times.
             Ntries defaults to zero.  A value of random for timeout will
             result in a variable pause, somewhere between 0 and 30 seconds.

         set recvpipe [value]
             This sets the routing table RECVPIPE value.  The optimum value is
             just over twice the MTU value.  If value is unspecified or zero,
             the default kernel controlled value is used.

         set redial seconds[.nseconds] [attempts]
             Ppp can be instructed to attempt to redial attempts times.  If
             more than one phone number is specified (see ``set phone''
             above), a pause of nseconds is taken before dialing each number.
             A pause of seconds is taken before starting at the first number
             again.  A value of random may be used here in place of seconds
             and nseconds, causing a random delay of between 0 and 30 seconds.

             Note, this delay will be effective, even after attempts has been
             exceeded, so an immediate manual dial may appear to have done
             nothing.  If an immediate dial is required, a ``!'' should
             immediately follow the ``open'' keyword.  See the ``open''
             description above for further details.

         set sendpipe [value]
             This sets the routing table SENDPIPE value.  The optimum value is
             just over twice the MTU value.  If value is unspecified or zero,
             the default kernel controlled value is used.

         set server|socket TcpPort|LocalName|none password [mask]
             This command tells ppp to listen on the given socket or
             `diagnostic port' for incoming command connections.

             The word none instructs ppp to close any existing socket.

             If you wish to specify a local domain socket, LocalName must be
             specified as an absolute file name, otherwise it is assumed to be
             the name or number of a TCP port.  You may specify the octal
             umask that should be used with local domain sockets as a four
             character octal number beginning with `0'.  Refer to umask(2) for
             umask details.  Refer to services(5) for details of how to
             translate TCP port names.

             You must also specify the password that must be entered by the
             client (using the ``passwd'' command above) when connecting to
             this socket.  If the password is specified as an empty string, no
             password is required for connecting clients.

             When specifying a local domain socket, the first ``%d'' sequence
             found in the socket name will be replaced with the current
             interface unit number.  This is useful when you wish to use the
             same profile for more than one connection.

             In a similar manner TCP sockets may be prefixed with the ``+''
             character, in which case the current interface unit number is
             added to the port number.

             When using ppp with a server socket, the pppctl(8) command is the
             preferred mechanism of communications.  Currently, telnet(1) can
             also be used, but link encryption may be implemented in the
             future, so telnet(1) should not be relied upon.

         set speed value
             This sets the speed of the serial device.

         set stopped [LCPseconds [CCPseconds]]
             If this option is set, ppp will time out after the given FSM
             (Finite State Machine) has been in the stopped state for the
             given number of ``seconds''.  This option may be useful if the
             peer sends a terminate request, but never actually closes the
             connection despite our sending a terminate acknowledgement.  This
             is also useful if you wish to ``set openmode passive'' and time
             out if the peer doesn't send a Configure Request within the given
             time.  Use ``set log +lcp +ccp'' to make ppp log the appropriate
             state transitions.

             The default value is zero, where ppp doesn't time out in the
             stopped state.

             This value should not be set to less than the openmode delay (see
             ``set openmode'' above).

         set timeout idleseconds
             This command allows the setting of the idle timer.  Refer to the
             section titled ``SETTING THE IDLE TIMER'' for further details.

         set vj slotcomp on|off
             This command tells ppp whether it should attempt to negotiate VJ
             slot compression.  By default, slot compression is turned on.

         set vj slots nslots
             This command sets the initial number of slots that ppp will try
             to negotiate with the peer when VJ compression is enabled (see
             the `enable' command above).  It defaults to a value of 16.
             Nslots must be between 4 and 16 inclusive.

     shell|! [command]
         If command is not specified a shell is invoked according to the SHELL
         environment variable.  Otherwise, the given command is executed.
         Word replacement is done in the same way as for the ``!bg'' commanad
         as described above.

         Use of the ! character requires a following space as with any of the
         other commands.  You should note that this command is executed in the
         foreground - ppp will not continue running until this process has
         exited.  Use the bg command if you wish processing to happen in the
         background.

     show var
         This command allows the user to examine the following:

         show bundle
             Show the current bundle settings.

         show ccp
             Show the current CCP compression statistics.

         show compress
             Show the current VJ compression statistics.

         show escape
             Show the current escape characters.

         show filter [name]
             List the current rules for the given filter.  If name is not
             specified, all filters are shown.

         show hdlc
             Show the current HDLC statistics.

         show help|?
             Give a summary of available show commands.

         show iface
             Show the current interface information (the same as ``iface
             show'').

         show ipcp
             Show the current IPCP statistics.

         show lcp
             Show the current LCP statistics.

         show [data]link
             Show high level link information.

         show links
             Show a list of available logical links.

         show log
             Show the current log values.

         show mem
             Show current memory statistics.

         show modem
             Show low level link information.

         show proto
             Show current protocol totals.

         show route
             Show the current routing tables.

         show stopped
             Show the current stopped timeouts.

         show timer
             Show the active alarm timers.

         show version
             Show the current version number of ppp.

     term
         Go into terminal mode.  Characters typed at the keyboard are sent to
         the modem.  Characters read from the modem are displayed on the
         screen.  When a ppp peer is detected on the other side of the modem,
         ppp automatically enables Packet Mode and goes back into command
         mode.

MORE DETAILS
     +o   Read the example configuration files.  They are a good source of
         information.

     +o   Use ``help'', ``alias''?, ``enable''?, ``set''?  and ``show''?  to
         get online information about what's available.

     +o   The following urls contain useful information:
         +o   http://www.FreeBSD.org/FAQ/userppp.html
         +o   http://www.FreeBSD.org/handbook/userppp.html

FILES
     Ppp refers to four files: ppp.conf, ppp.linkup, ppp.linkdown and
     ppp.secret.  These files are placed in the /etc/ppp directory.

     /etc/ppp/ppp.conf
         System default configuration file.

     /etc/ppp/ppp.secret
         An authorisation file for each system.

     /etc/ppp/ppp.linkup
         A file to check when ppp establishes a network level connection.

     /etc/ppp/ppp.linkdown
         A file to check when ppp closes a network level connection.

     /var/log/ppp.log
         Logging and debugging information file.  Note, this name is specified
         in /etc/syslogd.conf.  See syslog.conf(5) for further details.

     /var/spool/lock/LCK..*
         tty port locking file.  Refer to uucplock(3) for further details.

     /var/run/tunN.pid
         The process id (pid) of the ppp program connected to the tunN device,
         where `N' is the number of the device.

     /var/run/ttyXX.if
         The tun interface used by this port.  Again, this file is only
         created in -background, -auto and -ddial modes.

     /etc/services
         Get port number if port number is using service name.

     /var/run/ppp-authname-class-value
         In multi-link mode, local domain sockets are created using the peer
         authentication name (`authname'), the peer endpoint discriminator
         class (`class') and the peer endpoint discriminator value (`value').
         As the endpoint discriminator value may be a binary value, it is
         turned to HEX to determine the actual file name.

         This socket is used to pass links between different instances of ppp.

SEE ALSO
     at(1), ftp(1), gzip(1), hostname(1), login(1), tcpdump(1), telnet(1),
     syslog(3), uucplock(3), crontab(5), group(5), passwd(5), resolv.conf(5),
     syslog.conf(5), adduser(8), chat(8), getty(8), inetd(8), init(8),
     named(8), ping(8), pppctl(8), pppd(8), route(8), syslogd(8),
     traceroute(8), vipw(8)

HISTORY
     This program was originally written by Toshiharu OHNO (tony-o@iij.ad.jp),
     and was submitted to FreeBSD-2.0.5 by Atsushi Murai (amurai@spec.co.jp).

     It was substantially modified during 1997 by Brian Somers
     (brian@Awfulhak.org), and was ported to OpenBSD in November that year
     (just after the 2.2 release).

     Most of the code was rewritten by Brian Somers in early 1998 when multi-
     link ppp support was added.

FreeBSD                        20 September 1995                       FreeBSD

NAME | SYNOPSIS | DESCRIPTION | Major Features | PERMISSIONS | GETTING STARTED | MANUAL DIALING | AUTOMATIC DIALING | BACKGROUND DIALING | DIAL ON DEMAND | RECEIVING INCOMING PPP CONNECTIONS (Method 1) | RECEIVING INCOMING PPP CONNECTIONS (Method 2) | AUTHENTICATING INCOMING CONNECTIONS | PPP OVER TCP (a.k.a Tunnelling) | PACKET ALIASING | PACKET FILTERING | SETTING THE IDLE TIMER | PREDICTOR-1 and DEFLATE COMPRESSION | CONTROLLING IP ADDRESS | CONNECTING WITH YOUR INTERNET SERVICE PROVIDER | LOGGING FACILITY | SIGNAL HANDLING | MULTI-LINK PPP | PPP COMMAND LIST | MORE DETAILS | FILES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ppp&manpath=FreeBSD+3.1-RELEASE>

home | help