Etherdrivers Administrator's Guide

Version 1.0.8
Garrett D'Amore
Copyright 2002-2006

Table of Contents

About This Book Chapter 1 - Before You Begin Chapter 2 - Installation Chapter 3 - Configuring Your Ethernet Device Chapter 4 - Diagnostics and Troubleshooting Appendix A - Software License

Appendix B - Frequently Asked Questions

About This Book

This book describes installing, configuring, and troubleshooting the afe and mxfe ethernet drivers for SolarisTM platforms.

These ethernet drivers support a number of low-cost PCI-based fast ethernet controllers, which are used in quite a variety of network cards and on-board network interfaces. Specifically, these drivers support devices based on the ADMtek Centaur and Comet controllers, the Macronix 98715 family, and the Lite-On PNIC-II controllers.

Intended Audience

This book is intended for system administrators administering ethernet devices. You should be familiar with basic Solaris system administration. If you do not have these skills, you may wish to ask a more experienced system administrator for assistance. There are also numerous classes offered throughout the world that can help with this.

In order to perform the tasks outlined in this document, you must have root privileges for your system.

Typographic Conventions

The following table lists the typographic conventions used in this manual.

AaBbCc123On-screen output, commands, files and directories.Use showrev -p to list the patches on your system.
AaBbCc123User input as typed exactly in on-screen output and examples.csh% pkginfo
AaBbCc12Variable text, used in examples for text that should be replaced with a real value.csh% cd directory


I welcome feedback regarding this document, and the software which it documents, in the hope that the end product will be improved. Please send your comments to me at <>.


Copyright © 2002 - 2006 Garrett D'Amore, <>.

All rights reserved. Redistribution and use in source, binary, and printed forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions in any form must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Neither the name of the author nor the names of any co-contributors may be used to endorse or promote products derived from this software without specific prior written permission.




Sun, Sun Microsystems, SolarisTM, and are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. SPARC® and UltraSPARC® are registered trademarks of SPARC International, Inc. Intel® is a registered trademark of Intel Corporation. AMD is a trademark of Advanced Micro Devices, Inc. Other marks are the property of their respective owners.

Chapter 1 - Before You Begin

System Requirements

This software requires Solaris 7 or newer on Intel and compatible processors, or Solaris 8 or newer running on SPARC processors. In order to use IPv6, you will need to use Solaris 8 or newer. This version also includes support for 64-bit operation on AMD64 and SPARCv9 ISAs, if a suitable version of Solaris is installed.

Solaris 8 users on SPARC will require patch 109202-01 or newer. This patch is available from This patch is included with Solaris 8 10/00 and newer.

You must also have a device which is supported by these drivers, which can be either a PCI card, CardBus card, or an on-board device. The most up-to-date list of supported devices can be found on-line at

If the device is not built in to your system, you will need an available compatible slot for the card. Typically this means a bus-mastering capable PCI slot. On modern systems, almost any PCI slot will meet this requirement. (At the time of this writing, the author is unaware of any modern system with PCI slots that do not meet this requirement.)

There may also be specific requirements for voltage -- most older systems support 5 volt operation, but some newer ones may have 3.3V slots. (PCI 2.3 emoved support for 5V operation from the standard.) Additionally, most older network cards are 5V, while some newer ones support either 3.3V or 5V operation. Generally, the PCI connectors are keyed so that it is impossible to insert a device into a slot that doesn't support the voltage requirements of the card. You should check with your system and network card manufacturer if you need more assistance in determining compatibility.

CardBus slots are available on some systems from Tadpole Computer, and Tadpole includes software which makes the CardBus slots behave as if they were PCI slots (when 32-bit PC cards are inserted.) As a result, it is possible to use these drivers with certain 32-bit PC cards on these systems.

Mobile systems from other vendors may have CardBus slots, but may not have the necessary software drivers. (At the time of this writing, Sun does not provide a CardBus compatible software stack with Solaris.) Check with your system vendor for more information.
These drivers do not support removal of CardBus devices while they are in use; removing a CardBus device while it is in use will probably crash your system.

See the manuals that came with your system for information about the slots in your particular system.

You will also need an ethernet network with which to connect. This can be in the form of a hub, switch, bridge, or direct connection to another computer using an ethernet cross-over cable. If you need help, you should contact your network administrator.

Additionally, you will need to know the configuration parameters for your network (IP address, hostname, netmask, default router, and DNS servers if appropriate). You should contact your network administrator to obtain these parameters for your system if you do not already know them.

You will need to use root privileges in order to complete the tasks in this manual, so you must be in possession of the root password, or have equivalent access.

Finally, you will also need a small amount of disk space on your root disk in order to complete the installation. The recommended minimum free space is 10 megabytes.

Chapter 2 - Installation

This chapter describes installing the software for the ethernet device drivers.

