Update to v30-pre9

[android-x86/external-wireless-tools.git] / wireless_tools / HOTPLUG-UDEV.txt

                Sane network interface management with Hotplug or uDev
                ------------------------------------------------------

INTRODUCTION
------------
        In the old days all wireless cards were managed by the
excellent Pcmcia subsystem and its rich configuration scripts, and
life was good. Then came the wireless PCI cards, then the wireless
USB dongles. Some unification was needed, and rather than adapt the
Pcmcia subsystem for PCI and USB, it was decided to create the much
simpler Hotplug system.
        The USB subsystem already uses Hotplug. The Pcmcia subsystem
is migrating to it : CardBus cards (32 bits) already use Hotplug,
whereas Pcmcia cards (16 bits) often still use the old Pcmcia scripts.
        The Hotplug system is now very mature. Most users comming from
the old Pcmcia scripts are disappointed at first by its apparent lack
of features, however it is very flexible and powerful. The new uDev
system depend on Hotplug and integrates tightly with it.
        In this document, we will show how to fully exploit the
Hotplug system and try to implement the equivalent of all the
functionality of the Pcmcia scripts.


ASSUMPTIONS
-----------
        The target audience of this document is mostly power users and
distribution maintainers, but it should give enough clues to help
newbies. You should have read and understood DISTRIBUTIONS.txt. The
procedures described here are more advanced than the simple
configuration described in DISTRIBUTIONS.txt.
        The main focus is of course on removable wireless interfaces,
but we will to talk about network interface management in general, so
this should apply also to built-in Ethernet cards.


PROBLEM STATEMENT
-----------------
        Let's assume a Linux system and two or more network devices,
Device A and Device B. Those devices may be built-in or removable,
they may be present or absent from the system at any time, and they
may activated in any particular order.
        The user wants to assign Configuration A to Device A and
Configuration B to Device B, without the possibility that Device A
gets assigned Configuration B.
        Different users may have different definitions of what is
Device A. For some, it's a specific instance of a specific hardware,
for others any hardware that meets some criteria (a wireless card, an
Ethernet card).
        The user may also want to have multiple configurations for a
given device such that the chosen configuration depends on various
factors, just as with the old Pcmcia schemes. Device A may need
Configuration A1 or Configuration A2 depending on those factors.
        By default, all network interfaces are created using default
interface names (starting at "eth0" and going up). I call that the
"all my cards are eth0" problem : im most distributions, "eth0" points
to a single fixed configuration in the configuration
database. Clearly, this won't satisfy our requirements.


EXAMPLE SYSTEM
--------------
        The distribution I use is Debian 3.0, and some parts of what I
say here will be specific to it. However, it should be easy to
translate this material to other distributions and I welcome additions
to this document.

        The example system is as follows :
                o Linux 2.6.X SMP kernel with hotplug support
                o Fully modular system (all network drivers as modules)
                o PCI Ethernet card : AMD PCnet LANCE (pcnet32 - eth4)
                o PCI Ethernet card : HP 100VG J2585B (hp100 - eth2)
                o ISA Wireless card : Old AT&T Wavelan (wavelan - eth3)
                o ISA-Pcmcia bridge : VADEM VG-469 (i82365 - slot 0)
                o PCI-CardBus bridge : Ricoh RL5c475 (yenta_socket - slot 2)
                o Pcmcia 802.11 card : Aironet 350 (airo_cs - eth0)
                o Pcmcia 802.11 card : Lucent Orinoco (orinoco_cs - eth0)
                o CardBus 802.11 card : SMC 2835W (prism54 - prism0)

        This system just happens to be my Linux development box. It
has enough interfaces to make it interesting. All the examples I
present in this document are extracted from this system.


BASIC CONCEPTS
--------------
        Most of the concept and tricks presented here are not really
new. The main contribution is to integrate them.

        1) Removable network interfaces are managed by Hotplug
(Pcmcia, CardBus, USB...). We can't assume that those interfaces are
always present in this system and available at boot time (Pcmcia cards
were not made to be soldered in the Pcmcia slot). Therefore Hotplug is
the way to go.
        2) The Hotplug system can use either the original Hotplug
scripts or the uDev daemon with the uDev scripts.
        3) Built-in PCI and ISA cards are managed by the init scripts,
as they have always been. The ISA subsystem will never have Hotplug
support, and hotplug is not necessary for PCI cards.
        4) Built-in devices that are disable most of the time should
be enabled manually by the user. Therefore both Hotplug and the init
scripts should ignore those devices by default.
        5) (1), (3) and (4) must be compatible on the same system and
play nice with each other.

        6) A well defined and consistent network interface name is
assigned to each network hardware interface using 'ifrename'. Device A
is always named 'ethA' (or whatever name you like such as
'mynetworkcard').
        7) No interface is called 'eth0' (or 'wlan0'). Any unknown
device would be 'eth0', so known devices should be called something
else. There are also other issues with using 'eth0'.
        8) Multiple configurations for a single interface (schemes)
are managed by the ifup/ifdown subsystem.


CONFIGURATION FROM INIT SCRIPTS
-------------------------------
        It may seem paradoxical, but before setting up Hotplug, we
need to make sure that the initialisation of network cards via init
scripts is done properly and doesn't get in the way of the Hotplug
subsystem.
        The configuration of network cards via init scripts is the
traditional way networking is initialised in Linux. The advantage of
this method is that it's very well documented and understood, and has
not changed much over the years. Unfortunately, it doesn't adequately
support removable cards.

        The init scripts perform the following 3 functions in order :
                1) Load necessary driver modules
                2) Rename interface to name chosen by the user
                3) Configure those network interfaces

        1) Applicability
        ----------------
        Configuration from init scripts is applicable to any built-in
network interface (ISA, PCI...), i.e., interfaces available at boot
time and that will never be removed from the system.
        The Hotplug subsystem also has the ability to configure some
of the built-in network interfaces, such as PCI cards. However, there
is a class of devices that will never have Hotplug support, such as
ISA and EISA cards.

        2) Loading driver modules (if/as needed)
        ----------------------------------------
        Most distributions build the kernel drivers as modules. This
modular setup allows to minimise the amount of memory used by the
system and the flexible loading/unloading of drivers.
        You can also compile your kernel with static drivers
(non-modular). In that case, the driver will always be available in
the kernel, you don't need to configure the module subsystem, so you
can skip directly to the next section.

        There are 3 alternatives to manage device drivers as
modules.
                1) Some distributions have an explicit list of modules
that are loaded at boot time, usuall in /etc/modules. If you want to
use that feature you need to check the documentation of your
distribution.
                2) Some system, such as Hotplug, Discover or Kudzu,
can scan the various buses of the PC and load the appropriate
drivers. This is mostly configuration-free, but may not support all
devices and may load unnecessary modules.
                3) The module subsystem also allows to load modules
'on-demand'. When an application try to access or configure a network
interface, the corresponding module is loaded.

        I personally prefer to use the 'on-demand' feature of the
