Welcome to the ACUA PPP over Ethernet HOWTO.

Introduction:

    In this document I will describe how to set up a PPPoE server,
    where and how to get PPPoE clients, and how to set up ACUA for
    PPPoE monitoring.

    My test system is running Kernel 2.4.13 and a patched PPPD.


Programs you'll need to get:

    Roaring Penguin's PPPoE for Linux (you need the server program out of this).
    Patched PPPD for Roaring Penguins PPPoE.
	http://www.roaringpenguin.com/pppoe/
    
    ACUA v3.04 or newer.  ACUA v3.04 is the first ACUA with PPPoE support.
	http://acua.ebbs.com.au/


Some basic stuff you should know:

    The PPPoE (PPP over Ethernet) server is called an Access Concentrator.
    I will show you how to make your Linux box emulate an Access Concentrator
    as you need this to get PPPoE working.  I may at times call the Access
    Concentrator an AC for short.

    PPPoE is literally just that.  The PPPoE protocol itself is simple,
    and basically it provides a way to fool pppd into thinking it's running
    over a phone line, where in fact it is running over an Ethernet connection.


Lets get to it!

    The ACUA installation is really easy for PPPoE, in fact you probably wont
    need to configure a thing to actually get it working, but there are a few
    things I do suggest you configure, I'll get to that shortly.
    
    Unpack the ACUA archive that you have downloaded.  At the moment because
    PPPoE support is still very new, I'd suggest always using the latest
    version of ACUA.
    
    Once you've unpacked ACUA (for this tutorial we will assume you have
    unpacked it to /usr/src/acua-3.04)
    
    cd /usr/src/acua-3.04
    make dep
    make
    make install
    
    ACUA is now installed.
    
    There is two PPPoE-specific executables that come with ACUA v3.04.
    
    The executables are acua_login_pppoe and acua_logout_pppoe, which I'll
    explain how to use later.
    
    Next, unpack the Roaring Penguin PPPoE package.  To keep things easy I
    will assume it's been unpacked into /usr/src/rp-pppoe-3.3
    
    cd /usr/src/rp-pppoe-3.3/src
    ./configure
    make
    make install
    
    RP-PPPoE is now installed.
    
    Next, you need to install the patched PPPD which supports RP-PPPoE.
    If you haven't already, you can download the patched PPPD from the
    Roaring Penguin web site.

    To install the patched PPPD, unpack it to /usr/src/pppd-2.4.1.pppoe2,
    again, I'll now assume you've unpacked the special pppd into
    /usr/src/pppd-2.4.1.pppoe2.  I've also seen a pppoe4 version of this
    pppd but I'm not sure if it's the official one to use or not, so I've
    used the pppoe2 version on my system.
    
    cd /usr/src/pppd-2.4.1.pppoe2
    ./configure
    make
    make install
    
    The special PPPD is now installed.  This PPPD can also accept and make
    normal modem connections.
    

Configuring things:

    I'll keep the configuration simple.  It took me a while to get the PPPoE
    server running.  This I think was mainly because the PPPoE in my
    distribution was broken, so I had to download the vanilla source from the
    Roaring Penguin web site before it would work.  That cost me at least 12
    hours in development time, but it also gave me a chance to read through
    the pppoe-server source code, and I must say, the code is very good
    quality indeed.  I also read the PPPoE RFC to familiarise myself with
    the way it all works, that was also well worth it, but you shouldn't have
    to go to those extremes.  After all, what else is a HOWTO for, apart from
    letting you cheat? :)

