Sun PPPoE on Solaris

This page is written slightly differently from my RP-PPPoE on Solaris page. There is a lot of documentation for RP-PPPoE, so that page is mostly a complement to that documentation. However, since documentation for Sun PPPoE is scattered and somewhat sparse, this will attempt to be more comprehensive.

HOW TO GET SUN PPPoE
Sun PPPoE is part of Sun's PPPD 4.0 package. This is available in the 10/01 version of Solaris 8 (not the MU), and it's also available in Solaris 9. If you are running something earlier than Solaris 8 10/01 (MU6) then you do NOT have Sun PPPoE. You have must upgrade (download/order an updated CD - the MUs won't do it), or try using Roaring Pengiun PPPoE.


INSTALLING PPPD 4.0
If you are using a MU to install, you'll need to make sure you already have all of the SUNWpppd* packages installed before running the MU. Otherwise the MU won't update them.

If you have the 10/01 CD's then install the following packages:
SUNWpppd - Solaris PPP Device Drivers
SUNWpppdr - Solaris PPP configuration files
SUNWpppdt - Solaris PPP Tunneling
SUNWpppdu - Solaris PPP daemon and utilities
SUNWpppdx - Solaris PPP 64-bit (ONLY needed for SPARC's with 64-bit kernels)

This can be accomplished by going into the appropriate directory on the Software 2 CD under Solaris_8/Product/ and typing:
pkgadd -d . package_name

Now the software is installed. You'll want to reboot and reconfigure but first create a file called /etc/ppp/pppoe.if and put the interface you intend to run pppoe over in it. You don't need to include the "/dev/" so if you want to use iprb0 just have the file say exactly that and nothing more. This is so that when you reboot the pppd init script will know what interface to setup for pppoe (more on this later).

Now you'll want to reboot and have Solaris reconfigure /dev an /devices. To do this:
touch /reconfigure
shutdown -i6 -g0 -y


Once your system is back up do an:
ls /dev | grep ppp

and check to make sure that sppp and sppptun are there. If they are, you're set to move on! If not, make sure that the package installations added the information to your /etc/name_to_major file:
grep sppp /etc/name_to_major

should give you:
sppp 146
sppptun 147


Note: if you are using SPARC these would be 187 and 236 respectively. Note that these are usually the numbers, but your numbers may differ for various reasons. If you have different numbers, don't worry. If these entries are there, try reconfiguring again. If they are not there, then reinstall the packages.


THE TOOLS
There are a variety of tools you get when you install the above packages. They are:

/usr/lib/inet/pppoec
This is the pppoe chat executable. When things are working, you won't use this directly, pppd will. But it can be very helpful in setting up and troubleshooting.

/usr/lib/inet/pppoed
This you will never use. This is for setting up a PPPoE Server.

/usr/sbin/sppptun
This is used for plumbing interfaces with the pppoe and pppoed protocols. Note that pppoed here is NOT the same thing as pppoed above. You need both of these protocols. Pppoe is the "Session Stage" while pppoed is the "Discovery Stage."

/usr/bin/pppd
This is the PPP Daemon that will actually use the above executables to get you in the right place.



GETTING CONFIGURED
  1. Configuration files
    Now you need to setup a few configuration files. You're going to make a file with information about your connection. I will put isp in italics when I reference the filename, but you should make the file name resemble your ISP. So, open a file called /etc/ppp/peers/isp. In that file you want to put something along the lines of:
    
    sppptun 					# what device to use
    plugin pppoe.so					# initialize the
    connect "/usr/lib/inet/pppoec INTERFACE"	# connect string
    persist						# if the connection dies, bring it back up
    user "USERNAME"					# username
    noauth						# Do not make the other side authenticate itself
    noipdefault					# Let them give you what IP they want to give you
    noccp						# No compression
    novj						# No compression
    noaccomp					# No compression
    nopcomp						# No compression
    defaultroute					# add an appropriate default route
    
    Where USERNAME is the username for your DSL connection, and INTERFACE is whatever interface you are using (such as hme0 or iprb0). The options above are commented. The "No compression" ones are there because ISP's almost never support such compressions and disabling them all here will prevent the compression module (spppcomp) from being put in the stream and should therefore improve performance. There are a ton of other options that can go in this file. Pretty much anything that you can pass directly to pppd on the command line can be put in your peers file. Check the pppd man page for more info.

    Now you need to give it your password. Your ISP may use CHAP or PAP for authentication. As far as your concerned the only difference is what file you put your username and password in. There should already be a file called /etc/ppp/chap-secrets. Ensure that this is NOT world readable (and infact it should have perms 0600), because you're going to put your password in it. Now, open the file, and add a line like this:
    
    "USERNAME"		*		"PASSWORD"

    Again here, USERNAME is the username for your DSL connection and PASSWORD is the password for your DSL connection. Note that there must be tabs in between those fields, not spaces. Now do the same thing for /etc/ppp/pap-secrets. Note: If you know which authentication your ISP users, feel free to only create the appropriate file. However, if you don't know, having both files does no harm.

  2. Checking your work and getting the connection up.
    Alright, you're almost done. Now, you need to make sure both the pppoe and pppoed protocols are on your network card. So do
    sppptun query

    If you see something like:
    INTERFACE:pppoe
    INTERFACE:pppoed


    You're all set to go. If you do not see that, then the init script did not plumb those interfaces (did you create/etc/ppp/pppoe.if before you rebooted?). So assuming you've created the /etc/ppp/pppoe.if file, you can run /etc/init.d/pppd start or you can do it manually via:
    sppptun plumb pppoed INTERFACE
    sppptun plumb pppoe INTERFACE


    Where INTERFACE is whatever interface you want to use. Note that you should normally not have to run sppptun manually, the pppd init script should take care of this plumbing on boot. Now you should be redy to go.

    To double check that you've set everything up right, we can use the pppoec tool. With it's -i option we can have it tell us what services are available on the line:
    pppoec -i INTERFACE

    And you should see a line that has various information about your ISP. If not, check the troubleshooting section.

    Alright, so now your ready to bring the link up! Go ahead and type:
    /usr/bin/pppd call isp

    Where isp is whatever you called your file in /etc/ppp/peers. Wait a second and you should be able to see your new sppp0 interface with an ifconfig -a.

    Please remember to update any firewall rulesets you may have to use the new sppp0 interface name. See the section on that below.

  3. Getting the connection to come up on boot.
    There are multiple ways to have your connection come up at boot time. Unfortunately the pppd boot script does not handle this for you. I've been told there should be a better way to handle this in upcoming releases. Until then, the best thing to do is to create a suplimental init script of your own to bring the link up. Create a file called /etc/init.d/ppplink and put this in it:
    
    #!/sbin/sh
    #
    # This script compliments the Sun script /etc/init.d/pppd
    # It goes the rest of the way and brings the link up.
    # Written by Phil Dibowitz.
    #
    # This script is provided AS-IS. No warantee of ANY kind implied
    # or stated. Use at your own risk.
    #
    
    
    case "$1" in
    'start')
            if [ ! -x /usr/bin/pppd -o ! -c /dev/sppp ] ; then
                    # User probably just received the warning
                    # From Sun's pppd script, don't bother them more
                    exit 1
            fi
            if [ -s /usr/sbin/sppptun -a -f /etc/ppp/pppoe.if ] ; then
                    # If same conditions are satisfied
                    # Bring up the link
                    /usr/bin/pppd call isp
            fi
            ;;
    
    'stop')
            echo "Taking down PPP link..."
            /usr/bin/pkill -x pppd
            echo "done"
            ;;
    
    *)
            echo "Usage: $0 { start | stop }"
            exit 1
            ;;
    
    esac
    exit 0
    
    Make sure to replace isp with whatever you called your file in /etc/ppp/peers. You may of course want to change the script to suit your needs, but this should do for most users. I use this myself. Next, give it the right owner, group and permissions:
    chmod 744 ppplink
    chown root:sys ppplink


    Now, this file won't yet do anything, so we'll want to symlink it to the appropriate rc directory like this:
    cd /etc/rc2.d
    ln -s ../init.d/ppplink S48ppplink


    I actually made mine S64 to make sure I don't accidentally put anything between that and the IP Filter script (if you don't use IP Filter, ignore this sentence), but I'll leave as one after the pppd script and let people modify that as they see fit. There is no need to create a K?? symlink for this script since the /etc/rc0.d/K50pppd script that Sun provides will bring down the connection for you.

    You could alternatively modify the pppd init script, but this is not recommended since you will loose your change on the next time the package is updated.

  4. Handling your firewall with PPPD.
    If you have only a single connection, it should suffice to change your rulesets to reflect your new interface name.

    However, you also have the option to use /etc/ppp/ip-up to setup your firewall rules. In that script $1 will be replaced with the interface name.

    For example, if you use IP Filter, and you wanted to use this method, you might put:
    #!/bin/sh
    ( cat <<EOF
    block in on $1 ipopts
    block in on $1 udp port 137 <> 139
    ...
    EOF
    ) | ipf -f -


    in your /etc/ppp/ip-up and put something like:
    ipfstat -io | grep " on $1 " | ipf -rf -

    in your /etc/ppp/ip-down.

    If you have multiple links however, you may not be able to just edit your rulesets with sppp0, sppp1, etc. This is because the links may not always come up in the same order, and thus may not always have the same name. There are two solutions to this problem. One is to use /etc/ppp/ip-up and /etc/ppp/ip-down to set your rules as described above. The other option, if you want to keep your ruleset where it is, you can use the unit option in your peers file. So if you have three links, you may have three peer files, isp0, isp1, and isp2. In the peer files you would specify unit 0, unit 1, and unit 2 respectively. This would ensure that the link specified by isp0 was always sppp0, the link specified by isp1 was sppp1 and so on...