module subsystem, as this allow you to not have to specify a static
list of modules that need to be loaded, and only modules really needed
are loaded which saves kernel memory. You can also choose which module
to load when there are multiple modules available that support your
hardware (which happens quite often).

        With kernel 2.6.X the module subsystem is configured in the
file /etc/modprobe.conf or files in the directory /etc/modprobe.d/. To
configure 'on-demand' module loading, on my test system I need to add
to the following lines to the configuration :

--------- /etc/modprobe.d/local or /etc/modprobe.conf ------
# HP 100VG J2585B PCI card
alias eth2 hp100

# AMD AMD PCnet LANCE PCI card
alias eth4 pcnet32

# Old AT&T Wavelan ISA card
alias eth3 wavelan
options wavelan io=0x390 irq=15
------------------------------------------------------------

        Your distribution may already have lines for your interfaces,
either replace these or make sure they are correct (some distributions
are notorious for picking the wrong driver name in some cases). This
file also contains configuration for lot of other subsystems,
obviously you don't want to touch that.
        In this file, you put the name you would like the interface to
have (we'll fix that in a minute). Note that for modern PCI cards this
is much more straightforward than for old ISA cards.

        When loading modules on-demand, you usually can not use the
name 'eth0' or other 'ethX' with a low number for your interfaces, as
on-demand module may fail to load them. If there is a unknown
interface or an interface not yet renamed on the system, it will be
eth0, and the system will assume the module for eth0 is already loaded
and will fail to load the proper module.
        To test on-demand loading of module, you can do :
--------------------------
> /sbin/modprobe -r eth2
> /sbin/modprobe eth2
--------------------------

        3) Installing 'ifrename'
        ------------------------
        You will need to install ifrename on your system. 'ifrename'
is part of the Wireless Tools package (version 27 and later) and is a
complete rewrite of the now obsolete 'nameif'.
        Some distributions, such as Debian 3.1/4.0, offer a separate
package for 'ifrename', and in this case you should just install this
package. Other distributions may include ifrename as part of their
'wireless-tools' package (this should be the case for Gentoo, Fedora
and Mandrake). Other distributions, such as Debian 3.0 and Unbuntu
7.10, don't include ifrename at all, so you should compile yourself a
recent version of Wireless Tools (v29 or later) and install it.
        The installation of Wireless Tools is described in the INSTALL
file of the Wireless Tools package. If you plan to only use ifrename,
a good option is to compile a static version of Wireless Tools and
only copy the resulting ifrename executable.

        In any case, you should verify that 'ifrename' is properly
installed and check the path needed to call it :
--------------------------
> which ifrename
/sbin/ifrename
> whereis ifrename
ifrename: /sbin/ifrename /usr/man/man8/ifrename.8 /usr/share/man/man8/ifrename.8.gz
--------------------------
        Most distributions will install 'ifrename' in '/sbin', while
if you compile your own wireless tools, by default it will be in
'/usr/local/sbin' (see Makefile on how to change that).
        If you are upgrading ifrename from a previous version, you
should make sure that the new version of ifrename is either installed
in the same location (overwrite old version) or in a place earlier in
the PATH (check with whereis).

        4) Making the boot scripts call 'ifrename'
        ------------------------------------------
        You need to make sure 'ifrename' is run at boot time. Most
distributions don't do that yet by default.
        This is a part that is distribution-specific, so you will need
to look into your own init files, or ask people familiar with your
distribution. It will need to run just before the call to 'ifup' or
'ifconfig' command.

        In Debian 4.0 (Etch) and later, the 'ifrename' package adds it
own init script at the right place, called /etc/init.d/ifrename. You
don't have to do anything.
        In Debian 3.0 (Woody) and Debian 3.1 (Sarge), ifrename needs
to be run from /etc/init.d/networking, which is not the default. The
necessary patch to the init script is below :

----------------------------------------------------------------
--- networking-orig     Wed Feb 18 13:56:23 2004
+++ networking  Fri Feb 20 14:51:06 2004
@@ -120,6 +120,15 @@ case "$1" in
         doopt syncookies no
         doopt ip_forward no

+       # Optionally remap interface names based on MAC address.
+       # '/sbin/ifrename' is part of wireless-tools package.
+       # /etc/iftab is currently not created by default. Jean II
+       if [ -x /sbin/ifrename ] && [ -r /etc/iftab ]; then
+           echo -n "Remapping network interfaces name: "
+           ifrename -p
+           echo "done."
+       fi
+
         echo -n "Configuring network interfaces: "
         ifup -a
        echo "done."
----------------------------------------------------------------
        Don't forget to set the appropriate path to the ifrename
command (see step (3) above).

        You may also want to also set the proper options for ifrename
(check the man page).
        The option '-p' enables module autoloading compatibility.
        The default version of 'ifrename' also includes some special
Debian support : using "ifrename -p -d", only the proper modules are
loaded. If you are using Debian, you should use this option.

        5) Renaming interfaces
        ----------------------
        As stated above, we use 'ifrename' to assign names to
interfaces.

        First, you need to get the MAC address of each of your
interfaces. You can read the MAC address on the label of the card, or
display it using the 'ifconfig -a' command. Remember that the
interface won't load yet with the proper name, so you may need to do a
bit looking around :

-----------------------------
# modprobe pcnet32
# ifconfig eth0
eth0      Link encap:Ethernet  HWaddr 00:10:83:34:BA:E5
[...]
-----------------------------

        The configuration of 'ifrename' is simple, you just specify
which name should be used for each MAC address in the file
/etc/iftab :

--------- /etc/iftab ------------------------
# HP 100VG J2585B PCI card
eth2            mac 08:00:09:*

# Old AT&T Wavelan ISA card
eth3            mac 08:00:0E:*

# AMD AMD PCnet LANCE PCI card
eth4            mac 00:10:83:*
---------------------------------------------

        The '*' in the MAC address is a wildcard and allows me to
replicate my configuration between multiple identical computers. If
you have to manage large number of computers (like a rack of servers
or clusters), then you may want to look at other selectors offered by
'ifrename'.

        In this example, we used the MAC address of the card. Using
the MAC address is not always an option, there is a section at the end
of this document dedicated to those cases.

        To test that ifrename works, do the following :
                o Load all your drivers, see section (2)
                o Check /proc/net/dev to see which interface exist
                o Bring all interfaces down : ifconfig ethX down
                o Run ifrename
                o Check each interface with ifconfig
                o Bring all interfaces up : ifconfig ethX up

        6) Configuring interfaces
        -------------------------
        Most likely, your distribution is already doing this part
properly. Just assign the proper IP and wireless configuration to each
of the interface names you have chosen.
        This part is distribution specific, and I already document it
in the file DISTRIBUTIONS.txt.

        In Debian, you would need to modify the file
/etc/network/interfaces so that it looks something like this :

--------- /etc/network/interfaces -----------
# AMD PCnet LANCE PCI card
auto eth4
iface eth4 inet dhcp