Downloading the Software

In order to install the software, you must first obtain it. Fortunately, the device drivers you will need are freely available on the Internet at the URL

There are several different files you can download. Typically you will want to pick up one of either the etherdrivers- or files. You can also grab the source code, which is located in a file named etherdrivers-version In all these cases, version refers to the latest version, which at the time of this writing was 1.0.8.

There may be older releases of the software available on the web site as well. Since these probably have bugs that have been fixed in later releases, you are encouraged to stick with the latest release.

Uncompressing the Package

Now that you have got the software, you should unzip(1) it in an appropriate scratch directory. The following example shows this being done for version 1.0.8 on SPARC.

csh% cp /var/tmp
csh% cd /var/tmp
csh% unzip
csh% cd etherdrivers-1.0.8

Installing the Packages

Before you can install the software, you must become the superuser (for example by using the su(1M) command.)

csh% su

The next step is to install the software packages. This is done by executing the pkgadd(1M) command, as shown below:

# pkgadd -d Packages/arch all

The arch is assumed to refer to sparc or i386. You can determine the correct value by executing the following command:

csh% uname -p

You may be asked to answer additional questions, if pkgadd determines that it needs more information. See the pkgadd(1M) or admin(4) manual pages for information about this.

Checking your Installation

After software is installed, you should check the installation to make sure that the system has recognized the device driver, as well as any associated devices.

The simplest way to do this is to run the diagnostic utility to identify the devices that are present in the system. Do this by executing the etherdiag(1M) utility, as shown in the following example:

root# /opt/GEDnet/bin/etherdiag
Interface: afe0
Model: Accton EN5251
Speed: 100 Mbps
Duplex: full
Media: twpair
Ethernet Address: 0:0:e8:0:0:8f

At this point the software is installed properly, but the device has not been configured for use with any network protocols. The next chapter will explain how to configure the device so that you can use it.

Updating Your Shell Settings

The diagnostic software and manual pages are installed under /opt/GEDnet/bin and /opt/GEDnet/man. You may wish to modify your shell settings appropriately. The following example displays this for csh(1) users.

csh% setenv PATH ${PATH}:/opt/GEDnet/bin
csh% setenv MANPATH ${MANPATH}:/opt/GEDnet/man

This will make the commands and manual pages available in your environment without needing to specify the full path. For example, the manual page for the driver can be read using the following command:

csh% man afe

See the manual page for man(1) for more information.

Removing the Software

If you want to remove the software, you must first ensure that the device is not currently in use. Typically, you must do this by removing any interface configuration files you created for the interface (such as /etc/hostname.interface ). You may need to also edit configuration files, for example to modify default routes, etc.

For a full discussion of network configuration, or (in this case) unconfiguration, please refer to the Solaris 8 System Administration Guide, Volume 3.

Once you have deconfigured the interface, you can safely remove the software. This is easily done by executing the following command:

# pkgrm GEDenetu GEDenetd GEDenetm

You will need to answer 'y' to certain prompts in order to proceed. After this is complete, the software will have been removed from your system. You may need to reboot to remove the drivers from memory, however.

Chapter 3 - Configuring Your Ethernet Device

This chapter describes the steps to configure your device for use in a network.

Configuring for IPv4 with Fixed Address

To configure for a fixed IPv4 address, you must place the IP address of your network in /etc/hostname. interface, where interface is the name of the interface to use, such as afe0. The following example shows this, for a system that wishes to use the IP address (Replace with your real IP address.)

# echo > /etc/hostname.afe0

The interface will now automatically be configured the next time the system boots. To configure the interface for immediate use, without rebooting, the the ifconfig(1M) command can be used. Note that you must first "plumb" the interface using a command of the following form:

# ifconfig interface plumb

Until the interface is plumbed in this fashion, it will not display in the list of available interfaces (with the ifconfig -a command.)

Note that this is only the first part of network configuration. You may have to edit several other files, such as /etc/hosts, /etc/resolv.conf, /etc/netmasks, and /etc/defaultrouter to properly configure your network.

The generalities of network configuration on Solaris are well documented in the Solaris 8 System Administration Guide, Volume 3 , which can be accessed on-line at

Configuring for IPv4 with DHCP

To set up your ethernet device to act as a client for DHCP (Dynamic Host Configuration Protocol) you must create an empty file /etc/hostname.interface.

You must also then create a file /etc/dhcp. interface. This file should contain the word primary if the interface is your primary (or only) network interface. This will cause DHCP to be used to set the hostname, default route, and other global parameters for the system, in addition to the interface-specific configuration.

If the file is empty, then DHCP is only used to configure the interface and global parameters such as the hostname will not be adjusted.

The following example shows how to enable the interface mxfe0 as the primary (and only) interface, using DHCP.

