source: connect/other/pppoe.xml@ 919683dc

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY pppoe-download-http "http://www.roaringpenguin.com/penguin/pppoe/rp-pppoe-&pppoe-version;.tar.gz">
  <!ENTITY pppoe-download-ftp  "ftp://ftp.fu-berlin.de/unix/linux/mirrors/gentoo/distfiles/rp-pppoe-&pppoe-version;.tar.gz">
  <!ENTITY pppoe-md5sum        "97972f8f8f6a3ab9b7070333a6a29c4b">
  <!ENTITY pppoe-size          "185 KB">
  <!ENTITY pppoe-buildsize     "2.2 MB">
  <!ENTITY pppoe-time          "0.05 SBU">
]>

<sect1 id="pppoe" xreflabel="RP-PPPoE-&pppoe-version;">
  <?dbhtml filename="pppoe.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>RP-PPPoE-&pppoe-version;</title>

  <indexterm zone="pppoe">
    <primary sortas="a-RP-PPPoE">RP-PPPoE</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to RP-PPPoE</title>

    <para>The Roaring Penguin <application>PPPoE</application>
    package contains both a client and a server component that works with the
    client. The client allows you to connect to large networks that use the
    PPPoE protocol, common among ADSL providers. The server component
    runs alongside the client, allowing you to configure other clients that send
    out a configuration request.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&pppoe-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&pppoe-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &pppoe-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &pppoe-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &pppoe-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &pppoe-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">RP-PPPoE Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para><xref linkend="ppp"/> and
    <xref linkend="net-tools"/> (you may omit
    <application>Net-tools</application> by using the following patch to
    utilize <application>IPRoute2</application> instead: <ulink
    url="&patch-root;/rp-pppoe-&pppoe-version;-iproute2-1.patch"/>)</para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of RP-PPPoE</title>

    <note id="pppoe-kernel">
      <para>If you plan on using kernel-mode PPPoE, this package is no longer explicitly
      needed, however, it is recommended for ease of configuration. Additional information
      about kernel mode PPPoE can be found in
      <filename>rp-pppoe-&pppoe-version;/doc/KERNEL-MODE-PPPOE</filename>.</para>
    </note>

    <indexterm zone="pppoe pppoe-kernel">
      <primary sortas="d-Kernel-mode-PPPoE">Kernel-mode PPPoE</primary>
    </indexterm>

    <para>Fix the location of the logger executable in several ADSL scripts:</para>

<screen><userinput>sed -i s%/usr/bin/logger%/bin/logger% \
    scripts/adsl-{connect,setup,stop}.in</userinput></screen>

    <para>Install <application>RP-PPPoE</application> by running the following
    commands:</para>

<screen><userinput>cd src &amp;&amp;
./configure &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</userinput></screen>

  </sect2>

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

    <para>These are the standard installation commands that will install the
    package into the <filename class="directory">/usr</filename> prefix.  You
    can optionally use the <command>go</command> script in the root of the
    source tree to run the same commands, which are then immediately followed
    by the <command>adsl-setup</command> script.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring RP-PPPoE</title>

    <sect3 id="pppoe-config">
      <title>Config Files</title>

      <para><filename>/etc/ppp/pppoe.conf</filename>,
      <filename>/etc/ppp/firewall-standalone</filename>,
      <filename>/etc/ppp/firewall-masq</filename>,
      <filename>/etc/ppp/pppoe-server-options</filename>,
      <filename>/etc/resolv.conf</filename>,
      <filename>/etc/ppp/pap-secrets</filename>,
      <filename>/etc/ppp/chap-secrets</filename></para>

      <indexterm zone="pppoe pppoe-config">
        <primary sortas="e-etc-ppp-pppoe.conf">/etc/ppp/pppoe.conf</primary>
      </indexterm>

      <indexterm zone="pppoe pppoe-config">
        <primary sortas="e-etc-ppp-firewall-standalone">/etc/ppp/firewall-standalone</primary>
      </indexterm>

      <indexterm zone="pppoe pppoe-config">
        <primary sortas="e-etc-ppp-firewall-masq">/etc/ppp/firewall-masq</primary>
      </indexterm>

      <indexterm zone="pppoe pppoe-config">
        <primary sortas="e-etc-ppp-pppoe-server-options">/etc/ppp/pppoe-server-options</primary>
      </indexterm>

      <indexterm zone="pppoe pppoe-config">
        <primary sortas="e-etc-resolv.conf">/etc/resolv.conf</primary>
      </indexterm>

      <indexterm zone="pppoe pppoe-config">
        <primary sortas="e-etc-ppp-pap-secrets">/etc/ppp/pap-secrets</primary>
      </indexterm>

      <indexterm zone="pppoe pppoe-config">
        <primary sortas="e-etc-ppp-chap-secrets">/etc/ppp/chap-secrets</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>To configure <application>RP-PPPoE</application> after installation,
      you should run the <command>adsl-setup</command> script.</para>

      <para>When configuring your connection, you will need to have your
      ISP's nameserver information available, as well as your
      username and password.  You will also be asked whether to configure a
      dial-on-demand or a constant connection.  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>adsl-start</command> script.</para>

      <para id="pppoe-init"><emphasis>Optionally</emphasis> install the
      <filename>/etc/sysconfig/network-devices/services/pppoe</filename> service
      script included with the <xref linkend="intro-important-bootscripts"/>
      package (as user <systemitem class="username">root</systemitem>).</para>

      <indexterm zone="pppoe pppoe-init">
        <primary sortas="f-pppoe-service-script">pppoe (service script)</primary>
      </indexterm>