# HP 100VG J2585B PCI card
auto eth2
iface eth2 inet static
    address 10.0.0.2
    netmask 255.255.255.0
    broadcast 10.0.0.255
    gateway 10.0.0.1
---------------------------------------------

        This was the last part. Now, at your next boot, all your
interfaces should be assigned the proper name and the proper
configuration.
        If this is not the case, there is a troubleshooting section at
the end of this document.


CONFIGURATION VIA UDEV
----------------------
        Dealing with removable interfaces is similar to dealing with
built-in interfaces, the main difference is that we will use Hotplug
event with the uDev system instead of the init scripts. This requires
a fairly recent distributions, older distributions don't have uDev or
uDev system not capable enough.
        Note that you can also use removable interfaces with the
original Hotplug scripts. This is detailed in the next section. The
installation of uDev changes a lot of things on a system, so may not
be for everybody, however recent version of Gnome and KDE seem to
require it.

        1) Applicability
        ----------------
        The Hotplug configuration method is the best choice for any
removable network interface, such as :
                o Pcmcia (16 bits) network cards
                o CardBus (32 bits) network cards
                o USB network dongles
                o Hot-PCI network cards
        It may also be used to manage other types of network
interfaces, although it may not be the best choice for them.

        2) How Hotplug works with the uDev scripts
        ------------------------------------------
        When using uDev, the concept is similar to the original
Hotplug scripts, however the implementation is slightly less
transparent. Also, the name of the rules and the location of scripts
vary from distribution from distribution.

        When something interesting happens, the Linux kernel generates
an Hotplug event. The uDev deamon (udevd) receive the event, does some
processing on its own, use the rules in /etc/udev/rules.d/, and
finally run the proper script in /lib/udev/.
        There are 3 types of Hotplug events we care about :
                o PCI event : a CardBus device is added or removed
from the system. The hotplug rule loads the driver, in my case
/etc/udev/rules.d/z55_hotplug.rules.
                o USB event : a USB device is added or removed from
the system. The hotplug rule loads the driver, in my case
/etc/udev/rules.d/z55_hotplug.rules.
                o Network event : a network interface is added or
removed from the system. The script /lib/udev/net.agent is run.

        If we insert a CardBus network card in the system, the
following happens :
                1) Kernel detects new CardBus device
                2) Kernel generates PCI Hotplug event
                3) udevd receive the event, runs the Hotplug rule.
                4) The Hotplug rule find the proper driver module and loads it.
                5) Driver module initialises, creates new network device
                6) Kernel detects new network device
                7) Kernel generates Network Hotplug event
                8) /lib/udev/net.agent runs, configures network device
        The sequence of events is similar for USB devices and for removals.

        3) Installing uDev for Debian Lenny
        -----------------------------------
        Thanks to the great work of many people, Debian Lenny has all
the necessary packages and complete udev support, and will work mostly
'out of the box'.
        You will need to install the following packages :
                o udev
                o ifrename

        The configuration of Hotplug and uDev is simple. You only have
to modify the file /etc/network/interfaces to enable your interfaces
to be managed with Hotplug and uDev.
        By default, ifup ignore all hotplug network events, as it
assume network interfaces are configured using the static init
scripts. To enable ifup to configure specific network interfaces on
hotplug events, you need to list those interface in a "allow-hotplug"
statement.
        For example, your /etc/network/interfaces would include :
--------- /etc/network/interfaces -----------
# Enable Hotplug support (Etch and later)
#
allow-hotplug prism0 acx0
---------------------------------------------

        4) Installing uDev for Debian Etch (4.0)
        ----------------------------------------
        The uDev system provided with Debian Etch (4.0) is fully
functional, except for one missing feature. This version of uDev can
not integrate with ifrename. The version of ifrename provided also
lacks uDev support.
        If you want to use uDev with Debian Etch (4.0), there are two
possibilities. The first solution is use the uDev system to rename
interfaces, loosing some of the power of ifrename. The second solution
is to upgrade both udevd and ifrename.

        This is the procedure I personally use to upgrade udevd on
Debian Etch (4.0) :
        o Get the canonical version of udev 107 from :
                http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html
        o Compile it with "make".
        o Do not "make install" !
        o Run "strip udevd"
        o Save a copy of the original udevd "cp /sbin/udevd /sbin/udevd.orig"
        o Copy the new udevd with "cp udevd /sbin/udevd".
        Note that udevd is an essential component of the OS. This
procedure should be safe, but I do not guarantee it will always be
safe.

        Upgrading ifrename is simple, this is like installing ifrename
and is described above in this document.

        Once those two packages are upgraded, you can go follow the
procedure going back to step (3).

        5) Installing uDev for Debian Sarge (3.1)
        -----------------------------------------
        The uDev system provided with Debian Sarge (3.1) is a very old
version of uDev that is not integrated with the Hotplug scripts. In
other words, if you install uDev with Sarge, you will still need to
use the original Hotplug scripts and configure your system with them.

        6) Installing uDev on other distributions
        --------------------------------------------
        The canonical version of hotplug is available at :
                http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html
        The mailing list for udev is the Hotplug mailins list :
                http://linux-hotplug.sourceforge.net/
                http://marc.theaimsgroup.com/?l=linux-hotplug-devel&r=1&w=2

        Most distributions have highly customized uDev packages and
most likely the canonical version won't completely work on your
system. The udevd deamon is has usually little changes, however the
rules and scripts are very different.
        To be able to use uDev with ifrename, you will need uDev
version 107 and later, which has support for calling ifrename. You
will also need ifrename version 29.pre17 or later (I recommend version
29). Most modern distributions should already have those versions.
        If this is the case, you only need to install the uDev and
ifrename package. If there is no ifrename package, it's easy to
compile it from source and install it.

        7) Making uDev call ifrename
        ----------------------------
        We need to make sure that 'ifrename' is run by the uDev
subsystem at the right time. Because of the complex way uDev works,
the smooth integration can only be done one way. Other methods may
leave the uDev system in a confused state, which may be a problem when
the card/interface is removed.

        Most often, the only thing to do it to copy the file
'19-udev-ifrename.rules' from the Wireless Tools package to the
directory "/etc/udev/rules.d/". It should work on most system.

        What follow is a detailed explanation of what this additional
rules does.
        uDev needs to call ifrename as an IMPORT rule, and with the
right parameter. As I said, this requires uDev version 107 and later
and ifrename version 29.pre17 or later.
        The ifrename rule need to be called *before* the 'persistent'
rules. I also like the ifrename rule to happen after local rules. The
uDev rules are processed in alphabetical orders, which is why the
rules filename start usually with numbers. However, those name vary
betwen distributions. Make sure the ifrename rule has a proper
filename for your distribution.

        The rules we add looks like this :