# touch /etc/hostname.mxfe0
# echo primary > /etc/dhcp.mxfe0

Note that the configuration does not take effect until the next time the system is rebooted. The auto-dhcp sub-command of ifconfig can be used to configure the interface from DHCP without rebooting. (The interface must first be "plumbed" though.) The following example demonstrates use of ifconfig to configure afe1 via DHCP for temporary use without rebooting.

# ifconfig afe1 plumb auto-dhcp

See the ifconfig(1M) manual page for more information.

Configuring for IPv6 with Autoconfiguration

In IPv6, address autoconfiguration is commonly used to configure the address(es) that are used on a network interface. In most cases, static addresses will not be used with IPv6. To configure the device to use address autoconfiguration (for example, via the neighbor discovery protocol), all one needs to do is create an empty /etc/hostname6. interface file. For example, the following command enables IPv6 to be used with address autoconfiguration on the mxfe0 interface.

# touch /etc/hostname6.mxfe0

Similar to the IPv4 case, this does not take effect until the machine is rebooted. To configure an interface for IPv6 autoconfiguration temporarily, without rebooting, use a command similar to the following:

# ifconfig mxfe0 inet6 plumb up

Configuring for IPv6 with Static Addressing

Static addressing is much less likely to be used with IPv6, but it can still be done. With static IP addressing, one just needs to put the hostname or IPv6 address in the /etc/hostname6. interface file.

Again, a reboot is required for this to take effect. There is also an ifconfig command that can be used for this as well. It typically takes the form:

# ifconfig afe0 inet6 plumb addif 1234::5678/64 up

In the above address the address 1234::5678/64 was added to the afe0 interface. Please refer to the Solaris 8 System Administration Guide, Volume 3 for more information about IPv6 addressing.

Configuring for Use with Other Protocols

There are protocols besides IPv4 and IPv6 that can be used with ethernet. Some examples of these are Apple's AppleTalk and Novell's IPX/SPX protocols. These protocols should work fine with your new ethernet device. The details of configuring such protocols to use the ethernet device should be documented in your network protocol software documentation. You should be able to just replace the name of your interface (for example afe0) for the name of any other "standard" interface (for example hme0) to which the documentation might refer.

Note however while all this should work, it has not be tested for use with these drivers, so your results may vary. But it is hoped and believed that these drivers will function properly with any other Solaris networking software. The author would like very much to learn about any cases to the contrary.

Chapter 4 - Diagnostics and Troubleshooting

This chapter describes diagnostic and troubleshooting procedures for use with the ethernet device. Note that to use most of the commands in this chapter, you must run them as root.

Using the etherdiag(1M) Command

The etherdiag(1M) utility can be used to determine which devices are in your system along with other information about those devices, such as the ethernet address, manufacturer, link speed, and assorted other information. Normally it should be run without any options, to get a full listing for your system. Here is an example on one system:

root# /opt/GEDnet/bin/etherdiag
Interface: afe0
Model: Accton EN5251
Speed: 100 Mbps
Duplex: full
Media: twpair
Ethernet Address: 0:0:e8:0:0:8f

If you would like to obtain more information, merely add the verbose flag (-v) which, will cause the utility to display more information. If used twice, this flag causes even more output to be displayed. When submitting bug or problem reports, it is best to include the full (-v -v) output from this command.

See the etherdiag(1M) manual page for more options that can be used.

Using the snoop(1M) Command

Perhaps one of the most useful diagnostic utilities for network troubleshooting is the snoop(1M) utility which is bundled with Solaris. This utility can be used to watch packets traveling across the ethernet.

The snoop utility will cause your interface to run at reduced performance, so it isn't a good idea to leave it running for long periods of time, or whenever performance is critical.

To run snoop on a specific interface, use the -t device option. The example below shows snoop running on afe0:

# snoop -d afe0
Using device /dev/afe (promiscuous mode)

    doc-afe0 -> UDP D=64292 S=34614 LEN=104
    doc-afe0 -> UDP D=64292 S=34614 LEN=64 -> doc-afe0     UDP D=34614 S=64292 LEN=80
    doc-afe0 -> UDP D=64292 S=34614 LEN=876
    doc-afe0 -> UDP D=64292 S=34614 LEN=64

There are numerous other options for snoop, which allow disabling promiscuous mode, capturing packets to a file, and enabling more verbose display. Please read the manual page for more information about this useful utility.

Using the netstat(1M) Command

The netstat command is useful for monitoring various information regarding the IP stack on your machine. This utility is complex, and is not covered fully here, but the -i option can be useful to give an overview of the interfaces on your system.

The following example is taken from a system with two network interfaces, one of which is the stock eri0 supplied with the system, and one of which is the afe0 device which was added in afterwards. The lo0 interface is not a real network interface, but is an internal software loopback.

