This is the README file for ppp-2.4, a package which implements the
Point-to-Point Protocol (PPP) to provide Internet connections over
serial lines.


Introduction.
*************

The Point-to-Point Protocol (PPP) provides a standard way to establish
a network connection over a serial link.  At present, this package
supports IP and IPV6 and the protocols layered above them, such as TCP
and UDP.  The Linux port of this package also has support for IPX.

This PPP implementation consists of two parts:

- Kernel code, which establishes a network interface and passes
packets between the serial port, the kernel networking code and the
PPP daemon (pppd).  This code is implemented using STREAMS modules on
Solaris, and as a line discipline under Linux.

- The PPP daemon (pppd), which negotiates with the peer to establish
the link and sets up the ppp network interface.  Pppd includes support
for authentication, so you can control which other systems may make a
PPP connection and what IP addresses they may use.

The platforms supported by this package are Linux and Solaris.  I have
code for NeXTStep, FreeBSD, SunOS 4.x, SVR4, Tru64 (Digital Unix), AIX
and Ultrix but no active maintainers for these platforms.  Code for
all of these except AIX is included in the ppp-2.3.11 release.

The kernel code for Linux is no longer distributed with this package,
since the relevant kernel code is in the official Linux kernel source
(and has been for many years) and is included in all reasonably modern
Linux distributions.  The Linux kernel code supports using PPP over
things other than serial ports, such as PPP over Ethernet and PPP over
ATM.


Installation.
*************

The file SETUP contains general information about setting up your
system for using PPP.  There is also a README file for each supported
system, which contains more specific details for installing PPP on
that system.  The supported systems, and the corresponding README
files, are:

	Linux				README.linux
	Solaris				README.sol2

In each case you start by running the ./configure script.  This works
out which operating system you are using and creates the appropriate
makefiles.  You then run `make' to compile the user-level code, and
(as root) `make install' to install the user-level programs pppd, chat
and pppstats.

N.B. Since 2.3.0, leaving the permitted IP addresses column of the
pap-secrets or chap-secrets file empty means that no addresses are
permitted.  You need to put a "*" in that column to allow the peer to
use any IP address.  (This only applies where the peer is
authenticating itself to you, of course.)


What's new in ppp-2.4.7.
************************

* Fixed a potential security issue in parsing option files (CVE-2014-3158).

* There is a new "stop-bits" option, which takes an argument of 1 or 2,
  indicating the number of stop bits to use for async serial ports.

* Various bug fixes.


What was new in ppp-2.4.6.
**************************

* Man page updates.

* Several bug fixes.

* Options files can now set and unset environment variables for
  scripts.

* The timeout for chat scripts can now be taken from an environment
  variable.

* There is a new option, master_detach, which allows pppd to detach
  from the controlling terminal when it is the multilink bundle master
  but its own link has terminated, even if the nodetach option has
  been given.


What was new in ppp-2.4.5.
**************************

* Under Linux, pppd can now operate in a mode where it doesn't request
  the peer's IP address, as some peers refuse to supply an IP address.
  Since Linux supports device routes as well as gateway routes, it's
  possible to have no remote IP address assigned to the ppp interface
  and still route traffic over it.

* Pppd now works better with 3G modems that do strange things such as
  sending IPCP Configure-Naks with the same values over and over again.

* The PPP over L2TP plugin is included, which works with the pppol2tp
  PPP channel code in the Linux kernel.  This allows pppd to be used
  to set up tunnels using the Layer 2 Tunneling Protocol.

* A new 'enable-session' option has been added, which enables session
  accounting via PAM or wtwp/wtmpx, as appropriate.  See the pppd man
  page for details.

* Several bugs have been fixed.


What was new in ppp-2.4.4.
**************************

* Pppd will now run /etc/ppp/ip-pre-up, if it exists, after creating
  the ppp interface and configuring its IP addresses but before
  bringing it up.  This can be used, for example, for adding firewall
  rules for the interface.

* Lots of bugs fixed, particularly in the area of demand-dialled and
  persistent connections.

* The rp-pppoe plugin now accepts any interface name (that isn't an
  existing pppd option name) without putting "nic-" on the front of
  it, not just eth*, nas*, tap* and br*.


What was new in ppp-2.4.3.
**************************

* The configure script now accepts --prefix and --sysconfdir options.
  These default to /usr/local and /etc.  If you want pppd put in
  /usr/sbin as before, use ./configure --prefix=/usr.

* Doing `make install' no longer puts example configuration files in
  /etc/ppp.  Use `make install-etcppp' if you want that.

* The code has been updated to work with version 0.8.3 of libpcap.
  Unfortunately the libpcap maintainers removed support for the
  "inbound" and "outbound" keywords on PPP links, meaning that if you
  link pppd with libpcap-0.8.3, you can't use those keywords in the
  active-filter and pass-filter expressions.  The support has been
  reinstated in the CVS version and should be in future libpcap
  releases.  If you need the in/outbound keywords, use a later release
  than 0.8.3, or get the CVS version from http://www.tcpdump.org.

* There is a new option, child-timeout, which sets the length of time
  that pppd will wait for child processes (such as the command
  specified with the pty option) to exit before exiting itself.  It
  defaults to 5 seconds.  After the timeout, pppd will send a SIGTERM
  to any remaining child processes and exit.  A value of 0 means no
  timeout.

* Various bugs have been fixed, including some CBCP packet parsing
  bugs that could lead to the peer being able to crash pppd if CBCP
  support is enabled.

* Various fixes and enhancements to the radius and rp-pppoe plugins
  have been added.

* There is a new winbind plugin, from Andrew Bartlet of the Samba
  team, which provides the ability to authenticate the peer against an
  NT domain controller using MS-CHAP or MS-CHAPV2.

* There is a new pppoatm plugin, by various authors, sent in by David
  Woodhouse.

* The multilink code has been substantially reworked.  The first pppd
  for a bundle still controls the ppp interface, but it doesn't exit
  until all the links in the bundle have terminated.  If the first
  pppd is signalled to exit, it signals all the other pppds
  controlling links in the bundle.

* The TDB code has been updated to the latest version.  This should
  eliminate the problem that some people have seen where the database
  file (/var/run/pppd.tdb) keeps on growing.  Unfortunately, however,
  the new code uses an incompatible database format.  For this reason,
  pppd now uses /var/run/pppd2.tdb as the database filename.


What was new in ppp-2.4.2.
**************************

* The CHAP code has been rewritten.  Pppd now has support for MS-CHAP
  V1 and V2 authentication, both as server and client.  The new CHAP
  code is cleaner than the old code and avoids some copyright problems
  that existed in the old code.

