hotplug.txt

wireless tools是linux下的一套对无线网卡进行配置的工具

interfaces, the only difference is that we will use the Hotplug
scripts instead of the init scripts. Another difference is that it
will 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
run the proper script from the /etc/hotplug directory.
	There is 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, find 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, configure network device
	The sequence of events is similar for removals and USB devices.

	3) Make ifup reentrant
	----------------------
	<Most people should ignore this part>
	The first problem is that we need to make sure the command
'ifup' is fully reentrant. If the system has built-in interfaces, the
'ifup' may reenter itself at boot time :
		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'
	You can produce the same reentrancy if want to manually load
module with the ifup command.

	The default version of 'ifup' for Debian 3.0 is not reentrant and
may deadlock during boot or if you use it manually. The patch to make
'ifup' properly reentrant is available here :
		http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=231197
	Later version of Debian (Sarge and later) have some workaround
that prevent deadlock in most case (but not fully eliminate them), so
for normal use the default 'ifup' should work fine.

	Other distributions have very different version of ifup, 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 is controlled by the variable
NET_AGENT_POLICY in /etc/default/hotplug.

	In the mode "all", all interfaces are processed by
'ifup'. This will work without further configuration.

	In the mode "auto", only interfaces listed in a auto statement
in /etc/network/interfaces will be processed by 'ifup'. If you choose
this mode, you need to put in /etc/network/interfaces a statement auto
with the complete list of all interfaces.
--------- /etc/network/interfaces -----------
# Enable Hotplug support for "auto" mode (Sarge and later)
auto eth0 eth1 eth2 eth3 eth4 wlan0 wlan1 prism0 prism1 airo0 airo1
---------------------------------------------
	Unfortunately, this will make 'ifup' complain at boot time
that it can't find those interfaces. This is why I don't recommend
this mode.

	In the mode "hotplug", hotplug network events are ignored by
ifup by default. To enable them, therefore making this mode equal to
"all", 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
---------------------------------------------

	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 via apt-get), 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, other cases
	----------------------------------
	The canonical version of hotplug is available at :
		http://linux-hotplug.sourceforge.net/

	Most distributions have various version of hotplug with
various modifications on top of the canonical version, 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 need to be changed in the hotplug scripts to make
them work.

	Some version of hotplug will do scan at boot time, see section
(4) for my comments on this.

	My guess is that in a few release, 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. For the PCI buses, the
script /etc/hotplug/pci.rc is run after the boot, 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, generate 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, configure 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 problem, and it is totally redundant.
	Another reason I don't like this mechanism is that it blindly
attempt to load drivers for all hardware present on the system, and
don't use the configuration in /etc/modules.conf to select the proper
driver. It's fairly common to have multiple driver for some 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.
	Unfortunately, Hotplug did not provide a simple way to disable
such a feature. More importantly, there is no way to selectively
disable it (let say, disabled for network, enabled for sound).

	One way to disable this functionality is to delete or rename
the files /etc/hotplug/pci.rc and /etc/hotplug/usb.rc.

	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
integrated. However, you need to check that the path they use 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 workaround
+           # the dreaded configuration problem "all my cards are 'eth0'"...
+           # This needs to be done before ifup otherwise ifup will get
+           # confused by the name changed and because iface need 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 scrips already include ifrename support, 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.conf,
it's useless (and may be counter productive).

	If you use 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, so if you use 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 document 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 echo

# SMC 2835W wireless CardBus card
iface prism0 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
---------------------------------------------

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

PCMCIA INTERFACES (16 bits)
---------------------------
	The Pcmcia subsystem has quite some legacy, and can use
various configuration procedure. The Pcmcia subsystem fully use
hotplug for 32 bits card (if you are using the kernel Pcmcia modules,
which is the only option for 2.6.X). For 16 bits cards, we can't make
them fully hotplug yet and need the cardmgr and /etc/pcmcia directory,
however we can make their network configuration use hotplug.

	To use Hotplug network configuration with 16 bits Pcmcia
cards, first make sure the Pcmcia subsystem is properly configured and
that cardmgr load the right 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 entries in your system network configuration use 'eth0' or