source: archive/ppp.xml@ dfd51cd7

<?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        "4621bc56167b6953ec4071043fe0ec57">
  <!ENTITY ppp-size          "920 KB">
  <!ENTITY ppp-buildsize     "6.4 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>

    &lfs70_checked;

    <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)
    and <xref linkend="linux-pam"/> (to authenticate incoming calls using PAM -
    only needed by ISPs).
    </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. If you
      compiled them as modules they can be loaded by the modules bootscript if
      they are mentioned in <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>Compile <application>PPP</application> by running the
    following commands:</para>

<screen><userinput>rm include/linux/if_pppol2tp.h &amp;&amp;
./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;
install -d /etc/ppp/peers</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>rm include/linux/if_pppol2tp.h</command>:
    <application>PPP-&ppp-version;</application> contains an out of date copy
    of the kernel header <filename>linux/if_pppol2tp.h</filename>. This needs to
    be removed to <emphasis>force</emphasis> it to use the one installed in
    <filename class="directory">/usr</filename>. If you don't remove this file
    the build will still succeed (thanks to a poorly written
    <filename>Makefile</filename>) but it will fail to compile the
    <filename class="libraryfile">openl2tp.so</filename>,
    <filename class="libraryfile">pppol2tp.so</filename>,
    and <filename class="libraryfile">rp-pppoe.so</filename> plugins:</para>

    <para><command>install -d /etc/ppp/peers</command>: This command creates
    a directory for PPP peer configuration 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 the
    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>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>

      <para>Most internet service providers that use ppp give you a username
      and password for you to use to authenticate yourself when you connect to
      their servers. These secrets are kept in the files
      <filename>/etc/ppp/pap-secrets</filename> or
      <filename>/etc/ppp/chap-secrets</filename>. If you don't know whether
      your ISP uses CHAP or PAP then create both files and put the same content
      in both files.</para>

      <para>If you have more than one ISP account the second column
      (remotename) is used to identify between the different
      usernames/passwords needed for the different ISPs. If you only have one
      ISP account an asterisk will work fine in the second column.</para>

      <para>In this example 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 give this account the remotename
      <quote>dialup</quote> in order to distinguish it from other PPP
      accounts:</para>

<screen role="root"><userinput>cat &gt;&gt;/etc/ppp/pap-secrets &lt;&lt;"EOF"</userinput>
<literal># username      remotename    password
jdoe            dialup        guessit</literal>
<userinput>EOF
chmod 600 /etc/ppp/pap-secrets</userinput></screen>

    <sect4>
      <title>DNS Server Configuration</title>

      <para>If you don't run your own caching DNS server (like
      <xref linkend="bind"/>) <command>pppd</command> can ask your ISP for its
      domain name servers and put them in <filename>/etc/ppp/resolv.conf</filename>.
      If you want to use their domain name servers:</para>

<screen role="root"><userinput>mv /etc/resolv.conf{,.orig}
ln -s ppp/resolv.conf /etc</userinput></screen>

    </sect4>

    <sect4>
      <title>PPPoE connections</title>

      <para>In order to configure a PPPoE connection, create a peer file that
      contains the connection details:</para>
<screen role="root"><userinput>cat &gt;/etc/ppp/peers/<replaceable>peername</replaceable> &lt;&lt;"EOF"</userinput>
<literal>plugin rp-pppoe.so <replaceable>eth0</replaceable>

# Your username at the ISP. This is the same as the first
# column in /etc/ppp/*-secrets:
user "<replaceable>jdoe</replaceable>"

# remotename is not needed if you only have one ISP account and
# hence an asterisk in the second column in pap or chap-secrets:
# remotename "<replaceable>adsl</replaceable>"

# If it's not working and you want pppd to be
# more verbose in /var/log/sys.log, add debug:
# debug

# If you have a static IP address (eg, 12.34.56.78) you
# can specify it by following it with a colon:
# 12.34.56.78:

# Otherwise accept whatever IP address the ISP gives you:
noipdefault

# The settings below usually don't need to be changed
noauth
hide-password
updetach
defaultroute
# create /etc/ppp/resolv.conf:
usepeerdns

### For more details (and more options)
### read man pppd</literal>
<userinput>EOF
chmod 600 /etc/ppp/peers/<replaceable>peername</replaceable></userinput></screen>
    </sect4>

    <sect4>
      <title>PPPoATM connections</title>

      <para>PPPoA connections are very similar to PPPoE, the main differences
      are that you use the pppoatm.so plugin instead of rp-pppoe.so, you don't
      specify the ethernet interface (it uses ppp0) and you need to VP/VC
      numbers that are used by your ISP (there is a list of VP/VC numbers
      <ulink url="http://www.linux-usb.org/SpeedTouch/faq/index.html#q12">here
      </ulink>)</para>

<screen role="root"><userinput>cat &gt;/etc/ppp/peers/<replaceable>peername</replaceable> &lt;&lt;"EOF"</userinput>
<literal>plugin pppoatm.so

# Your VP/VC numbers. eg, in Britain it is 0.38, in
# France they use 8.35. Google is your friend :)
0.38

# Your username at the ISP. This is the same as the
# first column in /etc/ppp/*-secrets:
user "<replaceable>jdoe</replaceable>"

# remotename is not needed if you only have one ISP account and
# hence an asterisk in the second column in pap or chap-secrets:
# remotename "<replaceable>adsl</replaceable>"

# If it's not working and you want pppd to be
# more verbose in /var/log/sys.log, add debug:
# debug

# If you have a static IP address (eg, 12.34.56.78) you
# can specify it by following it with a colon:
# 12.34.56.78:

# Otherwise accept whatever IP address the ISP gives you:
noipdefault

# The settings below usually don't need to be changed
noauth
hide-password
updetach
defaultroute
# create /etc/ppp/resolv.conf:
usepeerdns

### For more details (and more options)
### read man pppd</literal>
<userinput>EOF
chmod 600 /etc/ppp/peers/<replaceable>peername</replaceable></userinput></screen>

    </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. 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, USB, or 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 per 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>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 <systemitem class="username">root</systemitem> or as a member
      of the <systemitem class="groupname">pppusers</systemitem> group):</para>
<screen><userinput>pppd call <replaceable>peername</replaceable></userinput></screen>

      <para>In order to stop the connection, run:</para>
<screen><userinput>killall pppd</userinput></screen>

      <!--  There are an infinite number of ways that computers can be
      connected together. Trying to write a bootscript that can cope with every
      possible network configuration is the road to madness. Andrew Benton -->

      <para>Writing a bootscript that brings up the connection during the boot
      process is left as an exercise for the reader ;)</para>

    </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, 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="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="pppoe-discovery">
        <term><command>pppoe-discovery</command></term>
        <listitem>
          <para>performs the same discovery process as the pppoe plugin, but
          does not initiate a <application>PPP</application> session.</para>
          <indexterm zone="ppp pppoe-discovery">
            <primary sortas="b-pppoe-discovery">pppoe-discovery</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>