------ /etc/udev/rules.d/19-udev-ifrename.rules ------
# Main ifrename rule.
# If interface is found in /etc/iftab, subsequent rename rules are bypassed.
# If interface is not found in /etc/iftab, subsequent rename rules applies.
SUBSYSTEM=="net", ACTION=="add", IMPORT="/sbin/ifrename -u -i %k", NAME:="%k"
------------------------------------------------------

        Lastly, make sure the rule has the right path for ifrename :
--------------------------
> which ifrename
/sbin/ifrename
--------------------------

        8) Loading driver modules
        -------------------------
        Wow ! The most difficult part is done.
        In theory, you don't need to do any specific configuration for
the driver modules to be loaded. The uDev system should load the right
driver module for you.
        Also, you don't need to define aliases in /etc/modprobe.d/* or
in /etc/modprobe.conf, it's useless and may be counterproductive.

        If you use a driver compiled statically in the kernel, you
also have nothing to do.

        9) Renaming interfaces
        -----------------------
        We still use ifrename to assign names to interfaces. The
configuration of 'ifrename' is the same. To keep the possibility of
having multiple wireless cards (one in each CardBus slot), we use
wildcards in both the MAC address and the name :

--------- /etc/iftab -----------------------
# SMC 2835W wireless CardBus card
prism*          mac 00:30:B4:*
---------------------------------------------

        If you insert two cards, they would be named prism0 and
prism1. If you want to control which card get each name, you should
not use wildcards and set a specific line for each card :

--------- /etc/iftab -----------------------
# SMC 2835W wireless CardBus card
prism0          mac 00:30:B4:64:27:8B
prism1          mac 00:30:B4:64:27:8D
---------------------------------------------

        10) Configuring interfaces
        --------------------------
        At this point, configuration of uDev network interfaces is done
just like their built-in counterparts. This part is still distribution
specific, and still already documented in the file DISTRIBUTIONS.txt.

        In Debian, you would need to modify the file
/etc/network/interfaces like this :

--------- /etc/network/interfaces -----------
# Enable Hotplug support (Etch and later)
#
allow-hotplug prism0

# SMC 2835W wireless CardBus card
iface prism0 inet static
    address 10.0.1.2
    netmask 255.255.255.0
    broadcast 10.0.1.255
    wireless-essid THE_ESSID
    wireless-mode ad-hoc
    wireless-channel 5
---------------------------------------------

        Note that you can also use graphical tools such as
NetworkManager to configure interfaces at this point.

        Now, just cross your fingers and plug the card in the slot...
        If it does not work, there is a troubleshooting section at the
end of this document.


CONFIGURATION VIA THE ORIGINAL HOTPLUG SCRIPTS
----------------------------------------------
        The previous section was dealing with removable interfaces
with Hotplug events and the uDev system. In various cases, or for old
distributions, it's preferable to use the original Hotplug
scripts. The original Hotplug scripts are much less invasive on the
system than uDev.
        Using the original Hotplug scripts is similar to using uDev or
dealing with built-in interfaces, the main difference is that the
script used are different. Another difference is that it will likely
require more work on your part because most distributions do not have
all part properly integrated.

        1) Applicability
        ----------------
        The Hotplug configuration method is the best choice for any
removable network interface, such as :
                o Pcmcia (16 bits) network cards
                o CardBus (32 bits) network cards
                o USB network dongles
                o Hot-PCI network cards
        It may also be used to manage other types of network
interfaces, although it may not be the best choice for them.

        2) How the original Hotplug scripts works
        -----------------------------------------
        Conceptually, Hotplug is very simple, and the Hotplug scripts
are quite easy to follow.

        When something interesting happens, the Linux kernel generates
an Hotplug event. This runs the main Hotplug script, which in turn
runs the appropriate script from the /etc/hotplug directory.
        There are 3 types of Hotplug events we care about :
                o PCI event : a CardBus device is added or removed
from the system. The script /etc/hotplug/pci.agent is run.
                o USB event : a USB device is added or removed
from the system. The script /etc/hotplug/usb.agent is run.
                o Network event : a network interface is added or
removed from the system. The script /etc/hotplug/net.agent is run.

        If we insert a CardBus network card in the system, the
following happens :
                1) Kernel detects new CardBus device
                2) Kernel generates PCI Hotplug event
                3) /etc/hotplug/pci.agent runs, finds proper driver module
                4) /etc/hotplug/pci.agent loads driver module
                5) Driver module initialises, creates new network device
                6) Kernel detects new network device
                7) Kernel generates Network Hotplug event
                8) /etc/hotplug/net.agent runs, configures network device
        The sequence of events is similar for USB devices and for removals.

        3) Make sure ifup does not deadlock
        -----------------------------------
        <Most people should ignore this part>
        <This applies only to Debian 3.0 and earlier>

        The first problem is that we need to make sure the command
'ifup' does not deadlock by calling itself re-entrantly. If the system
has built-in interfaces, the 'ifup' may reenter itself at boot time
via Hotplug :
                1) Init scripts start running
                2) Init script calls 'ifup -a' to initialise built-in
                        network interfaces
                3) 'ifup' auto-loads driver module for built-in network
                        interface 'eth4'
                4) Driver module initialises, creates new network device
                5) Kernel generates Network hotplug event
                6) /etc/hotplug/net.agent runs, call 'ifup eth4'
        Note that you can produce the same reentrancy if you call ifup
manually on an interface which module is not yet loaded.

        The default version of 'ifup' for Debian 3.0 and Debian 3.1
is not reentrant and can therefore deadlock if not used properly. The
patch to make 'ifup' properly reentrant is available here :
                http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=231197
        Contemporary versions of Debian (3.1 and later) have a
net.agent script that contains workarounds to prevents deadlock
situations, so for normal use the default 'ifup' should work fine.
        Modern version of Debian (4.0 and later) have a version of
'ifup' that is reentrant and that won't deadlock.

        Other distributions have very different ifup programs and I
have not tried those (tell me about it !).

        4) Installing uDev for Debian Etch (4.0) or Lenny
        -------------------------------------------------
        Thanks to the great work of many people, Debian Etch and Lenny
has all the necessary packages and hotplug support, and will work
mostly 'out of the box'.
        You will need to install the following packages :
                o hotplug
                o ifrename

        The configuration of network Hotplug has been much simplified
compared to Debian Sarge (3.0). You only have
to modify the file /etc/network/interfaces to enable your interfaces
to be managed with Hotplug and uDev.
        By default, ifup ignore all hotplug network events, as it
assume network interfaces are configured using the static init
scripts. To enable ifup to configure specific network interfaces on
hotplug events, you need to list those interface in a "allow-hotplug"
statement.
        For example, your /etc/network/interfaces would include :
--------- /etc/network/interfaces -----------
# Enable Hotplug support (Etch and later)
#
allow-hotplug prism0 acx0
---------------------------------------------

        5) Installing Hotplug for Debian Sarge (3.1)
        --------------------------------------------
        Thanks to the great work of many people, Debian Sarge has all
