| Solaris 8 users on SPARC will require patch 109202-01 or newer. This patch is available from http://sunsolve.sun.com/. This patch is included with Solaris 8 10/00 and newer. |
|---|
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.
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.
The following table lists the typographic conventions used in this manual.
| Typeface | Meaning | Example |
|---|---|---|
| AaBbCc123 | On-screen output, commands, files and directories. | Use showrev -p to list the patches on your system. |
| AaBbCc123 | User input as typed exactly in on-screen output and examples. | csh% pkginfo |
| AaBbCc12 | Variable 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 < garrett@damore.org>.
Copyright © 2002 - 2006 Garrett D'Amore, < garrett@damore.org>.
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:
THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
Sun, Sun Microsystems, SolarisTM, and docs.sun.com 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.
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 http://sunsolve.sun.com/. 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 http://sol-net.sourceforge.net/support.shtml
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.This chapter describes installing the software for the ethernet device drivers.
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 http://sol-enet.sourceforge.net/.
There are several different files you can download. Typically you will want to pick up one of either the etherdrivers- version-sparc.zip or etherdrivers-version-i386.zip files. You can also grab the source code, which is located in a file named etherdrivers-version -src.zip. 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.
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 etherdrivers-1.0.8-sparc.zip /var/tmp csh% cd /var/tmp csh% unzip etherdrivers-1.0.8-sparc.zip csh% cd etherdrivers-1.0.8 |
Before you can install the software, you must become the superuser (for example by using the su(1M) command.)
csh% su Password: # |
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.
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.
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.
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.
This chapter describes the steps to configure your device for use in a network.
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 192.168.128.101. (Replace with your real IP address.)
# echo 192.168.128.101 > /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 http://docs.sun.com/.
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.
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 |
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.
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.
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.
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.
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 -> 192.168.128.209 UDP D=64292 S=34614 LEN=104
doc-afe0 -> 192.168.128.209 UDP D=64292 S=34614 LEN=64
192.168.128.209 -> doc-afe0 UDP D=34614 S=64292 LEN=80
doc-afe0 -> 192.168.128.209 UDP D=64292 S=34614 LEN=876
doc-afe0 -> 192.168.128.209 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.
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 |
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.
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 www.whitehouse.gov site:
% ping www.whitehouse.gov www.whitehouse.gov is alive |
Note that unlike most of the other diagnostics presented in this chapter, ping can be run without root privileges.
The software documented by this manual is covered under the following terms:
Copyright © 2001-2006 by Garrett D'Amore < garrett@damore.org>. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.