hotplug.txt

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

	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 removals and USB devices.

	3) Make sure ifup does not deadlock
	-----------------------------------
	<Most people should ignore this part>
	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 Sarge
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 (Sarge and later) have a
net.agent script that contains workarounds to prevents deadlock
situations, so for normal use the default 'ifup' should work fine.

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

	4) Installing Hotplug for Debian Sarge (testing/unstable)
	---------------------------------------------------------
	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
---------------------------------------------

	5) 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.

	6) 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.

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

	7) 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.

	8) 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 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 (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...