the necessary packages and hotplug support, and will work mostly 'out
of the box'.
        You will need to install the following packages :
                o hotplug
                o ifrename

        While the installation of Hotplug is simple, its configuration
may seem complex. The current network Hotplug script has 3 modes :
'all', 'auto' and 'hotplug'. However for our purpose they all produce
the same results when configured. This mode is controlled by the
variable NET_AGENT_POLICY in /etc/default/hotplug.

        In the mode "all", Hotplug will run ifup for all network
events. This will result in failure messages if some interfaces have
already been configured by the init scripts. This mode is not
recommended.

        In the mode "auto", Hotplug will run ifup only for those
interfaces listed in a auto stanza in /etc/network/interfaces. If
you choose this mode, you need to put in /etc/network/interfaces a
"auto" line for the interfaces you want to control with hotplug.
--------- /etc/network/interfaces -----------
# Enable Hotplug support for "auto" mode (Sarge and later)
auto eth0 eth1 eth2 eth3 eth4 wlan0 wlan1 prism0 prism1 airo0 airo1
---------------------------------------------
        This will result in some failure message at boot time, the
init script will attempt to enable all those interfaces, and generate
an error for all those not available at this time. It will also
generate an error messages for interface which have already been
configured by the init scripts. This mode is also not recommended.

        In the mode "hotplug", hotplug network events are ignored by
ifup by default. To enable them you will need to add the following
lines to /etc/network/interfaces :
--------- /etc/network/interfaces -----------
# Enable Hotplug support for "hotplug" mode (Sarge and later)
mapping hotplug
    script echo
---------------------------------------------

        To enable them for only selected interfaces, e.g., ethA, make
/etc/network/interfaces look like this :
--------- /etc/network/interfaces -----------
# Enable Hotplug support for "hotplug" mode (Sarge and later)
mapping hotplug
    script grep
    map ethA
---------------------------------------------

        6) Installing Hotplug for Debian 3.0
        ------------------------------------
        Debian 3.0 doesn't come by default with hotplug, but the
hotplug package is available as regular Debian package (on the CD or
downloadable in Debian archive), so you can just install that.

        Unfortunately, this version of hotplug is not fully compatible
with kernel 2.6.X. You will need to do the following modifications to
the file /etc/hotplug/net.agent.

------- /etc/hotplug/net.agent ------------------
--- net.agent-d1        Fri Feb 20 18:18:05 2004
+++ net.agent   Fri Feb 20 18:22:50 2004
@@ -26,7 +26,7 @@ if [ "$INTERFACE" = "" ]; then
 fi

 case $ACTION in
-register)
+add|register)

     case $INTERFACE in
        # interfaces that are registered after being "up" (?)
@@ -52,7 +52,7 @@ register)
     mesg $1 $ACTION event not handled
     ;;

-unregister)
+remove|unregister)
     # Assume that we want to run ifdown no matter what,
     # because it is not going to remove the data from the
     # ifstate database otherwise.
-------------------------------------------------

        Compared to the version in Sarge, this older version of
hotplug is much more basic, and doesn't have any scanning at boot time
and doesn't need to be enabled in /etc/network/interfaces.

        7) Installing hotplug on other distributions
        --------------------------------------------
        The canonical version of hotplug is available at :
                http://linux-hotplug.sourceforge.net/

        Most distributions have customized hotplug packages and
chances are that the canonical version won't completely work on your
system. All these various changing versions make it difficult for me
to tell what exactly needs to be changed in the hotplug scripts to
make them work. However, most should work out of the box.
        Remember also that in most cases, you can not have the
original Hotplug scripts and uDev together. If uDev is already
installed on your system, downgrading to the original Hotplug scripts
may be tricky.

        My guess is that in a few releases, all these problems will
sort themselves out. Just be patient.

        8) Dealing with 'init' hotplug
        ------------------------------
        In addition to the standard kernel Hotplug events, modern
versions of the Hotplug scripts add init scripts that scan the system
buses and generate pseudo Hotplug events at boot time. For the PCI
buses, the script /etc/hotplug/pci.rc is run, for the USB bus,
/etc/hotplug/usb.rc is run.
        The end result is that the Hotplug subsystem will also attempt
to configure built-in devices :
                1) Kernel boots
                2) Init runs, start to initialise the OS
                3) /etc/hotplug/pci.rc runs, generates pseudo Hotplug event
                4) /etc/hotplug/pci.agent loads driver module
                5) Driver module initialises, creates new network device
                6) Kernel generates Network Hotplug event
                7) /etc/hotplug/net.agent runs, configures network device

        At this point, you realise that at initialisation, both
Hotplug and the regular init scripts (see "CONFIGURATION FROM INIT
SCRIPTS") are trying to configure the same devices in parallel. This
may create problems and is totally redundant.
        Another reason I don't like this mechanism is that it blindly
attempts to load drivers for all hardware present on the system and
doesn't use the module loader configuration files to select preferred
drivers. It's fairly common to have multiple drivers for a given
hardware, and because of Murphy's law, Hotplug will usually load the
wrong one. It's also fairly common to have hardware on the system that
doesn't need enabling (for example, the IDE controller on my SCSI
machine), not loading the driver makes your kernel smaller and boot
faster.

        Hotplug does have a way of disabling the loading of drivers
on a case by case basis. Drivers listed in /etc/hotplug/blacklist
will not be loaded.
        Hotplug can be disabled for a whole subsystem by editing the
appropriate .rc script in /etc/hotplug, or just deleting/renaming
those files.

        9) Making hotplug scripts call ifrename
        ---------------------------------------
        The last hotplug step is to make sure that 'ifrename' is run
by the hotplug subsystem at the right time. As before, we want to run
it just before calling 'ifup'.
        The latest version of the hotplug scripts have this feature
integrated. However, you need to check that the path used for calling
'ifrename' is the proper one on your system. And, for older versions
of hotplug scripts, you will need to add this support yourself.

        Check the path for ifrename :
--------------------------
> which ifrename
/sbin/ifrename
--------------------------

        The patch to add 'ifrename' to hotplug looks like :

------- /etc/hotplug/net.agent ------------------
--- net.agent-s2        Fri Feb 20 17:18:46 2004
+++ net.agent   Fri Feb 20 17:32:43 2004
@@ -40,6 +40,21 @@ add|register)
            # we can't do much here without distro-specific knowledge
            # such as whether/how to invoke DHCP, set up bridging, etc.

+           # Run ifrename as needed - Jean II
+           # Remap interface names based on MAC address. This works around
+           # the dreaded configuration problem "all my cards are 'eth0'"...
+           # This needs to be done before ifup, otherwise ifup will get
+           # confused by the name change and because iface needs to be
+           # down to change its name.
+           if [ -x /sbin/ifrename ] && [ -r /etc/iftab ]; then
+               debug_mesg invoke ifrename for $INTERFACE
+               NEWNAME=`/sbin/ifrename -i $INTERFACE`
+               if [ -n "$NEWNAME" ]; then
+                   debug_mesg iface $INTERFACE is remapped to $NEWNAME
+                   INTERFACE=$NEWNAME
+               fi;
+           fi
+
            # RedHat and similar
            export IN_HOTPLUG=1
            if [ -x /sbin/ifup ]; then
