hotplug.txt

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

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

INTRODUCTION
------------
	In the old day, all Wireless cards were managed by the
excellent Pcmcia subsystem and its rich configuration scripts, and
life was happy. 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 systems.
	The USB subsystem already use Hotplug, and 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 show
some good promises. Most users are disapointed 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 removable wireless interfaces, but
we will try to keep things generic and talk of the whole network
interface management, so this should apply also to built-in Ethernet
cards.

PROBLEM STATEMENT
-----------------
	Let 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
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 get
assigned Configuration B.
	Different users may have different definition of what is
Device A. For some, it's a specific instance of a specific hardware,
for others any hardware that meet some criteria (a wireless card, an
Ethernet card).
	The user may also want to have multiple configurations
depending on various factors (like the old Pcmcia schemes). Device A
may get Configuration A1 or Configuration A2 depending on those
factors.
	By default, all network interfaces are created using a default
interface name (starting at "eth0" and going up). I call that problem
"all my cards are eth0". And by default, "eth0" point 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 will be
specific to it. However, it should be easy to translate 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 happen to be my Linux development box, and
has enough interfaces to make it interesting. All the example I quote
in this document are extracted from this fully working system.

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

	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
are not made to be soldered in the Pcmcia slot), therefore Hotplug is
the only way to go.
	2) Built-in PCI and ISA cards are managed by the init scripts,
like 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.
	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', thefore known device should avoid using it
because it might be already taken.
	7) Multiple configurations for a single interface (schemes)
are managed by the ifup/ifdown subsystem.

CONFIGURATION FROM INIT SCRIPTS
-------------------------------
	It may seems paradoxal, 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 our way.
	The configuration of network cards via init scripts is the
traditional way network 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 support
properly removable cards.
	The init scripts perform the following 3 functions in that
order :
		1) load necessary driver modules
		2) rename interface to name chosen by the user
		3) configure those interfaces

	1) Applicability
	----------------
	Configuration from init scripts is applicable to any built-in
network interface (ISA, PCI...), i.e. interfaces availalble at boot
time and that will never be removed from the system.
	The Hotplug subsystem has also 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, and for those Hotplug won't work.
	The advantage of using the init script method is that you are
probably already familiar with it and you have the ability to select
which interfaces should be configured at boot and which interface
should only be enabled manually (whereas Hotplug just configures
everything).

	2) Loading driver modules (if/as needed)
	----------------------------------------
	Most distributions build the kernel drivers as modules. This
modular setup allow 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
your 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. Some distribution have explicit list of modules that are
loaded at boot time, if you want to use that feature you need to check
your distribution. Some system, such as hotplug or kudzu, can scan the
various buses of the PC and load the appropriate drivers, and this is
mostly configuration-free, but may not support all devices. The module
subsystem also allow to load modules 'on-demand'.

	I personally prefer to use the 'on-demand' feature of the
module subsystem has, as it allows you to not have to specify the list
of modules that need to be loaded, and only modules really necessary
are loaded which save kernel memory. You can also choose which module
to load when there are multiple altenate modules valid for your
hardware (which happens quite often).

	With kernel 2.6.X, the module subsystem is configured in
/etc/modprobe.conf. To configure 'on-demand' module loading, I need to
add to this file the following lines :

--------- /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 them or make sure they are correct (some distro are
notorious for picking the wrong driver name). 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). You 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 specific
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 Geentoo and
Mandrake). Other distributions, such as Debian 3.0, don't include
ifrename at all, and you should compile yourself a recent version of
Wireless Tools (v27 or later) and install it.

	In any case, you should verify if 'ifrename' is properly
installed, and what is the path 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 init files. It will need to run just before the call
to 'ifup' or 'ifconfig' command.

	In Debian 3.0, 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 call ifrename (see
step (3) above).

	You may want to also set the proper options for ifrename
(check the man page).
	The option '-p' enable module autoloading compatibility.
	The default version of 'ifrename' also includes some specific
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 you
interface. You can read it on the label on the card or display it
using the 'ifconfig' 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 allow me to
replicate my configuration between multiple identical computers. If
you have to manage large number of computers (like a rack of server or
clusters), you may want to look at other selectors offered by
'ifrename', such as the ability to base interface name on Bus
Information.

	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

	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 name 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 like this :

--------- /etc/network/interfaces -----------
# AMD 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
    network 10.0.0.0
    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 proper
configuration.

CONFIGURATION VIA HOTPLUG
-------------------------
	Dealing with removable interfaces is similar to built-in