glfs/basicnet/connect/ppp.xml
Alexander E. Patrakov f48fe3c624 Fixed typos on the PPP page. Thanks to David Jensen.
git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@7487 af4574ff-66df-0310-9fd7-8a98e5e911e0
2008-06-09 14:43:45 +00:00

583 lines
23 KiB
XML

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % general-entities SYSTEM "../../general.ent">
%general-entities;
<!ENTITY ppp-download-http "http://samba.org/ftp/ppp/ppp-&ppp-version;.tar.gz">
<!ENTITY ppp-download-ftp "&gentoo-ftp-repo;/ppp-&ppp-version;.tar.gz">
<!ENTITY ppp-md5sum "183800762e266132218b204dfb428d29">
<!ENTITY ppp-size "673 KB">
<!ENTITY ppp-buildsize "5.6 MB">
<!ENTITY ppp-time "0.1 SBU">
]>
<sect1 id="ppp" xreflabel="PPP-&ppp-version;">
<?dbhtml filename="ppp.html"?>
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<title>PPP-&ppp-version;</title>
<indexterm zone="ppp">
<primary sortas="a-PPP">PPP</primary>
</indexterm>
<sect2 role="package">
<title>Introduction to PPP</title>
<para>The <application>PPP</application> package contains the
<command>pppd</command> daemon and the <command>chat</command>
program. This is used for connecting to other machines; often for connecting to
the Internet via a dial-up or PPPoE connection to an ISP.</para>
<bridgehead renderas="sect3">Package Information</bridgehead>
<itemizedlist spacing="compact">
<listitem>
<para>Download (HTTP): <ulink url="&ppp-download-http;"/></para>
</listitem>
<listitem>
<para>Download (FTP): <ulink url="&ppp-download-ftp;"/></para>
</listitem>
<listitem>
<para>Download MD5 sum: &ppp-md5sum;</para>
</listitem>
<listitem>
<para>Download size: &ppp-size;</para>
</listitem>
<listitem>
<para>Estimated disk space required: &ppp-buildsize;</para>
</listitem>
<listitem>
<para>Estimated build time: &ppp-time;</para>
</listitem>
</itemizedlist>
<bridgehead renderas="sect3">PPP Dependencies</bridgehead>
<bridgehead renderas="sect4">Optional</bridgehead>
<para role="optional"><xref linkend="libpcap"/> (needed to do PPP filtering),
<xref linkend="linux-pam"/> (to authenticate incoming calls using PAM),
and <ulink url="http://linux-atm.sourceforge.net/">Linux ATM</ulink> (to
build the pppoatm.so plugin)</para>
<para condition="html" role="usernotes">User Notes:
<ulink url="&blfs-wiki;/PPP"/></para>
</sect2>
<sect2 role="installation">
<title>Installation of PPP</title>
<note id="ppp-kernel">
<para><application>PPP</application> support (CONFIG_PPP),
the asynchronous line discipline (CONFIG_PPP_ASYNC), the
driver for your serial port device and/or the PPP over Ethernet
(PPPoE) protocol driver (CONGIG_PPPOE) must be compiled into the
kernel or loaded as kernel modules.
Udev doesn't load the ppp_generic and pppoe modules automatically, they
must be mentioned in the <filename>/etc/sysconfig/modules</filename>
file.</para>
</note>
<indexterm zone="ppp ppp-kernel">
<primary sortas="d-PPP-support">PPP support</primary>
</indexterm>
<para>Create (as <systemitem class="username">root</systemitem>)
the group for users who may run <application>PPP</application>:</para>
<screen role="root"><userinput>groupadd -g 52 pppusers</userinput></screen>
<para>Install <application>PPP</application> by running the
following commands:</para>
<screen><userinput>./configure --prefix=/usr &amp;&amp;
make</userinput></screen>
<para>This package does not come with a test suite.</para>
<para>Now, as the <systemitem class="username">root</systemitem> user:</para>
<screen role='root'><userinput>make install &amp;&amp;
<!-- FIXME: is "make install-etcppp" needed for KPPP/WvDial?
The example configuration below overwrites two of three files, and
already includes the "lock" option in each peer file
-->make install-etcppp &amp;&amp;
install -d /etc/ppp/peers &amp;&amp;
install -m755 scripts/{pon,poff,plog} /usr/bin &amp;&amp;
install -m644 scripts/pon.1 /usr/share/man/man1</userinput></screen>
</sect2>
<sect2 role="commands">
<title>Command Explanations</title>
<para><command>make install-etcppp</command>: This command puts example
configuration files in <filename class="directory">/etc/ppp</filename>.</para>
<para><command>install -d /etc/ppp/peers</command>: This command creates
a directory for PPP peer description files.</para>
<!-- FIXME: the three options below are taken from pppd/Makefile.linux file.
They have not been tested. There are other options, such as USE_SRP=y,
that cannot work (in this case, because libsrp is not available from
anywhere) - Alexander E. Patrakov -->
<para><parameter>USE_PAM=y</parameter>: Add this argument to the
<command>make</command> command to compile in support for PAM, usually
needed for authenticating inbound calls against a central database.</para>
<para><parameter>HAVE_INET6=y</parameter>: Add this argument to the
<command>make</command> command to compile in support for IPv6.</para>
<para><parameter>CBCP=y</parameter>: Add this argument to the
<command>make</command> command to compile in support for
Microsoft proprietary Callback Control Protocol.</para>
</sect2>
<sect2 role="configuration">
<title>Configuring PPP</title>
<sect3 id="ppp-config">
<title>Config Files</title>
<para><filename>/etc/ppp/*</filename></para>
<indexterm zone="ppp ppp-config">
<primary sortas="e-etc-ppp-star">/etc/ppp/*</primary>
</indexterm>
</sect3>
<sect3>
<title>Configuration Information</title>
<para>The <application>PPP</application> daemon requires some
configuration. The main trick is scripting the connection.
For dialup and GPRS connections, this can be done
either using the <command>chat</command> program which comes with
this package, or by using external tools such as
<ulink url="http://alumnit.ca/wiki/?WvDial">WvDial</ulink>
or <application>KPPP</application> from
<xref linkend="kdenetwork"/>. The text below explains how to set up
dialup and GPRS and PPPoE connections using only tools provided with
the <application>PPP</application> package. All configuration steps
in this section are executed as
<systemitem class="username">root</systemitem> user.</para>
<para>Add the users who may run <application>PPP</application> to the
<systemitem class="groupname">pppusers</systemitem> group:</para>
<screen role="root"><userinput>usermod -a -G pppusers <replaceable>&lt;username&gt;</replaceable></userinput></screen>
<sect4>
<title>Setting the passwords</title>
<warning><para>Instructions in this section result in your password
appearing on the screen in a visible clear-text form. Make sure that
nobody else looks at the screen.</para></warning>
<para>Passwords are stored in <filename>/etc/ppp/pap-secrets</filename>
and <filename>/etc/ppp/chap-secrets</filename> files, depending on the
authentication method used by the ISP. If in doubt, place the password
into both files. E.g., if the username given by the ISP is
<quote>jdoe</quote>, the password is <quote>guessit</quote>, the
ISP uses PAP and the user wants to name this account
<quote>dialup</quote> in order to distinguish it from other PPP accounts,
the following file has to be created:</para>
<screen role="root"><userinput>touch /etc/ppp/pap-secrets
chmod 600 /etc/ppp/pap-secrets
cat &gt;&gt;/etc/ppp/pap-secrets &lt;&lt;"EOF"</userinput>
<literal># username remotename password IP for the peer
jdoe dialup guessit *</literal>
<userinput>EOF</userinput></screen>
</sect4>
<sect4>
<title>DNS Server Configuration</title>
<para>If you don't run your own caching DNS server, create a simple
<command>ip-up</command> script (to be called by <command>pppd</command>
automatically once the connection is brought up) that populates the
<filename>/etc/resolv.conf</filename> file with nameservers specified
by the ISP.</para>
<screen role="root"><userinput>cat &gt;/etc/ppp/ip-up &lt;&lt;"EOF"</userinput>
<literal>#!/bin/sh
if [ "$USEPEERDNS" = "1" ] &amp;&amp; [ -s /etc/ppp/resolv.conf ]
then
install -m 644 /etc/ppp/resolv.conf /etc/resolv.conf
fi</literal>
<userinput>EOF
chmod 755 /etc/ppp/ip-up</userinput></screen>
<para>If you use a caching DNS server such as <xref linkend="bind"/>
or <ulink url="http://www.phys.uu.nl/~rombouts/pdnsd.html">Pdnsd</ulink>,
the script above is wrong for you. In such case, write your
own script that tells your caching nameserver to forward queries to
upstream DNS servers specified in the $DNS1 and $DNS2 environment
variables.</para>
<!-- FIXME: write the replacement script that works with Bind -->
</sect4>
<sect4>
<title>Dialup Modem Connection</title>
<!-- This section has been tested with various ISPs in Yekaterinburg,
Russia using Lucent WinModem. I cannot test it anymore, because
there is no free PCI slot for the modem in my new computer. However,
it is similar enough to GPRS for me to be sure that it still works,
and nobody complained about non-working dialup on the LFS LiveCD.
- Alexander E. Patrakov -->
<para>Dialup connections are established with the help of a modem
connected to a computer and the telephone line. The modem dials a
telephone number of the ISP's modem, and they exchange data using
the signal frequencies 300-4000 Hz. Typical data transfer
rate is 40-50 kilobits per second, and the gateway ping time
(latency) is up to 300-400 ms. In order to configure the
dialup connection, it is required to know the telephone number of
the ISP's modem pool, the username and the password.</para>
<para>In order to configure a dialup connection, two files have to
be created: a chat script that automates the connection procedure
(common for all dialup accounts), and a peer file that provides
configuration information about a specific connection to
<command>pppd</command>:</para>
<screen role="root"><userinput>cat &gt;/etc/ppp/dialup.chat &lt;&lt;"EOF"</userinput>
<literal>ABORT BUSY ABORT 'NO CARRIER' ABORT VOICE ABORT 'NO DIALTONE'
ABORT 'NO DIAL TONE' ABORT 'NO ANSWER' ABORT DELAYED
ABORT ERROR ABORT BLACKLISTED
TIMEOUT 5
'' AT
# \T is the phone number, passed from /etc/ppp/peers/<replaceable>dialup</replaceable>
OK-+++\dATH0-OK ATD\T
TIMEOUT 75
CONNECT \d\c</literal>
<userinput>EOF
cat &gt;/etc/ppp/peers/<replaceable>dialup</replaceable> &lt;&lt;"EOF"</userinput>
<literal># Your username at the ISP
user "<replaceable>jdoe</replaceable>"
# What should be in the second column in /etc/ppp/*-secrets
remotename "<replaceable>dialup</replaceable>"
# Replace <replaceable>TTTTTTT</replaceable> with the ISP phone number
connect "/usr/sbin/chat -T <replaceable>TTTTTTT</replaceable> -f /etc/ppp/dialup.chat"
# Specify your modem serial port and speed below
<replaceable>/dev/ttyS0</replaceable>
<replaceable>115200</replaceable>
# The settings below usually don't need to be changed
updetach
noauth
hide-password
debug
lock
defaultroute
noipdefault
usepeerdns</literal>
<userinput>EOF</userinput></screen>
<para>The first three lines of the
<filename>/etc/ppp/dialup.chat</filename> file abort the script when
it receives an indication of an error from the modem. Then the timeout
is set to 5 seconds and the script checks that the modem responds to
the dummy AT command at all. If not, measures are taken to dewedge it
(by interrupting the data transfer and going on hook). Then the
telephone number is dialed, and the script waits for the answer for
75 seconds. The serial connection is considered established when the
modem sends the string CONNECT.</para>
</sect4>
<sect4>
<title>GPRS and EDGE Connections</title>
<!-- This section has been tested with GPRS service from MOTIV in
Yekaterinburg, Russia. According to forum messages, the procedure
also works with EDGE, but my cellular phone (Motorola C350) does not
support EDGE. - Alexander E. Patrakov -->
<para>GPRS and EDGE connections are established with the help of a
cellular phone connected to a computer via serial or USB cable, or
using Bluetooth.
The phone exchanges data packets with the nearest base station,
which can be up to 35 kilometers away.
<!-- FIXME: watch for new standards! SkyLink is already offering
3.1 megabits per second with CDMA mobile phones, and
the configuration below doesn't work. It is reported that
a regular dialup setup with the telephone number "#777",
username "mobile" and password "internet" works with SkyLink. -->
The maximum possible data transfer rate is 170 kilobits per second
for GPRS and 474 kilobits per second for EDGE, but many cellular
operators impose lower limits, such as 64 kilobits per second. The
gateway ping time is 900 ms for GPRS, which makes playing many online
games impossible and causes connection to ICQ to be unreliable.
In order to configure a GPRS or EDGE connection,
it is required to know the access point name (APN) and, rarely, the
username and the password.
In most cases, billing is based on the telephone number, and the
username/password pair is not needed, as assumed in the example
below.</para>
<para>In order to configure a GPRS connection, two files have to
be created: a chat script that automates the connection procedure
(common for all GPRS accounts), and a peer file that provides
configuration information about a specific connection to
<command>pppd</command>:</para>
<screen role="root"><userinput>cat &gt;/etc/ppp/gprs.chat &lt;&lt;"EOF"</userinput>
<literal>ABORT BUSY ABORT 'NO CARRIER' ABORT VOICE ABORT 'NO DIALTONE'
ABORT 'NO DIAL TONE' ABORT 'NO ANSWER' ABORT DELAYED
ABORT ERROR ABORT BLACKLISTED
TIMEOUT 5
'' AT
OK-+++\dATH0-OK ATZ
# \T is the APN, passed from /etc/ppp/peers/<replaceable>gprs</replaceable>
# This example stores the APN as profile #1 in the phone.
# The "telephone number", *99***&lt;profile_number&gt;#, is always the same.
# If you want to store this as profile #2, change 1 to 2 in the
# following two lines.
OK AT+CGDCONT=<replaceable>1</replaceable>,"IP","\T"
OK "ATD*99***<replaceable>1</replaceable>#"
CONNECT \d\c</literal>
<userinput>EOF
cat &gt;/etc/ppp/peers/<replaceable>gprs</replaceable> &lt;&lt;"EOF"</userinput>
<literal># Replace <replaceable>inet.example.com</replaceable> with the proper APN for your provider
connect "/usr/sbin/chat -T <replaceable>inet.example.com</replaceable> -f /etc/ppp/gprs.chat"
# Specify your cellphone serial port and speed below
# Note: you must manually send some vendor-specific AT commands
# to certain old cellular phones (such as Sony-Ericsson T200)
# in order to achieve connection speed more than 9600 bits ber second.
<replaceable>/dev/ttyS1</replaceable>
<replaceable>115200</replaceable>
# The settings below usually don't need to be changed
noccp
noauth
updetach
debug
lock
defaultroute
noipdefault
usepeerdns</literal>
<userinput>EOF</userinput></screen>
</sect4>
<sect4>
<title>PPPoE connections</title>
<!-- This section has been tested with the "USI" ISP in Yekaterinburg,
Russia. Other editors can test it as described in
http://linuxfromscratch.org/pipermail/blfs-dev/2008-March/018290.html
- Alexander E. Patrakov -->
<para>PPPoE connections are established over Ethernet, typically between
a computer and an ADSL router (usually installed in the same room)
that forwards the packets down the telephone line using frequencies
25-2500 kHz, thus not interfering with voice calls. Although the router
can, in theory, forward any Ethernet packet, PPP encapsulation is used
for password-based authentication, so that the ISP can limit the
bandwidth and charge money according to the chosen tariff. The maximum
data transfer rate on ADSL is 24 megabits per second, and the gateway
ping time is typically less than 10 ms. In order to configure a PPPoE
connection, it is required to know the username, the password, and,
sometimes, the service name and/or the access concentrator name.</para>
<para>In order to configure a PPPoE connection, only the peer file
has to be created:</para>
<screen role="root"><userinput>cat &gt;/etc/ppp/peers/<replaceable>adsl</replaceable> &lt;&lt;"EOF"</userinput>
<literal>plugin rp-pppoe.so
# Ethernet interface name
<replaceable>eth0</replaceable>
# Your username at the ISP
user "<replaceable>jdoe</replaceable>"
# What should be in the second column in /etc/ppp/*-secrets
remotename "<replaceable>adsl</replaceable>"
# If needed, specify the service and the access concentrator name
# rp_pppoe_service "<replaceable>internet</replaceable>"
# rp_pppoe_ac "<replaceable>ac1</replaceable>"
# The settings below usually don't need to be changed
noauth
hide-password
updetach
debug
defaultroute
noipdefault
usepeerdns</literal>
<userinput>EOF</userinput></screen>
</sect4>
<sect4>
<title>Establishing the connection manually</title>
<para>In order to establish a PPP connection described by the
<filename>/etc/ppp/peers/<replaceable>peername</replaceable></filename>
file, run, as root or as a member of the
<systemitem class="groupname">pppusers</systemitem> group:</para>
<screen><userinput>pon <replaceable>peername</replaceable></userinput></screen>
<para>In order to tear the connection down, run:</para>
<screen><userinput>poff <replaceable>peername</replaceable></userinput></screen>
</sect4>
<sect4>
<title>Bringing up PPPoE connection at boot time</title>
<para>If your service provider does not charge by the minute, it is
usually good to have a bootscript handle the connection for you.
You can, of course, choose not to install the following script, and
start your connection manually with the <command>pon</command> command,
as described above. If you wish your PPPoE connection to be brought
up at boot time, run:</para>
<screen role='root'><userinput>make install-service-pppoe</userinput></screen>
<para>The above command installs the <filename>pppoe</filename>
service script and the <filename>/etc/ppp/peers/pppoe</filename>
file with some settings that make sense for most PPPoE connections.
The bootscript calls <command>pppd</command> with the the following
options:</para>
<screen>pppd call pppoe ${1} linkname ${1} ${PPP_OPTS}</screen>
<para>Here <quote>${1}</quote> is the network interface name,
<quote>linkname ${1}</quote> is added for creation of the
<filename>/var/run/ppp-${1}.pid</filename> file with the
<command>pppd</command> process ID (to be used when bringing
the connection down), and the <quote>${PPP_OPTS}</quote> variable
contains user-specified options such as <quote>user</quote> and
<quote>remotename</quote>.</para>
<para>Now create the config file for use with the <filename>pppoe</filename>
service script:</para>
<screen role='root'><userinput>install -v -d /etc/sysconfig/network-devices/ifconfig.eth0 &amp;&amp;
cat &gt; /etc/sysconfig/network-devices/ifconfig.eth0/pppoe &lt;&lt; "EOF"
<literal>ONBOOT="yes"
SERVICE="pppoe"
PPP_OPTS="user <replaceable>jdoe</replaceable> remotename <replaceable>adsl</replaceable>"</literal>
EOF</userinput></screen>
<note><para>Instead of specifying additional options in the $PPP_OPTS
variable, you can also edit the <filename>/etc/ppp/peers/pppoe</filename>
file, but then your configuration will be lost when upgrading
BLFS bootscripts.</para></note>
</sect4>
</sect3>
</sect2>
<sect2 role="content">
<title>Contents</title>
<segmentedlist>
<segtitle>Installed Programs</segtitle>
<segtitle>Installed Libraries</segtitle>
<segtitle>Installed Directories</segtitle>
<seglistitem>
<seg>chat, pon, poff, plog, pppd, pppdump, pppoe-discovery and pppstats</seg>
<seg>Several plugin modules installed in
<filename class='directory'>/usr/lib/pppd/&ppp-version;</filename></seg>
<seg>/etc/ppp, /usr/include/pppd and /usr/lib/pppd</seg>
</seglistitem>
</segmentedlist>
<variablelist>
<bridgehead renderas="sect3">Short Descriptions</bridgehead>
<?dbfo list-presentation="list"?>
<?dbhtml list-presentation="table"?>
<varlistentry id="chat">
<term><command>chat</command></term>
<listitem>
<para>defines a conversational exchange between the computer and the
modem. Its primary purpose is to establish the connection between the
Point-to-Point Protocol Daemon (PPPD) and the remote
<command>pppd</command> process.</para>
<indexterm zone="ppp chat">
<primary sortas="b-chat">chat</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="pon">
<term><command>pon</command></term>
<listitem>
<para>is the script that establishes a PPP connection</para>
<indexterm zone="ppp pon">
<primary sortas="b-pon">pon</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="poff">
<term><command>poff</command></term>
<listitem>
<para>is the script that tears a PPP connection down.</para>
<indexterm zone="ppp poff">
<primary sortas="b-poff">poff</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="plog">
<term><command>plog</command></term>
<listitem>
<para>is a script that prints the tail of the PPP log.</para>
<indexterm zone="ppp plog">
<primary sortas="b-plog">plog</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="pppd">
<term><command>pppd</command></term>
<listitem>
<para>is the Point to Point Protocol daemon.</para>
<indexterm zone="ppp pppd">
<primary sortas="b-pppd">pppd</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="pppdump">
<term><command>pppdump</command></term>
<listitem>
<para>is used to convert
<application>PPP</application> record files to a readable
format.</para>
<indexterm zone="ppp pppdump">
<primary sortas="b-pppdump">pppdump</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="pppstats">
<term><command>pppstats</command></term>
<listitem>
<para>is used to print
<application>PPP</application> statistics.</para>
<indexterm zone="ppp pppstats">
<primary sortas="b-pppstats">pppstats</primary>
</indexterm>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>