<screen role='root'><userinput>make install-service-pppoe</userinput></screen>

      <para id="pppoe-config2">Now create the config file for use with the
      <filename>pppoe</filename> service script (as user <systemitem
      class="username">root</systemitem>):</para>

      <indexterm zone="pppoe pppoe-config2">
        <primary sortas="e-etc-sysconfig-pppoe">/etc/sysconfig/.../pppoe</primary>
      </indexterm>

      <note>
        <para>If you have previously configured the network interface that
        will now use PPPoE, you should remove the interface
        configuration files for that interface (as user <systemitem
        class="username">root</systemitem>):</para>

<screen role='root'><userinput>rm -v /etc/sysconfig/network-devices/ifconfig.eth0/*</userinput></screen>
      </note>

<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"</literal>
EOF</userinput></screen>

      <!-- A TYPE="[user/kernel]" will be added at a later date when kernel
      mode pppoe is described here. -->

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>adsl-connect, adsl-setup, adsl-start, adsl-status, adsl-stop, pppoe,
        pppoe-relay, pppoe-server and pppoe-sniff</seg>
        <seg>None</seg>
        <seg>/etc/ppp/plugins and /usr/share/doc/rp-pppoe-&pppoe-version;</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="adsl-connect">
        <term><command>adsl-connect</command></term>
        <listitem>
          <para>is a shell script which manages an ADSL
          connection using the user-space PPPoE client.</para>
          <indexterm zone="pppoe adsl-connect">
            <primary sortas="b-adsl-connect">adsl-connect</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="adsl-setup">
        <term><command>adsl-setup</command></term>
        <listitem>
          <para>is a script for configuring the client. Configuration is
          then stored in <filename>/etc/ppp/pppoe.conf</filename>.</para>
          <indexterm zone="pppoe adsl-setup">
            <primary sortas="b-adsl-setup">adsl-setup</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="adsl-start">
        <term><command>adsl-start</command></term>
        <listitem>
          <para>starts the client using the options specified in
          <filename>/etc/ppp/pppoe.conf</filename>.</para>
          <indexterm zone="pppoe adsl-start">
            <primary sortas="b-adsl-start">adsl-start</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="adsl-status">
        <term><command>adsl-status</command></term>
        <listitem>
          <para>displays the status of the ADSL
          connection.</para>
          <indexterm zone="pppoe adsl-status">
            <primary sortas="b-adsl-status">adsl-status</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="adsl-stop">
        <term><command>adsl-stop</command></term>
        <listitem>
          <para>stops the client.</para>
          <indexterm zone="pppoe adsl-stop">
            <primary sortas="b-adsl-stop">adsl-stop</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pppoe-prog">
        <term><command>pppoe</command></term>
        <listitem>
          <para>is the client program. Generally it should not be started on
          its own.</para>
          <indexterm zone="pppoe pppoe-prog">
            <primary sortas="b-pppoe">pppoe</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pppoe-relay">
        <term><command>pppoe-relay</command></term>
        <listitem>
          <para>starts the server relay agent.</para>
          <indexterm zone="pppoe pppoe-relay">
            <primary sortas="b-pppoe-relay">pppoe-relay</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pppoe-server">
        <term><command>pppoe-server</command></term>
        <listitem>
          <para>starts the server component.</para>
          <indexterm zone="pppoe pppoe-server">
            <primary sortas="b-pppoe-server">pppoe-server</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pppoe-sniff">
        <term><command>pppoe-sniff</command></term>
        <listitem>
          <para>is a small network sniffer designed to assist in setting
          <envar>PPPOE_EXTRA</envar> settings.</para>
          <indexterm zone="pppoe pppoe-sniff">
            <primary sortas="b-pppoe-sniff">pppoe-sniff</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>