icon Top 9 categories map      RocketAware > man pages >


Tips: Browse or Search all pages for efficient awareness of more than 6000 of the most popular reusable and open source applications, functions, libraries, and FAQs.

The "RKT couplings" below include links to source code, updates, additional information, advice, FAQs, and overviews.


Search all pages


By activity
Professions, Sciences, Humanities, Business, ...

User Interface
Text-based, GUI, Audio, Video, Keyboards, Mouse, Images,...

Text Strings
Conversions, tests, processing, manipulation,...

Integer, Floating point, Matrix, Statistics, Boolean, ...

Algorithms, Memory, Process control, Debugging, ...

Stored Data
Data storage, Integrity, Encryption, Compression, ...

Networks, protocols, Interprocess, Remote, Client Server, ...

Hard World
Timing, Calendar and Clock, Audio, Video, Printer, Controls...

File System
Management, Filtering, File & Directory access, Viewers, ...


RocketLink!--> Man page versions: OpenBSD

PPP(8)                  OpenBSD System Manager's Manual                 PPP(8)

     ppp - Point to Point Protocol (a.k.a. iijppp)

     ppp [ -auto | -background | -ddial | -direct | -dedicated ] [-alias]

     This is a user process PPP software package.  Normally, PPP is implement-
     ed 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 im-
     plementation 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 func-
     tions 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 de-
     termined 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 connec-
     tion.  In almost the same manner -ddial mode (direct-dial mode) also au-
     tomatically 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 packet aliasing.  Packet aliasing (a.k.a. IP masquerading) al-
     lows 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 success-
     fully 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 estab-

     Supports server-side PPP connections.  In direct mode, 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) proceedure, and use the PPP protocol for
     authentication instead.

     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:
     ifilter for incoming packets, ofilter for outgoing packets, dfilter to
     define a dialing trigger packet and afilter 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.
     Supports IETF draft Predictor-1 compression.  ppp supports not only VJ-
     compression but also Predictor-1 compression.  Normally, a modem has
     built-in compression (e.g. v42.bis) and the system may receive higher da-
     ta rates from it as a result of such compression.  While this is general-
     ly 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 compression pre-compresses all data
     flowing through the link, thus reducing overhead 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)

     Ppp is installed as user root and group network, with permissions 4550.
     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 in-
     voked ppp. Refer to the `ID0' logging facility if you're interested in
     what exactly is done as user id zero.

     When you first run ppp you may need to deal with some initial configura-
     tion details.  First, your kernel should include a tunnel device (the
     GENERIC kernel includes one by default).  If it doesn't, or if you re-
     quire 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.
     Second, 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. Last of all, 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:


     Make sure you use actual TABs here.  If you use spaces, the line will be
     silently ignored.  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

           *.* /var/log/ppp0.log

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

     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
           login: ppp
           Protocol: ppp

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

           ppp ON awfulhak>
           PPP ON awfulhak>

     You are now connected!  Note that `PPP' in the prompt has changed to cap-
     ital letters to indicate that you have a peer connection.  The show com-
     mand can be used to see how things are going:

           PPP ON awfulhak> show lcp
           * LCP related information is shown here *
           PPP ON awfulhak> show ipcp
           * IPCP 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.  It
     is possible to use the keyword `INTERFACE' in place of `HISADDR'. This
     will create a direct route on the tun interface.  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 avail-
     able commands.

     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:
     -   A line starting with a (``#'') character is treated as a comment
         line.  Leading whitespace are ignored when identifying comment lines.
     -   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.
     -   A label name starts in the first column and is followed by a colon
     -   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 la-
         bel 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
               dial OK!
               login OK!
               PPP ON awfulhak>

         If the /etc/ppp/ppp.linkup file is available, its contents are exe-
         cuted when the PPP connection is established.  See the provided
         ``pmdemand'' example in /etc/ppp/ppp.conf.sample which adds a default
         route.  The strings HISADDR, MYADDR and INTERFACE are available as
         the relevent IP addresses and interface name.  Similarly, when a con-
         nection is closed, the contents of the /etc/ppp/ppp.linkdown file are
         executed.  Both of these files have the same format as

     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.  You must also specify the destination label in
     /etc/ppp/ppp.conf to use.  This label must contain the ``set ifaddr''
     command to define the remote peers IP address. (refer to
     /etc/ppp/ppp.conf.sample) 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.

     Demand dialing is enabled with the -auto or -ddial options.  You must al-
     so 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 diagnostic port as
     follows (this can be done in -background and -direct mode too):

           # pppctl -v 3000 show ipcp
           IPCP [Opened]
             his side: xxxx

     Currently, telnet(1) may also be used to talk interactively.

     In order to achieve this, you must use the ``set server'' command as de-
     scribed below.  It is possible to retrospectively make a running ppp pro-
     gram listen on a diagnostic port by configuring /etc/ppp/ppp.secret, and
     sending it a USR1 signal.  In -auto mode, when an outgoing packet is de-
     tected, ppp will perform the dialing action (chat script) and try to con-
     nect 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 be-
     haviour 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 argu-
     ment 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 de-
     mand dial mode on both ends of the link. If each end has the same time-
     out, 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 ex-

           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 consti-
     tutes 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 con-
     nection 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) con-
     nection but not the ppp program itself.  You must use ``quit all'' to
     terminate ppp as well.

     To handle an incoming PPP connection request, follow these steps:

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

     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.   Prepare an account for the incoming user.

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

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

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

          (You can specify a label name for further control.)

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

     5.   Optional support for Microsoft's IPCP Name Server and NetBIOS Name
          Server negotiation can be enabled use ``enable msext'' and ``set ns
          pri-addr [sec-addr]'' along with ``set nbns pri-addr [sec-addr]'' in
          your /etc/ppp/ppp.conf file.

     This method differs in that it recommends the use of mgetty+sendfax to
     handle the modem connections.  The latest versions (0.99 and higher) can
     be compiled with the ``AUTO_PPP'' option to allow detection of clients
     speaking PPP to the login prompt.  Follow these steps:

     1.   Get, configure, and install mgetty+sendfax v0.99 or later making

          sure you have used the AUTO_PPP option.

     2.   Edit /etc/ttys to enable a mgetty on the port where the modem is at-
          tached.  For example:
                cuaa1 /usr/local/sbin/mgetty -s 57600 dialup on

     3.   Prepare an account for the incoming user.

          Pfred:xxxx:66:66:Fred's PPP:/home/ppp:/etc/ppp/ppp-dialup

     4.   Examine the files /etc/ppp/sample.ppp-dialup, /etc/ppp/sample.ppp-
          pap-dialup and /etc/ppp/ppp.conf.sample for ideas.  /etc/ppp/ppp-
          pap-dialup is supposed to be called from
          /usr/local/etc/mgetty+sendfax/login.conf from a line like
                /AutoPPP/ - - /etc/ppp/ppp-pap-dialup

     Normally, the receiver of a connection requires that the peer authenti-
     cates themself.  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 relevent section of

     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 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 ne-
     gotiating IP numbers.  See the ``set ifaddr'' command for details.

     If authentication is successful and label is specified, the current sys-
     tem label is changed to match the given label. This will change the sub-
     sequent parsing of the ppp.linkup and ppp.linkdown files.