* MPPE (Microsoft Point-to-Point Encryption) support has been added,
  although the current implementation shouldn't be considered
  completely secure.  (There is no assurance that the current code
  won't ever transmit an unencrypted packet.)

* James Carlson's implementation of the Extensible Authentication
  Protocol (EAP) has been added.

* Support for the Encryption Control Protocol (ECP) has been added.

* Some new plug-ins have been included:
  - A plug-in for kernel-mode PPPoE (PPP over Ethernet)
  - A plug-in for supplying the PAP password over a pipe from another
    process
  - A plug-in for authenticating using a Radius server.

* Updates and bug-fixes for the Solaris port.

* The CBCP (Call Back Control Protocol) code has been updated.  There
  are new options `remotenumber' and `allow-number'.

* Extra hooks for plugins to use have been added.

* There is now a `maxoctets' option, which causes pppd to terminate
  the link once the number of bytes passed on the link exceeds a given
  value.

* There are now options to control whether pppd can use the IPCP
  IP-Address and IP-Addresses options: `ipcp-no-address' and
  `ipcp-no-addresses'.

* Fixed several bugs, including potential buffer overflows in chat.


What was new in ppp-2.4.1.
**************************

* Pppd can now print out the set of options that are in effect.  The
  new `dump' option causes pppd to print out the option values after
  option parsing is complete.  The `dryrun' option causes pppd to
  print the options and then exit.

* The option parsing code has been fixed so that options in the
  per-tty options file are parsed correctly, and don't override values
  from the command line in most cases.

* The plugin option now looks in /usr/lib/pppd/<pppd-version> (for
  example, /usr/lib/pppd/2.4.1b1) for shared objects for plugins if
  there is no slash in the plugin name.

* When loading a plugin, pppd will now check the version of pppd for
  which the plugin was compiled, and refuse to load it if it is
  different to pppd's version string.  To enable this, the plugin
  source needs to #include "pppd.h" and have a line saying:
	char pppd_version[] = VERSION;

* There is a bug in zlib, discovered by James Carlson, which can cause
  kernel memory corruption if Deflate is used with the lowest setting,
  8.  As a workaround pppd will now insist on using at least 9.

* Pppd should compile on Solaris and SunOS again.

* Pppd should now set the MTU correctly on demand-dialled interfaces.


What was new in ppp-2.4.0.
**************************

* Multilink: this package now allows you to combine multiple serial
  links into one logical link or `bundle', for increased bandwidth and
  reduced latency.  This is currently only supported under the
  2.4.x and later Linux kernels.

* All the pppd processes running on a system now write information
  into a common database.  I used the `tdb' code from samba for this.

* New hooks have been added.

For a list of the changes made during the 2.3 series releases of this
package, see the Changes-2.3 file.


Compression methods.
********************

This package supports two packet compression methods: Deflate and
BSD-Compress.  Other compression methods which are in common use
include Predictor, LZS, and MPPC.  These methods are not supported for
two reasons - they are patent-encumbered, and they cause some packets
to expand slightly, which pppd doesn't currently allow for.
BSD-Compress and Deflate (which uses the same algorithm as gzip) don't
ever expand packets.


Contacts.
*********

The comp.protocols.ppp newsgroup is a useful place to get help if you
have trouble getting your ppp connections to work.  Please do not send
me questions of the form "please help me get connected to my ISP" -
I'm sorry, but I simply do not have the time to answer all the
questions like this that I get.

If you find bugs in this package, please report them to the maintainer
for the port for the operating system you are using:

Linux			Paul Mackerras <paulus@samba.org>
Solaris			James Carlson <carlson@workingcode.com>


Copyrights:
***********

All of the code can be freely used and redistributed.  The individual
source files each have their own copyright and permission notice.
Pppd, pppstats and pppdump are under BSD-style notices.  Some of the
pppd plugins are GPL'd.  Chat is public domain.


Distribution:
*************

The primary site for releases of this software is:

	ftp://ftp.samba.org/pub/ppp/

	     Microsoft Call Back Configuration Protocol.
			by Pedro Roque Marques
			(updated by Paul Mackerras)

The CBCP is a method by which the Microsoft Windows NT Server may
implement additional security. It is possible to configure the server
in such a manner so as to require that the client systems which
connect with it are required that following a valid authentication to
leave a method by which the number may be returned call.

It is a requirement of servers to be so configured that the protocol be
exchanged.

So, this set of patches may be applied to the pppd process to enable
the cbcp client *only* portion of the specification. It is primarily
meant to permit connection with Windows NT Servers.

The ietf-working specification may be obtained from ftp.microsoft.com
in the developr/rfc directory.

The ietf task group has decided to recommend that the LCP sequence be
extended to permit the callback operation. For this reason, these
patches are not 'part' of pppd but are an adjunct to the code.

To enable CBCP support, all that is required is to uncomment the line
in Makefile.linux that sets CBCP=y and recompile pppd.

I use such script to make a callback:

pppd debug nodetach /dev/modem 115200 crtscts modem	\
callback 222222 name NAME remotename SERVER	\
connect 'chat -v "" atz OK atdt111111 CONNECT ""'
sleep 1
pppd debug /dev/modem 115200 crtscts modem	\
name NAME remotename SERVER defaultroute	\
connect 'chat -v RING ATA CONNECT "\c"'

First we invoke pppd with 'nodetach' option in order to not detach from
the controlling terminal and 'callback NUMBER' option, then wait for
1 second and invoke pppd again which waits for a callback (RING) and
then answers (ATA). Number 222222 is a callback number, i.e. server will
call us back at this number, while number 111111 is the number we are
calling to.

You have to put in /etc/ppp/chap-secrets the following two lines:

NAME SERVER PASSWORD
SERVER NAME PASSWORD

You have to use your real login name, remote server name and password.

EAP with MD5-Challenge and SRP-SHA1 support
by James Carlson, Sun Microsystems
Version 2, September 22nd, 2002


1.  What it does

    The Extensible Authentication Protocol (EAP; RFC 2284) is a
    security protocol that can be used with PPP.  It provides a means
    to plug in multiple optional authentication methods.

    This implementation includes the required default MD5-Challenge
    method, which is similar to CHAP (RFC 1994), as well as the new
    SRP-SHA1 method.  This latter method relies on an exchange that is
    not vulnerable to dictionary attacks (as is CHAP), does not
    require the server to keep a cleartext copy of the secret (as in
    CHAP), supports identity privacy, and produces a temporary shared
    key that could be used for data encryption.

    The SRP-SHA1 method is based on draft-ietf-pppext-eap-srp-03.txt,
    a work in progress.

2.  Required libraries

    Two other packages are required first.  Download and install
    OpenSSL and Thomas Wu's SRP implementation.

	http://www.openssl.org/ (or ftp://ftp.openssl.org/source/)
	http://srp.stanford.edu/

    Follow the directions in each package to install the SSL and SRP
    libraries.  Once SRP is installed, you may run tconf as root to
    create known fields, if desired.  (This step is not required.)

3.  Installing the patch

    The EAP-SRP patch described here is integrated into this version
    of pppd.  The following patch may be used with older pppd sources:

	ftp://playground.sun.com/carlsonj/eap/ppp-2.4.1-eap-1.tar.gz

    Configure, compile, and install as root.  You may want to edit
    pppd/Makefile after configuring to enable or disable optional
    features.

	% ./configure
	% make
	% su
	# make install

    If you use csh or tcsh, run "rehash" to pick up the new commands.

    If you're using Solaris, and you run into trouble with the
    pseudonym feature on the server side ("no DES here" shows in the
    log file), make sure that you have the "domestic" versions of the
    DES libraries linked.  You should see "crypt_d" in "ldd
    /usr/local/bin/pppd".  If you see "crypt_i" instead, then make
    sure that /usr/lib/libcrypt.* links to /usr/lib/libcrypt_d.*.  (If
    you have the international version of Solaris, then you won't have
    crypt_d.  You might want to find an alternative DES library.)

4.  Adding the secrets

    On the EAP SRP-SHA1 client side, access to the cleartext secret is
    required.  This can be done in two ways:

	- Enter the client name, server name, and password in the
          /etc/ppp/srp-secrets file.  This file has the same format as
          the existing chap-secrets and pap-secrets files.

	  clientname servername "secret here"

	- Use the "password" option in any of the standard
          configuration files (or the command line) to specify the
          secret.

	  password "secret here"

    On the EAP SRP-SHA1 server side, a secret verifier is required.
    This is a one-way hash of the client's name and password.  To
    generate this value, run the srp-entry program (see srp-entry(8)).
    This program prompts for the client name and the passphrase (the
    secret).  The output will be an entry, such as the following,
    suitable for use in the server's srp-secrets file.  Note that if
    this is transferred by cut-and-paste, the entry must be a single
    line of text in the file.

pppuser srpserver 0:LFDpwg4HBLi4/kWByzbZpW6pE95/iIWBSt7L.DAkHsvwQphtiq0f6reoUy/1LC1qYqjcrV97lCDmQHQd4KIACGgtkhttLdP3KMowvS0wLXLo25FPJeG2sMAUEWu/HlJPn2/gHyh9aT.ZxUs5MsoQ1E61sJkVBc.2qze1CdZiQGTK3qtWRP6DOpM1bfhKtPoVm.g.MiCcTMWzc54xJUIA0mgKtpthE3JrqCc81cXUt4DYi5yBzeeGTqrI0z2/Gj8Jp7pS4Fkq3GmnYjMxnKfQorFXNwl3m7JSaPa8Gj9/BqnorJOsnSMlIhBe6dy4CYytuTbNb4Wv/nFkmSThK782V:2cIyMp1yKslQgE *

    The "secret" field consists of three entries separated by colons.
    The first entry is the index of the modulus and generator from
    SRP's /etc/tpasswd.conf.  If the special value 0 is used, then the
    well-known modulus/generator value is used (this is recommended,
    because it is much faster).  The second value is the verifier
    value.  The third is the password "salt."  These latter two values
    are encoded in base64 notation.

    For EAP MD5-Challenge, both client and server use the existing
    /etc/ppp/chap-secrets file.

5.  Configuration options

    There are two main options relating to EAP available for the
    client.  These are:

	refuse-eap		- refuse to authenticate with EAP
	srp-use-pseudonym	- use the identity privacy if
				  offered by server

    The second option stores a pseudonym, if offered by the EAP
    SRP-SHA1 server, in the $HOME/.ppp_pseudonym file.  The pseudonym
    is typically an encrypted version of the client identity.  During
    EAP start-up, the pseudonym stored in this file is offered to the
    peer as the identity.  If this is accepted by the peer, then
    eavesdroppers will be unable to determine the identity of the
    client.  Each time the client is authenticated, the server will
    offer a new pseudoname to the client using an obscured (reversibly
    encrypted) message.  Thus, access across successive sessions
    cannot be tracked.

    There are two main options for EAP on the server:

	require-eap		- require client to use EAP
	srp-pn-secret "string"	- set server's pseudoname secret

    The second option sets the long-term secret used on the server to
    encrypt the user's identity to produce pseudonames.  The
    pseudoname is constructed by hashing this string with the current
    date (to the nearest day) with SHA1, then using this hash as the
    key for a DES encryption of the client's name.  The date is added
    to the hash for two reasons.  First, this allows the pseudonym to
    change daily.  Second, it allows the server to decode any previous
    pseudonym by trying previous dates.

    See the pppd(8) man page for additional options.

6.  Comments welcome!

    This is still an experimental implementation.  It has been tested
    and reviewed carefully for correctness, but may still be
    incomplete or have other flaws.  All comments are welcome.  Please
    address them to the author:

		james.d.carlson@sun.com

    or, for EAP itself or the SRP extensions to EAP, to the IETF PPP
    Extensions working group:

		ietf-ppp@merit.edu

		PPP for Linux
		-------------

		Paul Mackerras
		8 March 2001

		for ppp-2.4.2
		Updated for ppp-2.4.5, Sep 08

1. Introduction
---------------

The Linux PPP implementation includes both kernel and user-level
parts.  This package contains the user-level part, which consists of
the PPP daemon (pppd) and associated utilities.  In the past this
package has contained updated kernel drivers.  This is no longer
necessary, as the current kernel sources contain up-to-date drivers
(and have done since the 2.4.x kernel series).

The Linux PPP implementation is capable of being used both for
initiating PPP connections (as a `client') or for handling incoming
PPP connections (as a `server').  Note that this is an operational
distinction, based on how the connection is created, rather than a
distinction that is made in the PPP protocols themselves.

Mostly this package is used for PPP connections over modems connected
via asynchronous serial ports, so this guide concentrates on this
situation.

The PPP protocol consists of two parts.  One is a scheme for framing
and encoding packets, the other is a series of protocols called LCP,
IPCP, PAP and CHAP, for negotiating link options and for
authentication.  This package similarly consists of two parts: a
kernel module which handles PPP's low-level framing protocol, and a
user-level program called pppd which implements PPP's negotiation
protocols.

The kernel module assembles/disassembles PPP frames, handles error
detection, and forwards packets between the serial port and either the
kernel network code or the user-level program pppd.  IP packets go
directly to the kernel network code.  So once pppd has negotiated the
link, it in practice lies completely dormant until you want to take
the link down, when it negotiates a graceful disconnect.


2. Installation
---------------

2.1 Kernel driver

Assuming you are running a recent 2.4 or 2.6 (or later) series kernel,
the kernel source code will contain an up-to-date kernel PPP driver.
If the PPP driver was included in your kernel configuration when your
kernel was built, then you only need to install the user-level
programs.  Otherwise you will need to get the source tree for your
kernel version, configure it with PPP included, and recompile.  Most
Linux distribution vendors ship kernels with PPP included in the
configuration.

The PPP driver can be either compiled into the kernel or compiled as a
kernel module.  If it is compiled into the kernel, the PPP driver is
included in the kernel image which is loaded at boot time.  If it is
compiled as a module, the PPP driver is present in one or more files
under /lib/modules and is loaded into the kernel when needed.

The 2.2 series kernels contain an older version of the kernel PPP
driver, one which doesn't support multilink.  If you want multilink,
you need to run a 2.4 or 2.6 series kernel.  The kernel PPP driver
was completely rewritten for the 2.4 series kernels to support
multilink and to allow it to operate over diverse kinds of
communication medium (the 2.2 driver only operates over serial ports
and devices which look like serial ports, such as pseudo-ttys).

Under the 2.2 kernels, if PPP is compiled as a module, the PPP driver
modules should be present in the /lib/modules/`uname -r`/net directory
(where `uname -r` represents the kernel version number).  The PPP
driver module itself is called ppp.o, and there will usually be
compression modules there, ppp_deflate.o and bsd_comp.o, as well as
slhc.o, which handles TCP/IP header compression.  If the PPP driver is
compiled into the kernel, the compression code will still be compiled
as modules, for kernels before 2.2.17pre12.  For 2.2.17pre12 and later,
if the PPP driver is compiled in, the compression code will also.

Under the 2.4 kernels, there are two PPP modules, ppp_generic.o and
ppp_async.o, plus the compression modules (ppp_deflate.o, bsd_comp.o
and slhc.o).  If the PPP generic driver is compiled into the kernel,
the other four can then be present either as modules or compiled into
the kernel.  There is a sixth module, ppp_synctty.o, which is used for
synchronous tty devices such as high-speed WAN adaptors.


2.2 User-level programs

If you obtained this package in .rpm or .deb format, you simply follow
the usual procedure for installing the package.

If you are using the .tar.gz form of this package, then cd into the
ppp-2.4.5 directory you obtained by unpacking the archive and issue
the following commands:

$ ./configure
$ make
# make install

The `make install' has to be done as root.  This makes and installs
four programs and their man pages: pppd, chat, pppstats and pppdump.
If the /etc/ppp configuration directory doesn't exist, the `make
install' step will create it and install some default configuration
files.


2.3 System setup for 2.4 kernels

Under the 2.4 series kernels, pppd needs to be able to open /dev/ppp,
character device (108,0).  If you are using udev (as most distributions
do), the /dev/ppp node should be created by udevd.

Otherwise you may need to create a /dev/ppp device node with the
commands:

# mknod /dev/ppp c 108 0
# chmod 600 /dev/ppp


2.4 System setup under 2.2 series kernels

Under the 2.2 series kernels, you should add the following to your
/etc/modules.conf or /etc/conf.modules:

alias tty-ldisc-3	ppp
alias ppp-compress-21	bsd_comp
alias ppp-compress-24	ppp_deflate
alias ppp-compress-26	ppp_deflate


3. Getting help with problems
-----------------------------

If you have problems with your PPP setup, or you just want to ask some
questions, or better yet if you can help others with their PPP
questions, then you should join the linux-ppp mailing list.  Send an
email to majordomo@vger.kernel.org with a line in the body saying

subscribe linux-ppp

To leave the mailing list, send an email to majordomo@vger.kernel.org
with a line in the body saying

unsubscribe linux-ppp

To send a message to the list, email it to linux-ppp@vger.kernel.org.
You don't have to be subscribed to send messages to the list.

You can also email me (paulus@samba.org) but I am overloaded with
email and I can't respond to most messages I get in a timely fashion.

There are also several relevant news groups, such as comp.protocols.ppp,
comp.os.linux.networking, or comp.os.linux.setup.


4. Configuring your dial-out PPP connections
--------------------------------------------

Some Linux distribution makers include tools in their distributions
for setting up PPP connections.  For example, for Red Hat Linux and
derivatives, you should probably use linuxconf or netcfg to set up
your PPP connections.

The two main windowing environments for Linux, KDE and Gnome, both
come with GUI utilities for configuring and controlling PPP dial-out
connections.  They are convenient and relatively easy to configure.

A third alternative is to use a PPP front-end package such as wvdial
or ezppp.  These also will handle most of the details of talking to
the modem and setting up the PPP connection for you.

Assuming that you don't want to use any of these tools, you want to
set up the configuration manually yourself, then read on.  This
document gives a brief description and example.  More details can be
found by reading the pppd and chat man pages and the PPP-HOWTO.

We assume that you have a modem that uses the Hayes-compatible AT
command set connected to an async serial port (e.g. /dev/ttyS0) and
that you are dialling out to an ISP.  

The trickiest and most variable part of setting up a dial-out PPP
connection is the part which involves getting the modem to dial and
then invoking PPP service at the far end.  Generally, once both ends
are talking PPP the rest is relatively straightforward.

Now in fact pppd doesn't know anything about how to get modems to dial
or what you have to say to the system at the far end to get it to talk
PPP.  That's handled by an external program such as chat, specified
with the connect option to pppd.  Chat takes a series of strings to
expect from the modem interleaved with a series of strings to send to
the modem.  See the chat man page for more information.  Here is a
simple example for connecting to an ISP, assuming that the ISP's
system starts talking PPP as soon as it answers the phone:

pppd connect 'chat -v "" AT OK ATDT5551212 ~' \
	/dev/ttyS0 57600 crtscts debug defaultroute

Going through pppd's options in order:
    connect 'chat ...'  This gives a command to run to contact the
    PPP server.  Here the supplied 'chat' program is used to dial a
    remote computer.  The whole command is enclosed in single quotes
    because pppd expects a one-word argument for the 'connect' option.
    The options to 'chat' itself are:

         -v            verbose mode; log what we do to syslog
         ""            don't wait for any prompt, but instead...
	 AT	       send the string "AT"
	 OK	       expect the response "OK", then
         ATDT5551212   dial the modem, then
         ~             wait for a ~ character, indicating the start
		       of a PPP frame from the server

    /dev/ttyS0	       specifies which serial port the modem is connected to
    57600	       specifies the baud rate to use
    crtscts	       use hardware flow control using the RTS & CTS signals
    debug	       log the PPP negotiation with syslog
    defaultroute       add default network route via the PPP link

Pppd will write error messages and debugging logs to the syslogd
daemon using the facility name "daemon".  These messages may already
be logged to the console or to a file like /var/log/messages; consult
your /etc/syslog.conf file to see.  If you want to make all pppd
messages go to a file such as /var/log/ppp-debug, add the line

daemon.*					/var/log/ppp-debug
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           This is one or more tabs. Do not use spaces.

to syslog.conf; make sure to put one or more TAB characters (not
spaces!) between the two fields.  Then you need to create an empty
/var/log/ppp-debug file with a command such as

	touch /var/log/ppp-debug

and then restart syslogd, usually by sending it a SIGHUP signal with a
command like this:

	killall -HUP syslogd


4.1 Is the link up?

The main way to tell if your PPP link is up and operational is the
ifconfig ("interface configuration") command.  Type

	/sbin/ifconfig

at a shell prompt.  It should print a list of interfaces including one
like this example:

ppp0      Link encap Point-to-Point Protocol
          inet addr 192.76.32.3  P-t-P 129.67.1.165  Mask 255.255.255.0
          UP POINTOPOINT RUNNING  MTU 1500  Metric 1
          RX packets 33 errors 0 dropped 0 overrun 0
          TX packets 42 errors 0 dropped 0 overrun 0

Assuming that ifconfig shows the ppp network interface, you can test
the link using the ping command like this:

	/sbin/ping -c 3 129.67.1.165

where the address you give is the address shown as the P-t-P address
in the ifconfig output.  If the link is operating correctly, you
should see output like this:

  PING 129.67.1.165 (129.67.1.165): 56 data bytes
  64 bytes from 129.67.1.165: icmp_seq=0 ttl=255 time=268 ms
  64 bytes from 129.67.1.165: icmp_seq=1 ttl=255 time=247 ms
  64 bytes from 129.67.1.165: icmp_seq=2 ttl=255 time=266 ms
  --- 129.67.1.165 ping statistics ---
  3 packets transmitted, 3 packets received, 0% packet loss
  round-trip min/avg/max = 247/260/268 ms

PPP Support for MPPE (Microsoft Point to Point Encryption)
==========================================================

Frank Cusack		frank@google.com
Mar 19, 2002

Updated by Paul Mackerras, Sep 2008


DISCUSSION

MPPE is Microsoft's encryption scheme for PPP links.  It is pretty much
solely intended for use with PPP over Internet links -- if you have a true
point to point link you have little need for encryption.  It is generally
used with PPTP.

MPPE is negotiated within CCP (Compression Control Protocol) as option
18.  In order for MPPE to work, both peers must agree to do it.  This
complicates things enough that I chose to implement it as strictly a binary
option, off by default.  If you turn it on, all other compression options
are disabled and MPPE *must* be negotiated successfully in both directions
(CCP is unidirectional) or the link will be disconnected.  I think this is
reasonable since, if you want encryption, you want encryption.  That is,
I am not convinced that optional encryption is useful.

While PPP regards MPPE as a "compressor", it actually expands every frame
by 4 bytes, the MPPE overhead (encapsulation).

Because of the data expansion, you'll see that ppp interfaces get their
mtu reduced by 4 bytes whenever MPPE is negotiated.  This is because
when MPPE is active, it is *required* that *every* packet be encrypted.
PPPD sets the mtu = MIN(peer mru, configured mtu).  To ensure that
MPPE frames are not larger than the peer's mru, we reduce the mtu by 4
bytes so that the network layer never sends ppp a packet that's too large.

There is an option to compress the data before encrypting (MPPC), however
the algorithm is patented and requires execution of a license with Hifn.
MPPC as an RFC is a complete farce.  I have no further details on MPPC.

Some recommendations:

- Use stateless mode.  Stateful mode is disabled by default.  Unfortunately,
  stateless mode is very expensive as the peers must rekey for every packet.
- Use 128-bit encryption.
- Use MS-CHAPv2 only.

Reference documents:

    <http://www.ietf.org/rfc/rfc3078.txt> MPPE
    <http://www.ietf.org/rfc/rfc3079.txt> MPPE Key Derivation
    <http://www.ietf.org/rfc/rfc2118.txt> MPPC
    <http://www.ietf.org/rfc/rfc2637.txt> PPTP
    <http://www.ietf.org/rfc/rfc2548.txt> MS RADIUS Attributes

You might be interested in PoPToP, a Linux PPTP server.  You can find it at
<http://www.poptop.org/>

RADIUS support for MPPE is from Ralf Hofmann, <ralf.hofmann@elvido.net>.


BUILDING THE PPPD

The userland component of PPPD has no additional requirements above
those for MS-CHAP and MS-CHAPv2.

MPPE support is now included in the mainline Linux kernel releases.


CONFIGURATION

See pppd(8) for the MPPE options.  Under Linux, if your modutils is earlier
than 2.4.15, you will need to add

    alias ppp-compress-18 ppp_mppe

to /etc/modules.conf.

PPP Support for Microsoft's CHAP-80
===================================

Eric Rosenquist          rosenqui@strataware.com
(updated by Paul Mackerras)
(updated by Al Longyear)
(updated by Farrell Woods)
(updated by Frank Cusack)

INTRODUCTION

Microsoft has introduced an extension to the Challenge/Handshake
Authentication Protocol (CHAP) which avoids storing cleartext
passwords on a server.  (Unfortunately, this is not as secure as it
sounds, because the encrypted password stored on a server can be used
by a bogus client to gain access to the server just as easily as if
the password were stored in cleartext.)  The details of the Microsoft
extensions can be found in the document:

    <http://www.ietf.org/rfc/rfc2433.txt>

In short, MS-CHAP is identified as <auth chap 80> since the hex value
of 80 is used to designate Microsoft's scheme.  Standard PPP CHAP uses
a value of 5.  If you enable PPP debugging with the "debug" option and
see something like the following in your logs, the remote server is
requesting MS-CHAP:

  rcvd [LCP ConfReq id=0x2 <asyncmap 0x0> <auth MS> <magic 0x46a3>]
                                           ^^^^^^^

MS-CHAP is enabled by default under Linux in pppd/Makefile.linux by
the line "CHAPMS=y".


CONFIGURATION

If you've never used PPPD with CHAP before, read the man page (type
"man pppd") and read the description in there.  Basically, you need to
edit the "chap-secrets" file typically named /etc/ppp/chap-secrets.
This should contain the following two lines for each system with which
you use CHAP (with no leading blanks):

    RemoteHost  Account     Secret
    Account     RemoteHost  Secret

Note that you need both lines and that item 1 and 2 are swapped in the
second line.  I'm not sure why you need it twice, but it works and I didn't
have time to look into it further.  The "RemoteHost" is a somewhat
arbitrary name for the remote Windows NT system you're dialing.  It doesn't
have to match the NT system's name, but it *does* have to match what you
use with the "remotename" parameter.  The "Account" is the Windows NT
account name you have been told to use when dialing, and the "Secret" is
the password for that account.  For example, if your service provider calls
their machine "DialupNT" and tells you your account and password are
"customer47" and "foobar", add the following to your chap-secrets file:

    DialupNT    customer47  foobar
    customer47  DialupNT    foobar

The only other thing you need to do for MS-CHAP (compared to normal CHAP)
is to always use the "remotename" option, either on the command line or in
your "options" file (see the pppd man page for details).  In the case of
the above example, you would need to use the following command line:

    pppd name customer47 remotename DialupNT <other options>

or add:

    name customer47
    remotename DialupNT

to your PPPD "options" file.

The "remotename" option is required for MS-CHAP since Microsoft PPP servers
don't send their system name in the CHAP challenge packet.


E=691 (AUTHENTICATION_FAILURE) ERRORS WHEN YOU HAVE THE VALID SECRET (PASSWORD)

If your RAS server is not the domain controller and is not a 'stand-alone'
server then it must make a query to the domain controller for your domain.

You need to specify the domain name with the user name when you attempt to
use this type of a configuration. The domain name is specified with the
local name in the chap-secrets file and with the option for the 'name'
parameter.

For example, the previous example would become:

    DialupNT            domain\\customer47   foobar
    domain\\customer47  DialupNT             foobar

and

    pppd name 'domain\\customer47' remotename DialupNT <other options>

or add:

    name domain\\customer47
    remotename DialupNT

when the Windows NT domain name is simply called 'domain'.


TROUBLESHOOTING

Assuming that everything else has been configured correctly for PPP and
CHAP, the MS-CHAP-specific problems you're likely to encounter are mostly
related to your Windows NT account and its settings.  A Microsoft server
returns error codes in its CHAP response.  The following are extracted from
RFC 2433:

 646 ERROR_RESTRICTED_LOGON_HOURS
 647 ERROR_ACCT_DISABLED
 648 ERROR_PASSWD_EXPIRED
 649 ERROR_NO_DIALIN_PERMISSION
 691 ERROR_AUTHENTICATION_FAILURE
 709 ERROR_CHANGING_PASSWORD

You'll see these in your pppd log as a line similar to:

   Remote message: E=649 R=0

The "E=" is the error number from the table above, and the "R=" flag
indicates whether the error is transient and the client should retry.  If
you consistently get error 691, then either you're using the wrong account
name/password, or the DES library or MD4 hashing (in md4.c) aren't working
properly.  Verify your account name and password (use a Windows NT or
Windows 95 system to dial-in if you have one available).  If that checks
out, test the DES library with the "destest" program included with the DES
library.  If DES checks out, the md4.c routines are probably failing
(system byte ordering may be a problem) or my code is screwing up.  I've
only got access to a Linux system, so you're on your own for anything else.

Another thing that might cause problems is that some RAS servers won't
respond at all to LCP config requests without seeing the word "CLIENT"
from the other end.  If you see pppd sending out LCP config requests
without getting any reply, try putting something in your chat script
to send the word CLIENT after the modem has connected.

STILL TO DO

A site using only MS-CHAP to authenticate has no need to store cleartext
passwords in the "chap-secrets" file.  A utility that spits out the ASCII
hex MD4 hash of a given password would be nice, and would allow that hash
to be used in chap-secrets in place of the password.  The code to do this
could quite easily be lifted from chap_ms.c (you have to convert the
password to Unicode before hashing it).  The chap_ms.c file would also have
to be changed to recognize a password hash (16 binary bytes == 32 ASCII hex
characters) and skip the hashing stage.  This would have no real security
value as the hash is plaintext-equivalent.

PPP Support for Microsoft's CHAP-81
===================================

Frank Cusack		frank@google.com

Some text verbatim from README.MSCHAP80,
by Eric Rosenquist, rosenqui@strataware.com

INTRODUCTION

First, please read README.MSCHAP80; almost everything there applies here.
MS-CHAP was basically devised by Microsoft because rather than store
plaintext passwords, they (Microsoft) store the md4 hash of passwords.
It provides no advantage over standard CHAP, since the hash is used
as plaintext-equivalent.  (Well, the Change-Password packet is arguably
an advantage.)  It does introduce a significant weakness if the LM hash
is used.  Additionally, the format of the failure packet potentially
gives information to an attacker.  The weakness of the LM hash is partly
addressed in RFC 2433, which deprecates its use.

MS-CHAPv2 adds 2 benefits to MS-CHAP.  (1) The LM hash is no longer
used.  (2) Mutual authentication is required.  Note that the mutual
authentication in MS-CHAPv2 is different than the case where both PPP
peers require authentication from the other; the former proves that
the server has access to the client's password, the latter proves that
the server has access to a secret which the client also has -- which
may or may not be the same as the client's password (but should not be
the same, per RFC 1994).  Whether this provides any actual benefit is
outside the scope of this document.  The details of MS-CHAPv2 can be
found in the document:

    <http://www.ietf.org/rfc/rfc2759.txt>