Configuring ACUA

    Very little has to be done to configure ACUA.  There is however a
    thing or two that you'll probably want to change.
    
    Firstly, a standard feature of ACUA is to offer idle timeouts for both
    shell and ppp connections.  I would suggest that you either increase the
    idle timeout, or disable it all together.
    
    The ACUA configuration file is /usr/lib/acua/acua.config, in that file
    you will see a few things.  You can safely ignore the devices line in
    there as this doesn't apply to PPPoE.
    
    In the ACUA config file, I suggest you find the following and tweak them:
    
    MailProg - The location of the "mail" program on your system.  If you are
    not sure where this program is then go to the Linux command prompt and
    type:
    
    which mail
    
    it will come back with something like /bin/mail or /usr/bin/mail.  So,
    make the MailProg configuration line look like:
    
    MailProg /usr/bin/mail
    
    Next, you should tweak the Idle Timeout values.  You can ignore the TTY
    Idle Timeouts, and just tweak the PPP ones.  By default, the PPP Idle
    Timeout line looks like:
    
    PPPIdleBoot 15 15360
    
    This means that PPP connections by default have a 15 minute timeout, and
    are also required to transfer 15360 bytes (15 * 1024 = 15360 bytes which
    is exactly 15k)  The reason for the minimum data limit is to help stop
    people leaving a PPP connection running with ping going in the background
    continually pinging something to keep the link from looking like it is
    idle.  For LANs and the like that have PPPoE running, I suggest that you
    set the PPPIdleBoot to something like:
    
    PPPIdleBoot 0 0
    
    This effectively disables the PPP idle timeouts in ACUA.  You can also
    set PPP idle timeouts on a per-user basis once the user has been created.

    One more very important thing you need to do is have acua_login_pppoe run
    automatically when there is a PPPoE connection.  This is configured in
    the /etc/ppp/ip-up script.  The way I have done this is like so:
    
    if [ "$PPP_TTY" == "" ]; then
        # PPPoE Connection Detected
	acua_login || kill -HUP "$PPPD_PID"
    fi
	    
    You should also (but you don't need to) configure a similar thing in
    /etc/ppp/ip-down, like so:
    
    if [ "$PPP_TTY" == "" ]; then
        # PPPoE Connection Ended
	acua_logout
    fi
	    
    If you neglect to configure the /etc/ppp/ip-down script with the above,
    users will not be logged out until acua_updated does it's next update
    run (once a minute), and because PPPoE connections can typically connect
    back very fast, if ACUA still thinks the old session is running, it will
    deny the login.


Configuring the RP-PPPoE server (Access Concentrator)
    
    When you installed RP-PPPoE, it put some files into /etc/ppp.  We should
    go and do some stuff here now.
    
    cd /etc/ppp
    cp pppoe-server-options-example pppoe-server-options
    
    Now you need to edit the pppoe-server-options file in /etc/ppp, make it
    look something like this:
    
    # PPP options for the PPPoE server
    require-pap
    login
    lcp-echo-interval 60
    lcp-echo-failure 2
    
    The "login" option is vital.  ACUA needs this otherwise it will think
    your PPPoE client has terminated the connection to the PPPoE server.
    
    The "login" option tells PPPD to do two things.
    
	1) Use /etc/passwd and /etc/shadow for authentication.
	
	2) Write an entry into utmp, so the user shows up when you type
	   "who" or "w" at the Linux prompt.

    Next, you need to edit /etc/ppp/pap-secrets, and add a line like so:
    
	*	*	""	*

    This line, along with the "login" option mentioned above, allows pppd to
    look in /etc/passwd and/or /etc/shadow for the users password when doing
    authentication.  If you do not have this line, you will get an
    Authentication Failure when your PPPoE client attempts to connect to
    the Access Concentrator (the server).
    
    If you want to use CHAP authentication as opposed to PAP, you need to
    put the same line above into /etc/ppp/chap-secrets.
    
    The permissions on /etc/ppp/pap-secrets and /etc/ppp/chap-secrets are
    also important to set correctly, so to make sure everything has the
    right permissions, run the following commands:
    
    chown root.root /etc/ppp/pap-secrets
    chown root.root /etc/ppp/chap-secrets
    chmod 600 /etc/ppp/pap-secrets
    chmod 600 /etc/ppp/chap-secrets
    
    PPPD is fussy about these permissions, and if set too insecure, PPPD will
    refuse to authenticate the client, and you'll get another
    Authentication Failure.
    