PPP OVER TCP (a.k.a Tunneling)
     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 connec-
     tion 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:

            set timeout 0
            set ifaddr

     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

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

            set escape 0xff
            set device ui-gate:ppp-in
            set dial
            set timeout 30 15 5
            set log Phase Chat Connect Carrier hdlc LCP IPCP CCP tun
            set ifaddr

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

            set authname MyAuthName
            set authkey MyAuthKey

     We're assigning the address of to ui-gate, and the address to awfulhak.  To open the connection, just type
           awfulhak # ppp -background ui-gate
     The result will be an additional "route" on awfulhak to the
     network via the TCP connection, and an additional "route" on ui-gate to
     the network.  The networks are effectively bridged - the un-
     derlying TCP connection may be across a public network (such as the In-
     ternet), 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.

     The -alias command line option enables packet aliasing.  This allows the
     ppp host to act as a masquerading gateway for other computers over a lo-
     cal 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 Inter-
     net access, although they are invisible from the outside world.  In gen-
     eral, correct ppp operation should first be verified with packet aliasing
     disabled.  Then, the -alias option should be switched on, and network ap-
     plications (web browser, telnet(1),  ftp(1),  ping(8),  traceroute(8))
     should be checked on the ppp host.  Finally, the same or similar applica-
     tions should be checked on other computers in the LAN.  If network appli-
     cations 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 desig-
     nated the ppp host as the gateway for the LAN.

     This implementation supports packet filtering. There are four kinds of
     filters; ifilter, ofilter, dfilter and afilter.  Here are the basics:
     -   A filter definition has the following syntax: set filter-name rule-no
         action [src_addr/src_width] [dst_addr/dst_width] [proto [src
         [lt|eq|gt] port ]] [dst [lt|eq|gt] port] [estab]

         1.   `filter-name' should be one of ifilter, ofilter, dfilter or


         2.   There are two actions: `permit' and `deny'. If a given packet
              matches the rule, the associated action is taken immediately.

         3.   `src_width' and `dst_width' work like a netmask to represent an
              address range.

         4.   `proto' must be one of icmp, udp or tcp.

         5.   `port number' can be specified by number and service name from

     -   Each filter can hold up to 20 rules, starting from rule 0.  The en-
         tire rule set is not effective until rule 0 is defined, ie. the de-
         fault is to allow everything through.
     -   If no rule is matched to a packet, that packet will be discarded
     -   Use ``set filter-name -1'' to flush all rules.

     See /etc/ppp/ppp.conf.filter.example.

     To check/set idle timer, use the ``show timeout'' and ``set timeout idle
     [LQR [FSM-resend]]'' commands:

           ppp ON awfulhak> set timeout 600

     The timeout period is measured in seconds, the  default values for which
     are timeout = 180 or 3 min, lqrtimer = 30sec and retrytimer = 3sec.  To
     disable the idle timer function, use the command

           ppp ON awfulhak> set timeout 0

     In -auto mode, an idle timeout causes the PPP session to be closed,
     though the ppp program itself remains running.  Another trigger packet
     will cause it to attempt to reestablish the link.

     This version supports CCP and Predictor type 1 or deflate compression
     based on the current IETF-draft specs. As a default behaviour, 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 dis-
     able this functionality.

     It is possible to use a different algorithm in each direction by using
     only one of ``disable deflate'' and ``deny deflate''.

     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.  Other-
     wise, ppp returns NAK to suggest that the peer use a different IP ad-
     dress. When both sides of the connection agree to accept the received re-
     quest (and send ACK), IPCP is set to the open state and a network level
     connection is established.  To control this IPCP behaviour, this imple-
     mentation has the ``set ifaddr'' command for defining the local and re-
     mote 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' and `dst_addr'
     default to, and `netmask' defaults to whatever mask is appropri-
     ate for `src_addr'. It is only possible to make `netmask' smaller than
     the default.  The usual value is  Some incorrect PPP im-
     plementations require that the peer negotiates a specific IP address in-
     stead 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

     The above specification means:
     -   I will first suggest that my IP address should be, but I will
         only accept an address of
     -   I strongly insist that the peer uses as his own address
         and won't permit the use of any IP address but  When
         the peer requests another IP address, I will always suggest that it
     -   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

     A number followed by a slash (/) represent the number of bits significant
     in the IP address.  The above example signifies that:
     -   I'd like to use as my address if it is possible, but
         I'll also accept any IP address between and
     -   I'd like to make him use as his own address, but I'll
         also permit him to use any IP address between and
     -   As you may have already noticed, is equivalent to say-
     -   As an exception, 0 is equivalent to, 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.
     - means that I'll accept/permit any IP address but I'll
         try to insist that be used first.

     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.  Num-
          bers separated by a colon are used sequentially, irrespective of
          what happened as a result of using the previous number.  For exam-

                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:

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

          -   Set the timeout to 4 seconds.

          -   Expect nothing.

          -   Send ATZ.

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

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

          -   Set the timeout to 60.

          -   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:

          -   Set the timeout to 15 seconds.

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

          -   Send "awfulhak"

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

          -   Send whatever our current authkey value is set to.

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

          -   Send "PPP".

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

     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 gen-
          eral, the serial speed should be about four times the modem speed.

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

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

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

          -   If your provider assigns your address dynamically, choose a
              suitably unobtrusive and unspecific IP number as your address.
     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
    , you could specify

          -   If you find that your ISP accepts the first IP number that you
              suggest, specify third and forth arguments of ``''. 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

     6.   In most cases, your ISP will also be your default router.  If this
          is the case, and if you're using -auto mode, add the lines

                delete ALL
                add default HISADDR

          to /etc/ppp/ppp.conf.

          This tells ppp to delete all non-direct routing entries for the tun
          interface that ppp is running on, then to add a default route to
  If you're not using -auto mode, this isn't necessary
          as ppp will dial immediately and may negotiate new IP numbers with
          the peer.

          If you're not using -auto mode, or if you're using dynamic IP num-
          bers, you must also put these two lines in the /etc/ppp/ppp.linkup

                delete ALL
                add default HISADDR

          HISADDR is a macro meaning the "other side"s IP number, and is
          available once an IP number has been agreed (using IPCP) or set
          (using ``set ifaddr''). Now, once a connection is established, ppp
          will delete all non-direct interface routes, and add a default route
          pointing at the peers IP number.  You should use the same label as
          the one used in /etc/ppp/ppp.conf.

          If commands are being typed interactively, the only requirement is
          to type

                add default HISADDR

          after a successful dial.

     7.   If your provider requests that you use PAP/CHAP authentication meth-
          ods, 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

     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.

     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
           Carrier    Log Chat lines with 'CARRIER'
           CCP        Generate a CCP packet trace
           Chat       Generate Chat script trace log
           Command    Log commands executed
           Connect    Generate complete Chat log
           Debug      Log (very verbose) debug information
           HDLC       Dump HDLC packet in hex
           ID0        Log all function calls specifically made as user Li00Li1
           IPCP       Generate an IPCP packet trace
           LCP        Generate an LCP packet trace
           Link       Log address assignments and link up/down events
           LQM        Generate LQR report
           Phase      Phase transition log output
           TCP/IP     Dump all TCP/IP packets
           TUN        Include the tun device on each log line
           Warning    Output to the terminal device. If there is Li00Li1 ter-
                      minal, output is sent to the log file using LOG_WARNING.
           Error      Output to both the terminal device and the Li00Li11Li2
           Alert      Output to the log file using LOG_ALERT

     The ``set log'' command allows you to set the logging output level.  Mul-
     tiple levels can be specified on a single command line.  The default is
     equivalent to ``set log Carrier Link 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. no direct screen logging).

     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 carrier link phase
           PPP ON awfulhak> show log
           Log:   Carrier Link Phase Warning Error Alert
           Local: Warning Error Alert
           PPP ON awfulhak> set log -link +tcp/ip -warning
           PPP ON awfulhak> set log local +command
           PPP ON awfulhak> show log
           Log:   Carrier 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.

     Ppp deals with the following signals:

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

        These signals tell ppp to exit.

        This signal, when not in interactive mode, tells ppp to close any ex-
        isting server socket and open an Internet socket using port 3000 plus
        the current tunnel device number.  This can only be achieved if a
        suitable local password is specified in /etc/ppp/ppp.secret.

        This signal, tells ppp to close any existing server socket.

     This section lists the available commands and their effect.  They are us-
     able 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 re-
        quested by us.  ``Disable'' means that the option will not be request-
        ed by us.

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

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

           Default: Disabled and Accepted.  CHAP stands for Challenge Hand-
           shake Authentication Protocol.  Only one of CHAP and PAP (below)
           may be negotiated.  With CHAP, the authenticator sends a "chal-
           lenge" message to its peer.  The peer uses a one-way hash function
           to encrypt the challenge and sends the result back.  The authenti-
           cator 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 en-
           crypting the challenge.  Refer to the description of the ``set
           encrypt'' command for further details.

           Default: Enabled and Accepted.  This option decides if deflate com-
           pression 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 compres-
           sion using type 24 as the CCP configuration type rather than type
           26 as specified in rfc1979. Type 24 is actually specified as ``PPP
           Magnalink Variable Resource Compression'' in rfc1975! Ppp is capa-
           ble of negotiating with pppd, but only if ``pppd-deflate'' is
           enabled and accepted.

           Default: Disabled and Accepted.  This option decides if Link Quali-
           ty Requests will be sent.  LQR is a protocol that allows ppp to de-
           termine that the link is down without relying on the modems carrier

           Default: Disabled and Accepted.  PAP stands for Password Authenti-
           cation Protocol.  Only one of PAP and CHAP (above) may be negotiat-
           ed.  With PAP, the ID and Password are sent repeatedly to the peer
           until authentication is acknowledged or the connection is terminat-
           ed.  This is a rather poor security mechanism.  It is only per-
           formed 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.

           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.

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

           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.

           Default: Enabled and Accepted.  This option decides 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.

           Default: Disabled.  This option allows the use of Microsoft's PPP
           extensions, supporting the negotiation of the DNS and the NetBIOS
           NS.  Enabling this allows us to pass back the values given in "set
           ns" and "set nbns".

           Default: Disabled.  Enabling this option will tell the PAP authen-
           tication code to use the password file (see passwd(5))  to authen-
           ticate the caller rather than the /etc/ppp/ppp.secret file.

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

           Default: Disabled.  Enabling this option will tell ppp to gather
           thoroughput 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 relevent PPP layer shuts down, and is
           also available using the ``show'' command.  Troughput statistics
           are available at the ``IPCP'' and ``modem'' levels.

           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 usual-
           ly only necessary if you require the user to both login and authen-
           ticate themselves.

     add[!] dest mask gateway
        Dest is the destination IP address and mask is its mask.  0 0 refers
        to the default route, and it is possible to use the symbolic name
        `default' in place of both the dest and mask arguments.  Gateway is
        the next hop gateway to get to the given dest machine/network.  It is
        possible to use the symbolic names `MYADDR' and `HISADDR' as the des-
        tination, and either `HISADDR' or `INTERFACE' as the gateway. `MYADDR'
        is replaced with the interface address, `HISADDR' is replaced with the
        interfaces destination address and `INTERFACE' is replaced with the
        current interface name.  If the interfaces destination address has not
        yet been assigned (via ``set ifaddr''), the current `INTERFACE' is
        used instead of `HISADDR'.

        Refer to the ``set ifaddr'' command below for details of some restric-
        tions regarding the use of this command in the ppp.conf file.

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

     allow .....
        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|users logname...
           By default, only user id 0 is allowed access.  If this command is
           specified, all of the listed users are allowed access to the sec-
           tion in which the ``allow users'' command is found.  The `default'
           section is always checked first (although it is only ever automati-
           cally 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

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

        allow mode|modes modelist...
           By default, access using all ppp modes is possible.  If this com-
           mand is used, it restricts the access modes allowed to load the la-
           bel 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 `*'.

     alias .....
        This command allows the control of the aliasing (or masquerading) fa-
        cilities that are built into ppp. Until this code is required, it is
        not loaded by ppp, and it is quite possible that the alias library is
        not installed on your system (some administrators consider it a secu-
        rity risk).  If aliasing is enabled on your system, the following com-
        mands 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''. If proto is specified, 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 gate-

        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 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 sock-
           et so that it can guarantee a correct incoming ftp data or IRC con-

        alias unregistered_only [yes|no]
           Only alter outgoing packets with an unregistered source ad- dress.
           According to RFC 1918, unregistered source addresses are
 , and

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

     [!]bg command
        The given command is executed in the background.  Any of the pseudo
        arguments HISADDR, INTERFACE and MYADDR will be replaced with the ap-
        propriate values.  If you wish to pause ppp while the command exe-
        cutes, use the shell command instead.

        Close the current connection (but don't quit).

     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 for
        the current interface that ppp is using are deleted.  This means all
        entries for tunN, except the entry representing the actual link.  If
        dest is specified as `default', the default route is deleted.

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

     dial|call [remote]
        If ``remote'' is specified, a connection is established using the
        ``dial'' and ``login'' scripts for the given ``remote'' system.  Oth-
        erwise, the current settings are used to establish the connection.

        Displays the current status of the negotiable protocol values as spec-
        ified under ``accept|deny|enable|disable option....'' above.

        Bring the link down ungracefully, as if the physical layer had become
        unavailable.  It's not considered polite to use this command.

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

     load [remote]
        Load the given ``remote'' label.  If ``remote'' is not given, the
        ``default'' label is assumed.

     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 may be specified either on the
        ``set server'' command line or by putting an entry in
        /var/log/ppp.secret for the local host.  The value of pass is not
        logged when command logging is active, instead, the literal string
        ``********'' is logged.

     quit|bye [all]
        Exit ppp. If ppp is in interactive mode or if the ``all'' argument is
        given, ppp will exit, closing the connection.  A simple ``quit'' is-
        sued from a pppctl(8) or telnet(1) session will not close the current


        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 Asyncronous Control Character Map.  This is al-
           ways negotiated with the peer, and defaults to a value of
           0x00000000.  This protocol is required to defeat hardware that de-
           pends on passing certain characters from end to end (such as
           XON/XOFF etc).

        set filter-name rule-no action [src_addr/src_width]
           [dst_addr/dst_width] [proto [src [lt|eq|gt] port ]] [dst [lt|eq|gt]
           port] [estab]

           Ppp supports four filter sets.  The afilter specifies packets that
           keep the connection alive - reseting the idle timer.  The dfilter
           specifies packets that cause ppp to dial when in -auto mode.  The
           ifilter specifies packets that are allowed to travel into the ma-
           chine and the ofilter specifies packets that are allowed out of the
           machine.  By default all filter sets allow all packets to pass.
           Rules are processed in order according to ``n''. Up to 20 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 ifilters and ofil-
           ters, this means that the packet is dropped.  In the case of afil-
           ters it means that the packet will not reset the idle timer and in
           the case of dfilters it means that the packet will not trigger a
           dial.  Refer to the section on PACKET FILTERING above for further

        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 be-
           ing 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 ne-

        set ctsrts
           This sets hardware flow control and is the default.

        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 be of the
           format ``host:port''. If this is the case, ppp will attempt to con-
           nect to the given ``host'' on the given ``port''. Refer to the sec-
           tion 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:

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

                 When the chat script encounters this sequence, it delays two

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

                 This is replaced with a newline character.

                 This is replaced with a carriage return character.

                 This is replaced with a space character.

                 This is replaced with a tab character.

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

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

                 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 exclaimation mark (``!''). When the command is execut-
           ed, 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 4 is attached to

           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 pars-
           es 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 se-
           quence.  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 at-
           tached 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 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

        set encrypt MSChap|MD5
           This specifies the encryption algorithm to request and use when is-
           suing the CHAP challenge, and defaults to MD5.  If this is set to
           MSChap, ppp will behave like a Microsoft RAS when sending the CHAP
           challenge (assuming CHAP is enabled).  When responding to a chal-
           lenge, ppp determines how to encrypt the response based on the
           challenge, so this setting is ignored.

           NOTE:  Because the Microsoft encryption algorithm uses a combina-
                  tion of MD4 and DES, if you have not installed DES encryp-
                  tion software on your machine before building ppp, this op-
                  tion will not be available - only MD5 will be used.

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

        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
           Where a.b.c.d is the preferred IP, but n specifies how many bits of
           the address we will insist on.  If the /n bit is omitted, it de-
           faults to /32 unless the IP address is in which case the
           mask defaults to /0.

           Hisaddr may also be specified as a range of IP numbers in the for-
           for example:
                 set ifaddr,
           will only negotiate as the local IP number, but will as-
           sign any of the given 10 IP numbers to the peer.  If the peer re-
           quests 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.  If the peer requests an IP number that's either outside
           of this range or is already in use, ppp will start by suggesting a
           random unused IP number from the range.  If the peer doesn't subse-
           quently agree, ppp will suggest each of the other numbers in suc-
           cession until a number is chosen or until too many IPCP Configure
           Requests have been sent.

           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.

           It should be noted that in -auto mode, ppp will configure the in-
           terface immediately upon reading the ``set ifaddr'' line in the
           config file.  In any other mode, these values are just used for the
           IPCP negotiations, and the interface isn't configured until the
           IPCP layer is up.  As a result, it is impossible (or at least
           unwise) to use the ``add'' command in ppp.conf unless using -auto
           mode (the ppp.linkup file should be used instead).  Use ``allow
           mode auto'' to restrict the current profile to -auto mode only.

           Note also that the hisaddr argument may be overridden in the
           ppp.secret file once the client has authenticated themself.  Refer
           to the AUTHENTICATING INCOMING CONNECTIONS section for details.

        set loopback on|off
           When set to on (the default), ppp will automatically loop back
           packets being sent out with a destination address equal to that of
           the PPP interface.  If set to off, ppp will send the packet, proba-
           bly resulting in an ICMP redirect from the other end.

        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 speci-
           fied, the login script will be executed after the dial script.  Es-
           cape sequences available in the dial script are also available

        set mru value
           The default MRU is 1500.  If it is increased, the other side *may*
           increase its mtu.  There is no use decreasing the MRU to below the
           default as the PPP protocol *must* be able to accept packets of at
           least 1500 octets.

        set mtu value
           The default MTU is 1500.  This may be increased by the MRU speci-
           fied by the peer.  It may only be subsequently decreased by this
           option.  Increasing it is not valid as the peer is not necessarily
           able to receive the increased packet size.

        set ns x.x.x.x y.y.y.y
           This option allows the setting of the Microsoft DNS servers that

           will be negotiated.

        set nbns x.x.x.x y.y.y.y
           This option allows the setting of the Microsoft NetBIOS DNS servers
           that will be negotiated.

        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 ini-
           tiate 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.  Multi-
           ple 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 ac-
           cording 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 reconnect timeout ntries
           Should the line drop unexpectedly (due to loss of CD or LQR fail-
           ure), a connection will be re-established after the given timeout.
           The line will be re-connected at most ntries times.  Ntries de-
           faults to zero.  A value of random for timeout will result in a
           variable pause, somewhere between 0 and 30 seconds.

        set redial seconds[.nseconds] [attempts]
           Ppp can be instructed to attempt to redial attempts times.  If more
           than one 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 too.

        set stopped [LCPseconds [IPCPseconds [CCPseconds]]]
           If this option is set, ppp will time out after the given FSM (Fi-
           nite State Machine) has been in the stopped state for the given
           number of ``seconds''. This option may be useful if you see ppp
           failing to respond in the stopped state, or if you wish to ``set
           openmode passive'' and time out if the peer doesn't send a Config-
           ure Request within the given time.  Use ``set log +lcp +ipcp +ccp''
           to make ppp log all 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 server|socket TcpPort|LocalName|none [password] [mask]
           This command tells ppp to listen on the given socket or `diagnostic
           port' for incoming command connections.  This is not possible if
           ppp is in interactive mode.  The word none instructs ppp to close
           any existing socket.  If you wish to specify a unix 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 unix 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 may also specify the password that must be used by the client
           when connecting to this socket.  If the password is not specified
           here, /etc/ppp/ppp.secret is searched for a machine name that's the
           same as your local host name without any domain suffix.  Refer to
           hostname(1) for further details.  If a password is specified as the
           empty string, no password is required.

           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 timeout idle [LQR [FSM-resend]]
           This command allows the setting of the idle timer, the LQR timer
           (if enabled) and the finite state machine (FSM) retry timer.

        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.

        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 help|?
           This command gives a summary of available set commands.

     shell|! [command]
        If ``command'' is not specified a shell is invoked according to the
        SHELL environment variable.  Otherwise, the given command is executed.
        Any of the pseudo arguments HISADDR, INTERFACE and MYADDR will be re-
        placed with the appropriate values.  Use of the ! character requires a
        following space as with any 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 pro-
        cessing to happen in the background.

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

        show [adio]filter
           List the current rules for the given filter.

        show auth
           Show the current authname and encryption values.  If you have built
           ppp without DES support, the encryption value is not displayed as
           it will always be MD5.

        show ccp
           Show the current CCP statistics.

        show compress
           Show the current compress statistics.

        show escape

           Show the current escape characters.

        show hdlc
           Show the current HDLC statistics.

        show ipcp
           Show the current IPCP statistics.

        show lcp
           Show the current LCP statistics.

        show loopback
           Show the current loopback status.

        show log
           Show the current log values.

        show mem
           Show current memory statistics.

        show modem
           Show current modem statistics.

        show mru
           Show the current MRU.

        show mtu
           Show the current MTU.

        show proto
           Show current protocol totals.

        show reconnect
           Show the current reconnect values.

        show redial
           Show the current redial values.

        show stopped
           Show the current stopped timeouts.

        show route
           Show the current routing tables.

        show timeout
           Show the current timeout values.

        show msext
           Show the current Microsoft extension values.

        show version
           Show the current version number of ppp.

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

        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.

     -   Read the example configuration files.  They are a good source of in-

     -   Use ``help'', ``show ?'', ``alias ?'', ``set ?'' and ``set ? <var>''

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

           System default configuration file.

           An authorisation file for each system.

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

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

           Logging and debugging information file.  Note, this name is speci-
           fied in /etc/syslogd.conf. See syslog.conf(5) for further details.

           tty port locking file.  Refer to uucplock(3) for further details.

           The process id (pid) of the ppp program connected to the tunN de-
           vice, where `N' is the number of the device.  This file is only
           created in -background, -auto and -ddial modes.

           The tun interface used by this port.  Again, this file is only cre-
           ated in -background, -auto and -ddial modes.

           Get port number if port number is using service name.

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

     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 has since been substantially modified by Brian Somers (brian@Awful-
     hak.org), and was ported to OpenBSD in November '97 (just after the 2.2

OpenBSD                        20 September 1995                            26

Source: OpenBSD 2.6 man pages. Copyright: Portions are copyrighted by BERKELEY
SOFTWARE DESIGN, INC., The Regents of the University of California, Massachusetts
Institute of Technology, Free Software Foundation, FreeBSD Inc., and others.

(Corrections, notes, and links courtesy of RocketAware.com)

[Detailed Topics]
FreeBSD Sources for ppp(8)
OpenBSD sources for ppp(8)

[Overview Topics]

Up to: Communication Implementation - low level implementation, multicast, ppp, slip, wrappers,firewalls, et al

RocketLink!--> Man page versions: OpenBSD

Rapid-Links: Search | About | Comments | Submit Path: RocketAware > man pages > ppp.8/
RocketAware.com is a service of Mib Software
Copyright 1999, Forrest J. Cavalier III. All Rights Reserved.
We welcome submissions and comments