-------------------------------------------------

        If your hotplug scripts already include ifrename support then
you should find a section in /etc/hotplug/net.agent looking like the
patch above. Otherwise, just cut'n'paste the patch above in the right
place.
        The path for 'ifrename' is used twice above, so don't forget
to modify both occurences.


        9) Loading driver modules
        -------------------------
        Wow ! The most difficult part is done.
        In theory, you don't need to do any specific configuration for
the driver modules to be loaded. The 'pci.agent' and 'usb.agent'
should load the right driver module for you.
        Also, you don't need to define aliases in /etc/modprobe.d/* or
in /etc/modprobe.conf, it's useless and may be counterproductive.

        If you use a driver compiled statically in the kernel, you
also have nothing to do.

        10) Renaming interfaces
        -----------------------
        We still use ifrename to assign names to interfaces. The
configuration of 'ifrename' is the same. To keep the possibility of
having multiple wireless cards (one in each CardBus slot), we use
wildcards in both the MAC address and the name :

--------- /etc/iftab -----------------------
# SMC 2835W wireless CardBus card
prism*          mac 00:30:B4:*
---------------------------------------------

        If you insert two cards, they would be named prism0 and
prism1. Note that 'name wildcarding' is a feature only available in
2.6.X and 2.4.30 and later, so if you use older version of 2.4.X you
will need to be explicit and list each card separatly :

--------- /etc/iftab -----------------------
# SMC 2835W wireless CardBus card
prism0          mac 00:30:B4:64:27:8B
prism1          mac 00:30:B4:64:27:8D
---------------------------------------------

        11) Configuring interfaces
        -------------------------
        At this point, configuration of Hotplug network interfaces is
done just like their built-in counterparts. This part is still
distribution specific, and still already documented in the file
DISTRIBUTIONS.txt.

        In Debian, you would need to modify the file
/etc/network/interfaces like this :

--------- /etc/network/interfaces -----------
# Enable Hotplug support (Etch and later)
#
allow-hotplug prism0 acx0

# Enable Hotplug support (Sarge and later)
mapping hotplug
    script grep
    map prism0

# SMC 2835W wireless CardBus card
iface prism0 inet static
    address 10.0.1.2
    netmask 255.255.255.0
    broadcast 10.0.1.255
    wireless-essid THE_ESSID
    wireless-mode ad-hoc
    wireless-channel 5
---------------------------------------------

        Note that you should not have wireless-* lines if you are
using waproamd to set these parameters.

        Now, just cross your fingers and plug the card in the slot...


PCMCIA INTERFACES (16 bits)
---------------------------
        The Pcmcia subsystem has quite some legacy, and can use
various configuration procedures. The Pcmcia subsystem exclusively
uses hotplug for 32 bits cards (if you are using the kernel Pcmcia
modules, which is the only option for 2.6.X). For 16 bit cards cardmgr
is still required for managing the sockets and loading
modules. Cardmgr is configured by files in the /etc/pcmcia directory.

        To use Hotplug network configuration with 16 bits Pcmcia
cards, first make sure the Pcmcia subsystem is properly configured and
that cardmgr loads the right driver module (in most case, it
should). Then, make sure that you don't have any configuration entries
in /etc/pcmcia/network.opts and /etc/pcmcia/wireless.opts. Make sure
that none of the entries in your system network configuration use
'eth0' or 'wlan0' (in /etc/network/interfaces for Debian users).
        Then, just follow the procedure described above for
"Configuration Using Hotplug" to configure your network cards.

        You might want a little bit of explanation on why this magic