Adding users to the system:

    To add a user to the system, you really should take a look at the
    acua_adduser script and make it suit your system.  After you have
    done any needed changes to that script (/usr/sbin/acua_adduser) you
    can then run acua_adduser and add a user to the system.
    
    acua_adduser test
    
    [ acua_adduser will ask you for a password for the account and a few
      other details ]
    
    Now you should give the user a subscription:
    
    acua subscribe test 30 1440
    
    This will give the user "test" a 30-day account with 1440 minutes a
    day access time.  You can also set session limits, download limits,
    upload limits, access times, etc.  See the standard ACUA documentation
    for that though as I won't explain it here.
    
    Ok, so now you have ACUA, RP-PPPoE, and a special PPPD set up on your
    server.  Now it's time to make the required programs start automatically,
    and the easiest way to do this is.....
    
    edit /etc/inittab, and add two lines to the end of it:
    
    au:2345:respawn:/usr/sbin/acua_updated -d
    ac:2345:respawn:/usr/sbin/pppoe-server -F -I eth0
    
    ^^ Notice the au and ac is different at the start of the lines.
      
    The first line above starts the ACUA Update daemon which is in charge
    of kicking users off when they exceed time/data/session limits, or if
    their subscription expires, etc.  This program is vital, and you will
    not like the results if it's not running (no accounting, no users being
    kicked off when necessary, etc).
    
    The second line above starts the PPPoE Access Concentrator (server).
    If your PPPoE clients are on eth1 instead of eth0, change the line above
    to suit.  You do not actually need to specify an Ethernet interface to
    use though.  On my test system I used eth0, which also had other computers
    running off it at the same time.
    
    Now at the Linux command prompt, you need to type the command:
    
    init q
    
    This will tell the INIT program (which is always running) to re-read
    /etc/inittab and to run the two new programs you just put in there.
    
    Once you type "init q" at the command-line, ACUA will be running and
    so will your PPPoE Access Concentrator.


Setting up the PPPoE clients (Linux and Windows):


    Linux:

    This is probably the easiest part of the whole process.  On Linux, you can
    type adsl-setup to set up your PPPoE connection.  If you do not have
    adsl-setup, there is another tool which can be found in Debian called
    pppoeconf which is really nice, but a little dodgy when it comes to
    detecting your Ethernet card if it does not have an IP Address assigned
    to it.  The adsl-setup package is included with RP-PPPoE.
    

    Windows:

    And the fun begins.
    
    When it comes to Windows, there doesn't seem to be many FREE PPPoE clients.
    
    One that I have used with this PPPoE setup is RASPPPoE, which works very
    well, and can be found at:
    
	RASPPPoE Web site - http://user.cs.tu-berlin.de/~normanb/
    
    Alternatively, if you can't get along with RASPPPoE, there is another way
    to get PPPoE clients for free, but it's probably not really legal.  I'll
    explain anyway and leave the choice up to you.
    
    It seems that most PPPoE clients are licensed to ISP's.  Some of us are
    not going to pay for PPPoE client licenses.  So, to get a good PPPoE client
    that you're probably supposed to in-directly pay for, but for free, you
    simply visit a few ISP's home pages which provide an ADSL service and
    download their client.  Thats what I did and the client I got is a nice
    one, works exceptionally well (no faults yet, no crashes, no unexpected
    sessions terminated, etc).
    
    Some ISP's password protect their web site where the PPPoE clients reside,
    which I guess is probably what they're supposed to do (or at least restrict
    them to members only).
    
    So simply download either RASPPPoE which is legal (read the license
    though!) or go and get some other ISP's PPPoE client and change any
    settings you need to change. :)

    It has come to my attention that versions of EnterNet prior to v1.34
    are buggy and sometimes (or always) don't put in a default route on
    the Windows PC.  So, if using EnterNet and you're not getting anywhere,
    this could be why.

Test your setup:

    Go on! Test it!
    
    Cross your fingers, ring everyone and make them prey for success on
    your behalf - you'll probably need it.
    
    Are you feeling confident now?


Getting help:

    ACUA v3.04 is the first to have PPPoE support, and it was somewhat a
    fluke that I got it working as well and quickly that I did, so there
    is bound to be a glitch somewhere in the software.  If you are having
    ANY PROBLEM AT ALL with ACUA, using the PPPoE stuff, you are more than
    welcome to contact me because I'm more than eager to help you and to find
    any bugs in the PPPoE support in ACUA!
    
    You can contact me on acua@acua.ebbs.com.au
    
    Or you may use the ACUA mailing list by sending an E-Mail containing
    your question to acua_list@lists.ebbs.com.au