BUILDING THE PPPD

In addition to the requirements for MS-CHAP, MS-CHAPv2 uses the SHA-1
hash algorithm.  A public domain implementation is provided with pppd.


TROUBLESHOOTING

Assuming that everything else has been configured correctly for PPP and
CHAP, the MS-CHAPv2-specific problems you're likely to encounter are mostly
related to your Windows NT account and its settings.  A Microsoft server
returns error codes in its CHAP response.  The following are extracted from
RFC 2759:

 646 ERROR_RESTRICTED_LOGON_HOURS
 647 ERROR_ACCT_DISABLED
 648 ERROR_PASSWD_EXPIRED
 649 ERROR_NO_DIALIN_PERMISSION
 691 ERROR_AUTHENTICATION_FAILURE
 709 ERROR_CHANGING_PASSWORD

You'll see these in your pppd log as a line similar to:

   Remote message: E=649 No dialin permission

Previously, pppd would log this as:

   Remote message: E=649 R=0

Now, the text message is logged (both for MS-CHAP and MS-CHAPv2).

		PPPoE Support
		-------------

		Michal Ostrowski
		8 August 2001

		for ppp-2.4.2
		Updated for ppp-2.4.5 by Paul Mackerras, Sep 08

1. Introduction
---------------

This document describes the support for PPP over Ethernet (PPPoE)
included with this package.  It is assumed that the reader is
familiar with Linux PPP (as it pertains to tty/modem-based
connections).  In particular, users of PPP in the Linux 2.2 series
kernels should ensure they are familiar with the changes to the PPP
implementation in the 2.4 series kernels before attempting to use
PPPoE features.

