source: connect/dialup/ppp.xml@ 782820d

<?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), and the
      driver for your serial port device must be
      compiled into the kernel or loaded as a kernel module.
      Udev doesn't load the ppp_generic module automatically, it 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>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>groupadd -g 52 pppusers &amp;&amp;
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>

      <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>Establishing the connection</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>
    </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>