hotplug.txt

This package contains the Wireless tools, used to manipulate the Wireless Extensions. The Wireless

		Sane network interface management with Hotplug
		----------------------------------------------

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) still use the old Pcmcia scripts.
	The Hotplug system is still in its infancy, but already shows
some good promise. Most users are disappointed at first by its
apparent lack of features compared to the Pcmcia scripts. 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) 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.
	3) 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.
	4) (1), (2) and (3) must be compatible on the same system and
play nice with each other.

	5) 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').
	6) No interface is called 'eth0' (or 'wlan0'). Any unknown
device would be 'eth0', so known devices should be called something
else.
	7) 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. 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.

	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 Sarge, 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, don't include
ifrename at all, so you should compile yourself a recent version of
Wireless Tools (v27 or later) and install it.

	In any case, you should verify that 'ifrename' is properly
installed and check the path needed to call it :
--------------------------
> which ifrename
/sbin/ifrename
--------------------------
	Most distributions will install 'ifrename' in '/sbin', while if
you compile your own wireless tools, it will be in '/usr/local/sbin'.

	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 3.0 and Debian Sarge, it needs to be run from
/etc/init.d/networking, which is not the default. The necessary patch
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'.

	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.

CONFIGURATION VIA HOTPLUG
-------------------------
	Dealing with removable interfaces is similar to dealing with
built-in interfaces, the main difference is that we will use the
Hotplug scripts instead of the init scripts. Another difference is
that it will likely require more work on your part because most
distributions are not fully ready for 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
	--------------------
	Conceptually, Hotplug is very simple. When something
interesting happens, the Linux kernel generates an Hotplug event. This
runs the proper script from the /etc/hotplug directory.