source: connect/other/pppoe.xml@ 68dcb2dd

<?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>: <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 recomended 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 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 /etc/sysconfig/network-devices/ifconfig.eth0/*</userinput></screen>
      </note>

<screen role='root'><userinput>install -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>