TROUBLESHOOTING
The first thing to do if you are having problems is to turn on debuging. Edit /etc/ppp/peers/isp and change:
connect "/usr/lib/inet/pppoec INTERFACE"

to:
connect "/usr/lib/inet/pppoec -v INTERFACE"

and add a line at the end of the file that simply says:
debug

Now, make sure to kill of any running pppd's that you may have started:
pkill pppd

Now when you run pppd again, you should be able to watch /etc/ppp/connect-errors to see what happens when you attempt to connect. This should help you track down the problem. I've also included a few problems that I ran into, including a known bug in Sun PPPoE.

  1. I get unrecognized option 'sppptun' (in /etc/ppp/connect-errors) when I try to connect.

    This means there is no /dev/sppptun. You need to reboot with a reconfigure. Either touch /reconfigure before you reboot, or use the -r option at the OBP (SPARC) or boot options screen (Intel).

  2. I get PPPTUN_SCTL INTERFACE:pppoed: No such process when I try to connect.

    This means that your interface wasn't plumbed with pppoed via sppptun. This usually happens at boot through the /etc/rc2.d/S47pppd script if you have the interface you want listed in /etc/ppp/pppoe.if. However, you can do it manually via:
    sppptun plumb pppoed INTERFACE

    Note: If you're error message refers to pppoe substitute that for pppoed in the above command.

  3. Everything seems to be setup right. /usr/lib/inet/pppoec -i INTERFACE shows seemingly valid information, by connect-errors shows a lot of connecting information, but then says that it failed.

    This may be because your ISP does not support "wildcard" service. In this case what you need to do is first look at the output of /usr/lib/inet/pppoec -i INTEFACE. There should be something that says Svc and then has the name of your service there (for example: Svc:"myisp.com"). If you have more than one Svc section that's ok, just pick one, usually the first will do. Add whatever that name is to your /etc/ppp/peers/isp file by changing:
    connect "/usr/lib/inet/pppoec INTERFACE"

    to:
    connect "/usr/lib/inet/pppoec INTERFACE SVC_NAME"

    Where SVC_NAME is the name in quotes after Svc (in the above example it would be myisp.com). This is a known bug in PPPoE (the fact that Sun PPPoE doesn't notice the problem, and send the service name by itself). I've been told by Sun that this should be fixed very soon.

  4. When I run /etc/init.d/pppd stop the link goes down but it doesn't unplumb the pppoe and pppoed like it's supposed to.

    This is because the first thing run when you run /etc/init.d/pppd stop is pkill -x pppd which will kill any and all processes with the name pppd... but the script your running (/etc/init.d/pppd) has that name, so not only does the ppp daemon die, but the script also kills itself! Thus it never moves on to do the other things it is supposed to do. To get around this use /etc/rc0.d/K50pppd stop.

  5. I'm having problems with ifconfig modinsert on the PPP link.

    When using ifconfig modinsert with the PPP link you need to specify the plink option. Most people should be able to ignore this question, but certain applications such as Sun Bandwidth Manager and SunScreen may require this.

  6. NAT'd machines behind my Solaris box can't access some websites.

    I have a whole other page on this here.

EXTRA SPECIAL THANKS
I want to extend a very special thanks to Greg and James Carlson at Sun for all of their help.


Last Updated: 03/03/02

This page is © Phil Dibowitz 2001 - 2004