will work (which would help in case it doesn't work).
        There are two types of Pcmcia network configuration scripts,
available as /etc/pcmcia/network. The original Pcmcia script
configures network cards using options found in
/etc/pcmcia/network.opts and /etc/pcmcia/wireless.opts. Most
distributions replace it with a script calling 'ifup'. By making sure
that network.opts and wireless.opts are "empty", we neutralise the
first set of scripts. By making sure no system configuration uses
'eth0' or 'wlan0', we neutralise the second set of scripts, the script
would call 'ifup' with the default interface name, which is usually
'eth0', ifup would not find a configuration for it and would just
ignore it.
        The card would still be configured because hotplug network
events are generated for every interfaces, not only for devices
managed by hotplug. So, net.agent would receive an event and perform
the necessary steps to configure it.

        Personally, I'm still using the original Pcmcia scripts for my
Pcmcia cards as described in the file PCMCIA.txt, because it still
works and I will migrate my complex configurations over time.
        You can also decide to not use Hotplug for Pcmcia cards and
modify the distribution Pcmcia scripts in /etc/pcmcia/* to handle
Pcmcia cards with ifrename. You would need to modify
/etc/pcmcia/network to add 'ifrename' before 'ifup' the same way it
was done for /etc/hotplug/net.agent. But, as in the long term Pcmcia
will migrate to Hotplug, I would not bother...


MANUAL LOADING, DOCKING STATIONS
--------------------------------
        Manual loading is used for built-in network interfaces that
are only use at specific time, and that you want disabled the rest of
the time. We assume that you still use modules so that when the
interface is not used you can remove the driver from the kernel.

        First, you need to set the configuration for those interfaces,
the same way it's done for other network interfaces. The main
difference is that you need to specify that those interfaces should
not be enabled at boot time. It's also a good idea to disable Hotplug
init scripts.
        With Debian, you just need to make sure that the 'auto"
keyword doesn't apply to this interface.

        If you use drivers statically built in the kernel, make sure
that ifrename runs at boot time (see CONFIGURATION FROM INIT
SCRIPTS). Once it's done, you can just enable and disable those
interfaces with 'ifup ethX' and 'ifdown ethX'.

        If you use both a modular system, make sure that the
'on-demand' module loading is properly configured :

--------- /etc/modprobe.d/local or /etc/modprobe.conf ------
# HP 100VG J2585B PCI card
alias eth2 hp100

# AMD AMD PCnet LANCE PCI card
alias eth4 pcnet32
------------------------------------------------------------

        Then, you should instruct 'ifup' to load module and use
ifrename prior to configuring the interface, and remove the module
when going down. With Debian, this is done with :

--------- /etc/network/interfaces -----------
# AMD AMD PCnet LANCE PCI card
# noauto
iface eth4 inet dhcp
    pre-up /sbin/ifrename -p -n eth4
    post-down /sbin/modprobe -r eth4

# HP 100VG J2585B PCI card
# noauto
iface eth2 inet static
    address 10.0.0.2
    netmask 255.255.255.0
    broadcast 10.0.0.255
    gateway 10.0.0.1
    pre-up /sbin/ifrename -p -n eth2
    post-down /sbin/modprobe -r eth2
---------------------------------------------

        We use the '-n' option of ifrename to specify the name of the
interface after renaming. This assume that the mapping for those
interfaces don't use wildcards. The '-p' option make sure ifrename
probes the module prior to using it.
        Using "modprobe -r" make sure that if the driver is composed
of multiple module all the modules are unloaded.

        To enable the interface, just use :
-----------------------------------
ifup eth4
-----------------------------------
        And to disable the interface :
-----------------------------------
ifdown eth4
-----------------------------------

        This solution is obviously Debian specific, but could be
adapted to other distributions. If you can't manage to get your
distributions to use those tricks, you can do things manually.
        If you don't use Hotplug, you enable an interface with :
-----------------------------------
modprobe eth4
ifrename
ifup eth4
-----------------------------------
        If you use hotplug, you only need to do :
-----------------------------------
modprobe eth4
-----------------------------------
        On the other hand, disabling the interface is done with :
-----------------------------------
ifdown eth4
modprobe -r eth4
-----------------------------------


        Docking stations for laptops may contain built-in
interfaces. My previous laptop had one, and Linux had no support for
it. After docking, I was able to bring up the network ISA card in the
docking station.
        However, with most laptops and version of Linux, the issue is
that after docking, the new devices are not seen. The solutions is to
force a rescan of the PCI bus. Documentation is unclear on that, maybe
'scanpci' may help.

        To be able to simply manage my docking station, I had created
two little scripts to enable and disable my network interface.
        After docking, you would run :
-------- /sbin/dock ----------------------------
#!/bin/sh
modprobe eth4
ifrename
ifup eth4
------------------------------------------------
        And prior to undocking, you would run :
-------- /sbin/undock ----------------------------
#!/bin/sh
ifdown eth4
modprobe -r eth4
------------------------------------------------
        Thanks to 'ifrename', the network interface in your dock will
always be properly configured regardless of if you have a Pcmcia
network card in the Pcmcia slot or not.


SCHEMES (MULTI-CONFIG)
----------------------
        Most Ethernet cards will only connect to a single network, or
can use DHCP to be auto-configured. With Wireless Cards, it's much
more likely that you will need multiple configurations, for example at
work, at home and on-the-go.

        Most distributions have various level of support for such
schemes. Some distributions offer simple network schemes, while other
offer "overall" schemes changing the whole configuration. I document
the support for schemes in various distributions in the file
DISTRIBUTIONS.txt.

        You can also use tools such as ifplugd, waproamd or
wlandetect. Those tools are a kind of "wireless-DHCP", they attempt to
automatically detect the proper wireless configuration and apply
it. Most will also attempt to detect network changes.
        The main limitation of those tools is that they offer very
little manual control. If two valid alternatives are possible, you
can't switch between them. If a configuration can't be detected, they
usually fail.
        That's the same concept as using DHCP versus Static IP
addresses. Some people are very happy with DHCP, my style is Static IP
addresses.

        If you use Debian and want to use simple manual schemes, these
are the things you need to do.
        1) Make sure that 'ifscheme' and 'ifscheme-mapping' are
installed on the system. You may find them in a separate tar file on
my web site.
        2) Check the path for 'ifscheme-mapping' (using whereis).
        3) Modify you /etc/network/interface to add proper mapping and
configuration.

------- /etc/network/interfaces ----------------------
# Enable Hotplug support (Sarge and later)
mapping hotplug
    script echo

# SMC 2835W wireless CardBus card
mapping prism0
    script /sbin/ifscheme-mapping

iface prism0-any inet dhcp
    wireless-essid any
    wireless-mode managed

iface prism0-adhoc inet static
    address 10.0.1.2
    network 10.0.1.0
    netmask 255.255.255.0
    broadcast 10.0.1.255
    wireless-essid THE_ESSID
    wireless-mode ad-hoc
    wireless-channel 5

iface prism0-other inet static
    address 10.10.10.2
    network 10.10.10.0
    netmask 255.255.255.0
    broadcast 10.10.10.255
    wireless-essid ANOTHER_ESSID
    wireless-mode ad-hoc
    wireless-key "s:secure"
------------------------------------------------------


FIRMWARE LOADING
----------------
        A lot of modern wireless card don't have built in firmware and
need firmware loading. Recent kernels (2.6.X) have a firmware
loader. These are a few notes on how to use it.

        First, read the documentation coming with your driver, because
each driver has specificities (like the name of the firmware file it
requires). Some drivers may offer additional ways to load the
firmware, but in the long term things should be standardised around
the hotplug method to simplify packaging in distributions.

        You need to compile your kernel with firmware loading
(CONFIG_FW_LOADER in "Generic Driver Options"). If your driver was
built from the kernel, chances are that it enabled this feature
already. Make sure you boot from this new kernel.

        The 'sysfs' file system must be mounted. The easiest is to
mount it at boot time, add a line for it in /etc/fstab :

-------- /etc/fstab ------------------------------
sysfs           /sys          sysfs  defaults                   0      0
--------------------------------------------------

        Then, you add the firmware file in the directory where it's
expected, which is /lib/firmware/ in most cases, and
/usr/lib/hotplug/firmware/ on older systems.

        Most distributions nowadays have a version of the Hotplug
scripts that knows how to deal with firmware. If it is not the case,
just grab the 'firmware.agent' file from an alternate source and copy
it into your /etc/hotplug directory (make sure it's executable).
        You can try the canonical version :
                http://linux-hotplug.sourceforge.net/
        Or Debian's version :
                http://packages.debian.org/unstable/admin/hotplug

        Note that firmware loading will usually only work with
interfaces that are fully managed by Hotplug. This is the only way to
ensure the that proper sequence of action is happening in the right
order every time. Firmware loading may not work properly for
interfaces configured in the init scripts.
        This means that if you have a built-in interface that require
firmware loading, you should just use manage those interfaces like
removable interfaces (see section above). However, interface
configuration need to be explicitly triggered at boot time.

        One possibility is to set-up Hotplug to be run from the init
script at boot time. This is usually an option for recent
distributions (it's not the case for Hotplug in Debian 3.0). But, we
have seen that this has some issues.
        The other possibility is to use an hybrid between the init
script method and the hotplug method. First, you need to add an alias
for the driver in /etc/modprobe.conf. Then, you need to specify a
mapping for this interface in /etc/iftab, and specify a configuration
for this interface and that it is enabled at boot time. Lastly,
you make sure that the network init scripts run 'ifrename
-p'. 'ifrename' will trigger the module to load, and all the Hotplug
events will be generated properly to configure the interface.


DEVICES WITH MULTIPLE NAMES/INTERFACES
--------------------------------------
        Some wireless drivers offer multiple network interfaces for
the same device. A classical example is the Aironet driver that
creates a 'ethX' and 'wifiY' for each card.

        'ifrename' allows you a finer selection of interfaces than
'nameif'. For example, to only rename the pseudo-Ethernet network
interface name of the Aironet driver, you would do :

--------- /etc/iftab -----------------------
# Cisco Aironet 350 wireless Pcmcia card
airo*           mac 00:07:0E:* arp 1
---------------------------------------------

        After that, your device would be available through 'eth0' and
'wifi0'.

        You can rename both interfaces. You just need to remember that
'ifrename' starts matching from the last line of the file, so you
would do :
--------- /etc/iftab -----------------------
# Cisco Aironet 350 wireless Pcmcia card
wifi*           mac 00:07:0E:* arp 801
airo*           mac 00:07:0E:* arp 1
---------------------------------------------

        The current version of 'ifrename' supports only the most useful
selectors, but it is architectured such as adding selectors is relatively
trivial. If you find a case that 'ifrename' can't handle, you should
just extend it.


DEVICES WITHOUT MAC ADDRESSES
-----------------------------
        Most Ethernet and Wireless devices have a fixed and unique MAC
address, and it is therefore advised to name them based on this
criteria. However, there are also network interfaces that don't have a
fixed and unique MAC address, for example Ethernet over USB, IP over
FireWire, PPP and tunnel interfaces.
        The driver for those devices creates the interface with a name
specific to the driver, such as ppp* for PPP interfaces and usb* for
Ethernet over USB, and therefore they are easy to identify and
configure, and few users feel the need to rename them. Moreover, some
of them, such as PPP, have their own configuration scripts and
methodology addressing their unique needs.

        There are a few cases where you might want to rename
interfaces without MAC addresses. One example is two Ethernet over USB
dongles. The way to do this is to use alternate ifrename
selectors. Choosing the right selector depends on what you want to
achieve.
        A quick theoretical example to illustrate :
--------- /etc/iftab -----------------------
# All other usbnet devices
usb*            driver usbnet
# Specific usbnet devices
usb-p           firmware "Prolific PL-2301/PL-2302"
usb-4           bus-info usb-00:02.0-1.4
---------------------------------------------


TROUBLESHOOTING
---------------
        If your interface doesn't show up as expected with ifconfig,
you will need to find out why. First, you need to be familiar with the
sequence of actions in the system and find which one did not happen.

        1) Interfaces on the system
        ---------------------------
        You first need to check which network interfaces are currently
available on your system and configuration was assigned to it. This is
mostly done using 'ifconfig'.
        To list only the configured network interfaces :
--------------------------
> /sbin/ifconfig
--------------------------
        The list all network interfaces :
--------------------------
> /sbin/ifconfig -a
--------------------------
        You can also use 'iwconfig' to check the wireless configuration.

        2) Modules
        ----------
        You need to check that the driver module(s) was loaded using
'lsmod'.

        If this device is configure via init scripts, you should test
if the on-demand loading of module (module probing works). This is
done with :
--------------------------
> /sbin/modprobe -r eth2
> /sbin/modprobe eth2
--------------------------

        If your module does not load, first you should check that the
hardware is present. This depend on the bus used, for PCI bus you will
use 'lspci' and for USB bus you will use 'lsusb'.
        The second step is to check if the driver for your hardware is
available on the system.

        3) Ifrename
        -----------
        You need to check if the interface was properly renamed with
'ifrename'. You can use 'ifrename -D -V' to debug your /etc/iftab.
        Get the list of interfaces on your system with 'ifconfig -a'
or 'cat /proc/net/dev', and check if an interface is using the name
you assigned or 'eth0'. Check any suspicious interfaces with 'ifconfig
eth0', and check its MAC address.
        Verify that no line in /etc/iftab matches the all-zero MAC
address. The all-zero MAC address matches the loopback interface 'lo'
and various pseudo network devices, renaming the loopback interface is
highly discouraged.
        Finally, run ifrename in debug mode :
--------------------------
> /sbin/ifrename -D -V
--------------------------

        The only case where running ifrename in debug mode would
differ from when it is run normally are drivers that don't have valid
descriptor value until after ifrename is run. There are a few drivers,
such as prism54, which don't have a proper MAC address before brought
up. This obviously fools ifrename.
        A way to debug that is to change the way ifrename is called to
save the debug output. For example, you could call ifrename that way :
------- /etc/hotplug/net.agent ------------------
                NEWNAME=`/sbin/ifrename -i $INTERFACE -V 2>> /var/log/ifrename`
-------------------------------------------------

        4) Original Hotplug scripts
        ---------------------------
        The Hotplug subsystem has also good debugging facilities.
        To enable Hotplug debugging, just make sure the variable DEBUG
is defined in /sbin/hotplug :
--------- /sbin/hotplug ------------------------------
--- /sbin/hotplug-old      Tue Mar 26 09:00:20 2002
+++ /sbin/hotplug       Fri Feb 20 18:40:38 2004
@@ -22,7 +22,7 @@
 cd /etc/hotplug
 . hotplug.functions

-# DEBUG=yes export DEBUG
+DEBUG=yes export DEBUG

 if [ "$DEBUG" != "" ]; then
     mesg "arguments ($*) env (`env`)"
------------------------------------------------------
        Then, you can check your message logs for Hotplug events with
'tail -f /var/log/messages'. Verify that the various Hotplug events
happen as expected (pci, firmware, net...), and verify the log
messages from 'net.agent'.

        5) UDev
        -------
        There are two main facilities to debug uDev, the 'udevtest'
program and udev daemon debugging.

        The uDev package comes with 'udevtest', a program that
simulate a hotplug event, however this has many limitations and is not
exactly like the real thing.
        The file 19-udev-ifrename.rules has a special rule to work
with udevtest. This rule runs ifrename in dry-run mode. This rule is
disabled by default, and if you intend to use udevtest you should
enable this rule :
--------- 19-udev-ifrename.rules ---------------------
# Enable this rule to test with udevtest.
ENV{UDEV_LOG}=="6", SUBSYSTEM=="net", ACTION=="add", IMPORT="/sbin/ifrename -D -V -u -i %k", NAME:="%k"
------------------------------------------------------
        Then, to test on a specific interface, you would run it like this :
----------------------
> udevtest /sys/class/net/eth5
[...]
run_program: '/usr/sbin/ifrename' (stderr) 'Dry-run : Would rename eth0 to eth5.'
[...]
udev_rules_get_name: rule applied, 'eth0' becomes 'eth5'
----------------------
        The advantage of this procedure is that it's very simple to
try and all the output is on the console.

        The enable udevd debugging, you need to change the default log
level to "debug" in the file /etc/udev/udev.conf :
--------- /etc/udev/udev.conf ------------------------
udev_log="debug"
------------------------------------------------------
        You will also need to reboot for this change to be
effective. The alternative is to use 'udevcontrol'.
        Make sure the special udevtest rule for ifrename described
above is *NOT* enabled, i.e. it should be commented out or
eliminated.
        The debug message may be spread in various log files depending
on the distribution. On Debian, I would find them with 'tail -f
/var/log/debug'.




        Have fun...

        Jean