# netstat -i
Name  Mtu  Net/Dest      Address        Ipkts  Ierrs Opkts  Oerrs Collis Queue
lo0   8232 loopback      localhost      4991935 0     4991935 0     0      0
eri0  1500 doc           doc            2835250 1     3652228 298   0      0
afe0  1500 doc-afe0      doc-afe0       1491228 0     5605143 45    0      0

Getting Statistics with kstat(1M)

These device drivers maintain a number of statistics, which can be useful in determining a number of things about the device. The simplest way to view these statistics (on Solaris 8 and later) is with the kstat(1M) command. Here is an example for mxfe1. Note the colon (:) separating mxfe (the driver) from 1 (the PPA, or device instance.)

# kstat mxfe:1 
module: mxfe                            instance: 1     
name:   mxfe1                           class:    net                           
        align_errors                    0
        blocked                         0
        brdcstrcv                       87
        brdcstxmt                       1911
        carrier_errors                  45
        collisions                      0
        crtime                          1815247.75130736
        defer_xmts                      0
        duplex                          full
        ex_collisions                   0
        fcs_errors                      0
        first_collisions                0
        ierrors                         0
        ifspeed                         100000000
        intr                            1869597
        ipackets                        1488584
        ipackets64                      1488584
        macrcv_errors                   0
        macxmt_errors                   45
        media                           twpair
        missed                          0
        multi_collisions                0
        multircv                        0
        multixmt                        30405
        norcvbuf                        0
        noxmtbuf                        0
        obytes                          750185937
        obytes64                        5045153233
        oerrors                         45
        oflo                            0
        opackets                        5602789
        opackets64                      5602789
        promisc                         off
        rbytes                          162676612
        rbytes64                        162676612
        rcv_badinterp                   0
        runt_errors                     0
        snaptime                        2423664.10711802
        sqe_errors                      45
        toolong_errors                  0
        tx_late_collisions              0
        uflo                            0
        unknowns                        24
        xmt_badinterp                   0
        xmtretry                        921895

A full discussion of the meaning of the statistics is not given here. You should contact the author if you have specific questions about any of these values.

Verifying Connectivity with the ping(1M) Command

The ping(1M) command can be used to verify connectivity between two systems. Typically this command is run with a single option, which is the hostname or IP address to which you want to verify connectivity.

This causes an ICMP (Internet Control Message Protocol) ECHO packet to be sent to the specified host or IP address, which will normally send a response packet back to the originating machine.

Many sites restrict ICMP packets using firewalls. In such a case ping will not function correctly, even if normal traffic would otherwise get through. Ask your network administrator for help if you believe this is the case at your site.

The following demonstrates a test of connectivity to the site:

% ping is alive

Note that unlike most of the other diagnostics presented in this chapter, ping can be run without root privileges.

Appendix A - Software License

The software documented by this manual is covered under the following terms:

Copyright © 2001-2006 by Garrett D'Amore <>. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the author nor the names of any co-contributors may be used to endorse or promote products derived from this software without specific prior written permission.


Appendix B - Frequently Asked Questions

  1. I installed the software, but I can't see my device.
    This usually stems from failing to follow the documented procedures correctly. The most common error is to attempt to configure or see the device with ifconfig, without first "plumbing" it, as described in Chapter 3. Also, make sure your device is on the supported devices list.

  2. Why won't my interface negotiate for full duplex?
    A common misunderstanding is that all devices can operate in full-duplex mode. While most NICs, and most switches are capable of full-duplex operation, hubs are generally not able to operate in full-duplex mode. If you are connecting to a hub, half-duplex operation is normal.

    Also, make sure that if you are connecting to a switch, that you have enabled autoconfiguration (sometimes called auto-sense) on the port.

  3. Can I use this for diskless client or install Solaris (jumpstart) over it?
    No. On SPARC, network boot requires an FCode PROM, which is absent from most or all NICs produced for the commodity PC market. On x86 platforms, a real mode driver is required, and one has not been written yet. If you'd like to volunteer to write a real mode driver, please contact the author.

  4. Will this work with Solaris 7 or older on SPARC?
    No, SPARC platforms require Solaris 8. Changing this would be non-trivial, since there is no GLD for Solaris 7 or older on SPARC.

  5. Will this work with Solaris 2.6 or older on Intel?
    No. Changing this would be non-trivial, since there were substantial changes to the GLD in Solaris 7. (These changes give drivers based on the GLDv2, such as these, much better performance.)

  6. I really like this software. How can I donate to the author?
    The author greatly appreciates any donations which might help fund continued development efforts. A donation of $5 (five US dollars) per station using these drivers is recommended, but any donation is gratefully accepted, and none is obligatory. The author has an account with PayPal, so you can donate that way. The easiest way to do this is to click the appropriate link on the home page for these drivers at