source: connect/dialup/ppp.xml@ ab8365a

<?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 -m755 scripts/{pon,poff,plog} /usr/bin &amp;&amp;
instal -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>

<!-- 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 <xref linkend="wvdial"/>
      or <application>KPPP</application> from
      <xref linkend="kdenetwork"/>. The text below explains how to set up
      PPPoE, dialup and GPRS 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>

    <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/adsl &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>