If you are not familiar with PPP, I recommend looking at other
packages which include end-user configuration tools, such as Roaring
Penguin (http://www.roaringpenguin.com/pppoe).

PPPoE is a protocol typically used by *DSL providers to manage IP
addresses and authenticate users.  Essentially, PPPoE provides for a
PPP connection to be established not over a physical serial-line or
modem, but over a logical connection between two unique MAC-addresses
on an ethernet network.  Once the PPPoE layer discovers the end-points
to be used in the link and negotiates it, frames may be sent to and
received from the PPPoE layer just as if the link was a serial line
(or that is how it's supposed to be).

With this in mind, the goal of the implementation of PPPoE support in
Linux is to allow users to simply specify that the device they intend
to use for the PPP connection is an ethernet device (e.g. "eth0") and
the rest of the system should function as usual.

2. Using PPPoE
--------------

This section is a quick guide for getting PPPoE working, to allow one
to connect to their ISP who is providing PPPoE based services.

1.  Enable "Prompt for development and/or incomplete code/drivers" and
    "PPP over Ethernet" in your kernel configuration.  Most distributions
    will include the kernel PPPoE module by default.

2.  Compile and install your kernel.

3.  Install the ppp package.

4.  Add the following line to /etc/ppp/options:

    plugin rp-pppoe.so

    The effect of this line is simply to make "eth0", "eth1",
    ....,"ethx" all valid device names for pppd (just like ttyS0,
    ttyS1).

5.  Add the necessary authentication options to your pppd
    configuration (i.e. PAP/CHAP information).  If you wish to
    maintain seperate configurations for different devices you may
    place configuration options in device-specific configuration
    files: /etc/ppp/options.devname (devname=ttyS0, ttyS1, eth0, eth1
    or any other valid device name).

6.  Invoke pppd with the appropriate device name: e.g. "pppd eth0"


Do not include any compression or flow control options in your PPPoE
configuration.  They will be ignored.

Again, here it is assumed that the reader is familiar with the general
process of configuring PPP.  The steps outlined here refer only to the
steps and configuration options which are PPPoE specific, and it is
assumed that the reader will also configure other aspects of the system
(e.g. PAP authentication parameters).

3.  Advanced Functionality
--------------------------

For more advanced functionality (such as providing PPPoE services) and
user configuration tools, look to the Roaring Penguin PPPoE software
package (http://www.roaringpenguin.com/pppoe).

4.  Credits
-----------

The PPPoE plugin included in this package is a component of the
Roaring Penguin PPPoE package, included in this package courtesy of
Roaring Penguin Software. (http://www.roaringpenguin.com).

PPPoL2TP plugin
===============

The pppol2tp plugin lets pppd use the Linux kernel driver pppol2tp.ko
to pass PPP frames in L2TP tunnels. The driver was integrated into the
kernel in the 2.6.23 release. For kernels before 2.6.23, an
out-of-tree kernel module is available from the pppol2tp-kmod package
in the OpenL2TP project.

Note that pppd receives only PPP control frames over the PPPoL2TP
socket; data frames are handled entirely by the kernel.

The pppol2tp plugin adds extra arguments to pppd and uses the Linux kernel
PPP-over-L2TP driver to set up each session's data path.

Arguments are:-

pppol2tp <fd>                   - FD for PPPoL2TP socket
pppol2tp_lns_mode               - PPPoL2TP LNS behavior. Default off.
pppol2tp_send_seq               - PPPoL2TP enable sequence numbers in
                                  transmitted data packets. Default off.
pppol2tp_recv_seq               - PPPoL2TP enforce sequence numbers in
                                  received data packets. Default off.
pppol2tp_reorderto <millisecs>  - PPPoL2TP data packet reorder timeout.
                                  Default 0 (no reordering).
pppol2tp_debug_mask <mask>      - PPPoL2TP debug mask. Bitwise OR of
				  1 - verbose debug
				  2 - control
				  4 - kernel transport
				  8 - ppp packet data
				  Default: 0 (no debug).
pppol2tp_ifname <ifname>	- Name of PPP network interface visible
				  to "ifconfig" and "ip link".
				  Default: "pppN"
pppol2tp_tunnel_id <id>		- L2TP tunnel_id tunneling this PPP
				  session.
pppol2tp_session_id <id>	- L2TP session_id of this PPP session.
				  The tunnel_id/session_id pair is used
				  when sending event messages to openl2tpd.

pppd will typically be started by an L2TP daemon for each L2TP sesion,
supplying one or more of the above arguments as required. The pppd
user will usually have no visibility of these arguments.

Two hooks are exported by this plugin.

void (*pppol2tp_send_accm_hook)(int tunnel_id, int session_id,
     uint32_t send_accm, uint32_t recv_accm);
void (*pppol2tp_ip_updown_hook)(int tunnel_id, int session_id, int up);

Credits
=======

This plugin was developed by Katalix Systems as part of the OpenL2TP
project, http://openl2tp.sourceforge.net. OpenL2TP is a full-featured
L2TP client-server, suitable for use as an enterprise L2TP VPN server
or a VPN client.

Please copy problems to the OpenL2TP mailing list:
openl2tp-users@lists.sourceforge.net.

Maintained by:
	James Chapman
	jchapman@katalix.com
	Katalix Systems Ltd
	http://www.katalix.com

	Support to pass the password via a pipe to the pppd
	---------------------------------------------------

	Arvin Schnell <arvin@suse.de>
	2002-02-08


1. Introduction
---------------

Normally programs like wvdial or kppp read the online password from their
config file and store them in the pap- and chap-secrets before they start the
pppd and remove them afterwards. Sure they need special privileges to do so.

The passwordfd feature offers a simpler and more secure solution. The program
that starts the pppd opens a pipe and writes the password into it. The pppd
simply reads the password from that pipe.

This methods is used for quite a while on SuSE Linux by the programs wvdial,
kppp and smpppd.


2. Example
----------

Here is a short C program that uses the passwordfd feature. It starts the pppd
to buildup a pppoe connection.


--snip--

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>
#include <string.h>
#include <paths.h>

#ifndef _PATH_PPPD
#define _PATH_PPPD "/usr/sbin/pppd"
#endif


// Of course these values can be read from a configuration file or
// entered in a graphical dialog.
char *device = "eth0";
char *username = "1122334455661122334455660001@t-online.de";
char *password = "hello";

pid_t pid = 0;


void
sigproc (int src)
{
    fprintf (stderr, "Sending signal %d to pid %d\n", src, pid);
    kill (pid, src);
    exit (EXIT_SUCCESS);
}


void
sigchild (int src)
{
    fprintf (stderr, "Daemon died\n");
    exit (EXIT_SUCCESS);
}


int
start_pppd ()
{
    signal (SIGINT, &sigproc);
    signal (SIGTERM, &sigproc);
    signal (SIGCHLD, &sigchild);

    pid = fork ();
    if (pid < 0) {
	fprintf (stderr, "unable to fork() for pppd: %m\n");
	return 0;
    }

    if (pid == 0) {

	int i, pppd_argc = 0;
	char *pppd_argv[20];
	char buffer[32] = "";
	int pppd_passwdfd[2];

	for (i = 0; i < 20; i++)
	    pppd_argv[i] = NULL;

	pppd_argv[pppd_argc++] = "pppd";

	pppd_argv[pppd_argc++] = "call";
	pppd_argv[pppd_argc++] = "pwfd-test";

	// The device must be after the call, since the call loads the plugin.
	pppd_argv[pppd_argc++] = device;

	pppd_argv[pppd_argc++] = "user";
	pppd_argv[pppd_argc++] = username;

	// Open a pipe to pass the password to pppd.
	if (pipe (pppd_passwdfd) == -1) {
	    fprintf (stderr, "pipe failed: %m\n");
	    exit (EXIT_FAILURE);
	}

	// Of course this only works it the password is shorter
	// than the pipe buffer. Otherwise you have to fork to
	// prevent that your main program blocks.
	write (pppd_passwdfd[1], password, strlen (password));
	close (pppd_passwdfd[1]);

	// Tell the pppd to read the password from the fd.
	pppd_argv[pppd_argc++] = "passwordfd";
	snprintf (buffer, 32, "%d", pppd_passwdfd[0]);
	pppd_argv[pppd_argc++] = buffer;

	if (execv (_PATH_PPPD, (char **) pppd_argv) < 0) {
	    fprintf (stderr, "cannot execl %s: %m\n", _PATH_PPPD);
	    exit (EXIT_FAILURE);
	}
    }

    pause ();

    return 1;
}


int
main (int argc, char **argv)
{
    if (start_pppd ())
	exit (EXIT_SUCCESS);

    exit (EXIT_FAILURE);
}

---snip---


Copy this file to /etc/ppp/peers/pwfd-test. The plugins can't be loaded on the
command line (unless you are root) since the plugin option is privileged.


---snip---

#
# PPPoE plugin for kernel 2.4
#
plugin pppoe.so

#
# This plugin enables us to pipe the password to pppd, thus we don't have
# to fiddle with pap-secrets and chap-secrets. The user is also passed
# on the command line.
#
plugin passwordfd.so

noauth
usepeerdns
defaultroute
hide-password
nodetach
nopcomp
novjccomp
noccp

---snip---

This file describes the installation process for ppp-2.4 on systems
running Solaris.  The Solaris and SVR4 ports share a lot of code but
are not identical.  The STREAMS kernel modules and driver for Solaris
are in the solaris directory (and use some code from the modules
directory).

NOTE: Although the kernel driver and modules have been designed to
operate correctly on SMP systems, they have not been extensively
tested on SMP machines.  Some users of SMP Solaris x86 systems have
reported system problems apparently linked to the use of previous
versions of this software.  I believe these problems have been fixed.


Installation.
*************

1. Run the configure script and make the user-level programs and the
   kernel modules.

	./configure
	make

    The configure script will automatically find Sun's cc if it's in
    the standard location (/opt/SUNWspro/bin/cc).  If you do not have
    Sun's WorkShop compiler, configure will attempt to use 'gcc'.  If
    this is found and you have a 64 bit kernel, it will check that gcc
    accepts the "-m64" option, which is required to build kernel
    modules.

    You should not have to edit the Makefiles for most ordinary cases.

2. Install the programs and kernel modules: as root, do

	make install

    This installs pppd, chat and pppstats in /usr/local/bin and the
    kernel modules in /kernel/drv and /kernel/strmod, and creates the
    /etc/ppp directory and populates it with default configuration
    files.  You can change the installation directories by editing
    solaris/Makedefs.  If you have a 64 bit kernel, the 64-bit drivers
    are installed in /kernel/drv/sparcv9 and /kernel/strmod/sparcv9.

    If your system normally has only one network interface at boot
    time, the default Solaris system startup scripts will disable IP
    forwarding in the IP kernel module.  This will prevent the remote
    machine from using the local machine as a gateway to access other
    hosts.  The solution is to create an /etc/ppp/ip-up script
    containing something like this:

	#!/bin/sh
	/usr/sbin/ndd -set /dev/ip ip_forwarding 1

    See the man page for ip(7p) for details.

Integrated pppd
***************

  Solaris 8 07/01 (Update 5) and later have an integrated version of
  pppd, known as "Solaris PPP 4.0," and is based on ppp-2.4.0.  This
  version comes with the standard Solaris software distribution and is
  supported by Sun.  It is fully tested in 64-bit and SMP modes, and
  with bundled and unbundled synchronous drivers.  Solaris 8 10/01
  (Update 6) and later includes integrated PPPoE client and server
  support, with kernel-resident data handling.  See pppd(1M).

  The feature is part of the regular full installation, and is
  provided by these packages:

	SUNWpppd	- 32-bit mode kernel drivers
	SUNWpppdr	- root-resident /etc/ppp config samples
	SUNWpppdu	- /usr/bin/pppd itself, plus chat
	SUNWpppdx	- 64-bit mode kernel drivers
	SUNWpppdt	- PPPoE support
	SUNWpppg	- GPL'd optional 'pppdump' and plugins
	SUNWpppgS	- Source for GPL'd optional features

  Use the open source version of pppd if you wish to recompile to add
  new features or to experiment with the code.  Production systems,
  however, should run the Sun-supplied version, if at all possible.

  You can run both versions on a single system if you wish.  The
  Solaris PPP 4.0 interfaces are named "spppN," while this open source
  version names its interfaces as "pppN".  The STREAMS modules are
  similarly separated.  The Sun-supplied pppd lives in /usr/bin/pppd,
  while the open source version installs (by default) in
  /usr/local/bin/pppd.

Dynamic STREAMS Re-Plumbing Support.
************************************

  Solaris 8 (and later) includes dynamic re-plumbing support.  With
  this feature, modules below ip can be inserted, or removed, without
  having the ip stream be unplumbed, and re-plumbed again.  All state
  in ip for the interface will be preserved as modules are added or
  removed.  Users can install (or upgrade) modules such as firewall,
  bandwidth manager, cache manager, tunneling, etc., without shutting
  the interface down.

  To support this, ppp driver now uses /dev/udp instead of /dev/ip for
  the ip stream. The interface stream (where ip module pushed on top
  of ppp) is then I_PLINK'ed below the ip stream. /dev/udp is used
  because STREAMS will not let a driver be PLINK'ed under itself, and
  /dev/ip is typically the driver at the bottom of the tunneling
  interfaces stream.  The mux ids of the ip streams are then added
  using SIOCSxIFMUXID ioctl.

  Users will be able to see the modules on the interface stream by,
  for example:

    pikapon# ifconfig ppp modlist
    0 ip
    1 ppp

  Or arbitrarily if bandwidth manager and firewall modules are installed:

    pikapon# ifconfig hme0 modlist
    0 arp
    1 ip
    2 ipqos
    3 firewall
    4 hme

Snoop Support.
**************

  This version includes support for /usr/sbin/snoop.  Tests have been
  done on Solaris 7 through 9. Only IPv4 and IPv6 packets will be sent
  up to stream(s) marked as promiscuous (i.e., those used by snoop).

  Users will be able to see the packets on the ppp interface by, for
  example:

    snoop -d ppp0

  See the man page for snoop(1M) for details.

IPv6 Support.
*************

  This is for Solaris 8 and later.

  This version has been tested under Solaris 8 and 9 running IPv6.
  Interoperability testing has only been done between Solaris machines
  in terms of the IPV6 NCP.  An additional command line option for the
  pppd daemon has been added: ipv6cp-use-persistent.

  By default, compilation for IPv6 support is not enabled.  Uncomment
  the necessary lines in pppd/Makefile.sol2 to enable it.  Once done,
  the quickest way to get IPv6 running is to add the following
  somewhere in the command line option:

	+ipv6 ipv6cp-use-persistent

  The persistent id for the link-local address was added to conform to
  RFC 2472; such that if there's an EUI-48 available, use that to make
  up the EUI-64.  As of now, the Solaris implementation extracts the
  EUI-48 id from the Ethernet's MAC address (the ethernet interface
  needs to be up).  Future work might support other ways of obtaining
  a unique yet persistent id, such as EEPROM serial numbers, etc.

  There need not be any up/down scripts for ipv6,
  e.g. /etc/ppp/ipv6-up or /etc/ppp/ipv6-down, to trigger IPv6
  neighbor discovery for auto configuration and routing.  The in.ndpd
  daemon will perform all of the necessary jobs in the
  background. /etc/inet/ndpd.conf can be further customized to enable
  the machine as an IPv6 router. See the man page for in.ndpd(1M) and
  ndpd.conf(4) for details.

  Below is a sample output of "ifconfig -a" with persistent link-local
  address.  Note the UNNUMBERED flag is set because hme0 and ppp0 both
  have identical link-local IPv6 addresses:

lo0: flags=1000849<UP,LOOPBACK,RUNNING,MULTICAST,IPv4> mtu 8232 index 1
        inet 127.0.0.1 netmask ff000000 
hme0: flags=1000843<UP,BROADCAST,RUNNING,MULTICAST,IPv4> mtu 1500 index 2
        inet 129.146.86.248 netmask ffffff00 broadcast 129.146.86.255
        ether 8:0:20:8d:38:c1 
lo0: flags=2000849<UP,LOOPBACK,RUNNING,MULTICAST,IPv6> mtu 8252 index 1
        inet6 ::1/128 
hme0: flags=2000841<UP,RUNNING,MULTICAST,IPv6> mtu 1500 index 2
        ether 8:0:20:8d:38:c1 
        inet6 fe80::a00:20ff:fe8d:38c1/10 
hme0:1: flags=2080841<UP,RUNNING,MULTICAST,ADDRCONF,IPv6> mtu 1500 index 2
        inet6 fec0::56:a00:20ff:fe8d:38c1/64 
hme0:2: flags=2080841<UP,RUNNING,MULTICAST,ADDRCONF,IPv6> mtu 1500 index 2
        inet6 2000::56:a00:20ff:fe8d:38c1/64 
hme0:3: flags=2080841<UP,RUNNING,MULTICAST,ADDRCONF,IPv6> mtu 1500 index 2
        inet6 2::56:a00:20ff:fe8d:38c1/64 
ppp0: flags=10008d1<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST,IPv4> mtu 1500 index 12
        inet 172.16.1.1 --> 172.16.1.2 netmask ffffff00 
ppp0: flags=2202851<UP,POINTOPOINT,RUNNING,MULTICAST,UNNUMBERED,NONUD,IPv6> mtu 1500 index 12
        inet6 fe80::a00:20ff:fe8d:38c1/10 --> fe80::a00:20ff:fe7a:24fb

  Note also that a plumbed ipv6 interface stream will exist throughout
  the entire PPP session in the case where the peer rejects IPV6CP,
  which further causes the interface state to stay down. Unplumbing
  will happen when the daemon exits. This is done by design and is not
  a bug.

64-bit Support.
***************

  This version has been tested under Solaris 7 through 9 in both 32-
  and 64-bit environments (Ultra class machines).  Installing the
  package by executing "make install" will result in additional files
  residing in /kernel/drv/sparcv9 and /kernel/strmod/sparcv9
  subdirectories.

  64-bit modules and driver have been compiled and tested using Sun's
  cc and gcc.

Synchronous Serial Support.
***************************

  This version has working but limited support for the on-board
  synchronous HDLC interfaces.  It has been tested with the
  /dev/se_hdlc, /dev/zsh, HSI/S, and HSI/P drivers.  Synchronous mode
  was tested with a Cisco router.

  The ppp daemon does not directly support controlling the serial
  interface.  It relies on the /usr/sbin/syncinit command to
  initialize HDLC mode and clocking.

  There is a confirmed bug with NRZ/NRZI mode in the /dev/se_hdlc
  driver, and Solaris patch 104596-11 is needed to correct it.
  (However this patch seems to introduce other serial problems.  If
  you don't apply the patch, the workaround is to change the nrzi mode
  to yes or no, whichever works.)

  How to start pppd with synchronous support:

	#!/bin/sh

	local=1.1.1.1   # your ip address here
	baud=38400	# needed, but ignored by serial driver

	# Change to the correct serial driver/port
	#dev=/dev/zsh0
	dev=/dev/se_hdlc0
 
	# Change the driver, nrzi mode, speed and clocking to match
	# your setup.
	# This configuration is for external clocking from the DCE
	connect="syncinit se_hdlc0 nrzi=no speed=64000 txc=rxc rxc=rxc"
 
	/usr/sbin/pppd $dev sync $baud novj noauth $local: connect "$connect"

  Sample Cisco router config excerpt:

	!
	! Cisco router setup as DCE with RS-232 DCE cable
	! 
	!         
	interface Serial0
	 ip address 1.1.1.2 255.255.255.0
	 encapsulation ppp
	 clockrate 64000
	 no nrzi-encoding
	 no shutdown
	!         

Indexes created Thu Jun 20 12:38:36 MDT 2024