1 Sane Hotplug network interface management
2 -----------------------------------------
6 In the old day, all Wireless cards were managed by the
7 excellent Pcmcia subsystem and its rich configuration scripts, and
8 life was happy. Then came the wireless PCI cards, then the wireless
9 USB dongles. Some unification was needed, and rather than adapt the
10 Pcmcia subsystem for PCI and USB, it was decided to create the much
11 simpler Hotplug systems.
12 The USB subsystem already use Hotplug, and the Pcmcia
13 subsystem is migrating to it, CardBus cards (32 bits) already use
14 Hotplug, whereas Pcmcia cards (16 bits) still use the old Pcmcia
16 The Hotplug system is still in its infancy, but already show
17 some good promises. Most users are disapointed at first by its
18 apparent lack of features compared to the Pcmcia scripts. In this
19 document, we will show how to fully exploit the Hotplug system and try
20 to implement the equivalent of all the functionality of the Pcmcia
25 The target audience of this document is mostly power users and
26 distribution maintainers, but it should give enough clues to help
27 newbies. You should have read and understood DISTRIBUTIONS.txt. The
28 procedures described here are more advanced than the simple
29 configuration described in DISTRIBUTIONS.txt.
30 The main focus is of course removable wireless interfaces, but
31 we will try to keep things generic and talk of the whole network
32 interface management, so this should apply also to built-in Ethernet
37 Let assume a Linux system and two or more network devices,
38 Device A and Device B. Those devices may be built-in or removable,
39 they may be present or absent from the system at any time, and
40 activated in any particular order.
41 The user wants to assign Configuration A to Device A and
42 Configuration B to Device B, without the possibility that Device A get
43 assigned Configuration B.
44 Different users may have different definition of what is
45 Device A. For some, it's a specific instance of a specific hardware,
46 for others any hardware that meet some criteria (a wireless card, an
48 The user may also want to have multiple configurations
49 depending on various factors (like the old Pcmcia schemes). Device A
50 may get Configuration A1 or Configuration A2 depending on those
52 By default, all network interfaces are created using a default
53 interface name (starting at "eth0" and going up). I call that problem
54 "all my cards are eth0". And by default, "eth0" point to a single
55 fixed configuration in the configuration database. Clearly, this won't
56 satisfy our requirements.
60 The distribution I use is Debian 3.0, and some parts will be
61 specific to it. However, it should be easy to translate to other
62 distributions and I welcome additions to this document.
64 The example system is as follows :
65 o Linux 2.6.X SMP kernel with hotplug support
66 o Fully modular system (all network drivers as modules)
67 o PCI Ethernet card : AMD PCnet LANCE (pcnet32 - eth4)
68 o PCI Ethernet card : HP 100VG J2585B (hp100 - eth2)
69 o ISA Wireless card : Old AT&T Wavelan (wavelan - eth3)
70 o ISA-Pcmcia bridge : VADEM VG-469 (i82365 - slot 0)
71 o PCI-CardBus bridge : Ricoh RL5c475 (yenta_socket - slot 2)
72 o Pcmcia 802.11 card : Aironet 350 (airo_cs - eth0)
73 o Pcmcia 802.11 card : Lucent Orinoco (orinoco_cs - eth0)
74 o CardBus 802.11 card : SMC 2835W (prism54 - prism0)
76 This system just happen to be my Linux development box, and
77 has enough interfaces to make it interesting. All the example I quote
78 in this document are extracted from this fully working system.
82 Most of the concept and tricks presented here are not really
83 new, the main contribution is to integrate them together and make them
86 1) Removable network interfaces are managed by Hotplug
87 (Pcmcia, CardBus, USB...). We can't assume that those interfaces are
88 always present in this system and available at boot time (Pcmcia cards
89 are not made to be soldered in the Pcmcia slot), therefore Hotplug is
91 2) Built-in PCI and ISA cards are managed by the init scripts,
92 like they have always been. The ISA subsystem will never have Hotplug
93 support, and hotplug is not necessary for PCI cards.
94 3) Built-in devices that are disable most of the time should
96 4) (1), (2) and (3) must be compatible on the same system and
97 play nice with each other.
99 5) A well defined and consistent network interface name is
100 assigned to each network hardware interface using 'ifrename'. Device A
101 is always named 'ethA' (or whatever name you like such as
103 6) No interface is called 'eth0' (or 'wlan0'). Any unknown
104 device would be 'eth0', thefore known device should avoid using it
105 because it might be already taken.
106 7) Multiple configurations for a single interface (schemes)
107 are managed by the ifup/ifdown subsystem.
109 CONFIGURATION FROM INIT SCRIPTS
110 -------------------------------
111 It may seems paradoxal, but before setting up Hotplug, we need
112 to make sure that the initialisation of network cards via init
113 scripts is done properly and doesn't get in our way.
114 The configuration of network cards via init scripts is the
115 traditional way network is initialised in Linux. The advantage of this
116 method is that it's very well documented and understood, and has not
117 changed much over the years. Unfortunately, it doesn't support
118 properly removable cards.
119 The init scripts perform the following 3 functions in that
121 1) load necessary driver modules
122 2) rename interface to name chosen by the user
123 3) configure those interfaces
127 Configuration from init scripts is applicable to any built-in
128 network interface (ISA, PCI...), i.e. interfaces availalble at boot
129 time and that will never be removed from the system.
130 The Hotplug subsystem has also the ability to configure some
131 of the built-in network interfaces, such as PCI cards. However, there
132 is a class of devices that will never have Hotplug support, such as
133 ISA and EISA cards, and for those Hotplug won't work.
134 The advantage of using the init script method is that you are
135 probably already familiar with it and you have the ability to select
136 which interfaces should be configured at boot and which interface
137 should only be enabled manually (whereas Hotplug just configures
140 2) Loading driver modules (if/as needed)
141 ----------------------------------------
142 Most distributions build the kernel drivers as modules. This
143 modular setup allow to minimise the amount of memory used by the
144 system and the flexible loading/unloading of drivers.
145 You can also compile your kernel with static drivers
146 (non-modular). In that case, the driver will always be available in
147 your kernel, you don't need to configure the module subsystem, so you
148 can skip directly to the next section.
150 There are 3 alternatives to manage device drivers as
151 modules. Some distribution have explicit list of modules that are
152 loaded at boot time, if you want to use that feature you need to check
153 your distribution. Some system, such as hotplug or kudzu, can scan the
154 various buses of the PC and load the appropriate drivers, and this is
155 mostly configuration-free, but may not support all devices. The module
156 subsystem also allow to load modules 'on-demand'.
158 I personally prefer to use the 'on-demand' feature of the
159 module subsystem has, as it allows you to not have to specify the list
160 of modules that need to be loaded, and only modules really necessary
161 are loaded which save kernel memory. You can also choose which module
162 to load when there are multiple altenate modules valid for your
163 hardware (which happens quite often).
165 With kernel 2.6.X, the module subsystem is configured in
166 /etc/modprobe.conf. To configure 'on-demand' module loading, I need to
167 add to this file the following lines :
169 --------- /etc/modprobe.conf ----------------
170 # HP 100VG J2585B PCI card
173 # AMD AMD PCnet LANCE PCI card
176 # Old AT&T Wavelan ISA card
178 options wavelan io=0x390 irq=15
179 ---------------------------------------------
181 Your distribution may already have lines for your interfaces,
182 either replace them or make sure they are correct (some distro are
183 notorious for picking the wrong driver name). This file also contains
184 configuration for lot of other subsystems, obviously you don't want to
186 In this file, you put the name you would like the interface to
187 have (we'll fix that in a minute). You note that for modern PCI cards,
188 this is much more straightforward than for old ISA cards.
190 3) Installing 'ifrename'
191 ------------------------
192 You will need to install ifrename on your system. 'ifrename'
193 is part of the Wireless Tools package (version 27 and later) and is a
194 complete rewrite of the now obsolete 'nameif'.
195 Some distributions, such as Debian Sarge, offer a specific
196 package for 'ifrename', and in this case you should just install this
197 package. Other distributions may include ifrename as part of their
198 'wireless tools' package (this should be the case for Geentoo and
199 Mandrake). Other distributions, such as Debian 3.0, don't include
200 ifrename at all, and you should compile yourself a recent version of
201 Wireless Tools (v27 or later) and install it.
203 In any case, you should verify if 'ifrename' is properly
204 installed, and what is the path to call it.
205 --------------------------
208 --------------------------
209 Most distributions will install 'ifrename' in '/sbin', while if
210 you compile your own wireless tools, it will be in '/usr/local/sbin'.
212 4) Making the boot scripts call 'ifrename'
213 ------------------------------------------
214 You need to make sure 'ifrename' is run at boot time. Most
215 distributions don't do that yet by default.
216 This is a part that is distribution specific, so you will need
217 to look into your init files. It will need to run just before the call
218 to 'ifup' or 'ifconfig' command.
220 In Debian 3.0, it needs to be run from /etc/init.d/networking,
221 which is not the default. The necessary patch is below :
223 ----------------------------------------------------------------
224 --- networking-orig Wed Feb 18 13:56:23 2004
225 +++ networking Fri Feb 20 14:51:06 2004
226 @@ -120,6 +120,15 @@ case "$1" in
230 + # Optionally remap interface names based on MAC address.
231 + # '/sbin/ifrename' is part of wireless-tools package.
232 + # /etc/iftab is currently not created by default. Jean II
233 + if [ -x /sbin/ifrename ] && [ -r /etc/iftab ]; then
234 + echo -n "Remapping network interfaces name: "
239 echo -n "Configuring network interfaces: "
242 ----------------------------------------------------------------
243 Don't forget to set the appropriate path to call ifrename (see
246 You may want to also set the proper options for ifrename
247 (check the man page).
248 The option '-p' enable module autoloading compatibility.
249 The default version of 'ifrename' also includes some specific
250 Debian support : using "ifrename -p -d", only the proper modules are
251 loaded. If you are using Debian, you should use this option.
253 5) Renaming interfaces
254 ----------------------
255 As stated above, we use 'ifrename' to assign names to
258 First, you need to get the MAC address of each of you
259 interface. You can read it on the label on the card or display it
260 using the 'ifconfig' command. Remember that the interface won't load
261 yet with the proper name, so you may need to do a bit looking around :
263 -----------------------------
266 eth0 Link encap:Ethernet HWaddr 00:10:83:34:BA:E5
268 -----------------------------
270 The configuration of 'ifrename' is simple, you just specify
271 which name should be used for each MAC address in the file
274 --------- /etc/iftab ------------------------
275 # HP 100VG J2585B PCI card
278 # Old AT&T Wavelan ISA card
281 # AMD AMD PCnet LANCE PCI card
283 ---------------------------------------------
285 The '*' in the MAC address is a wildcard and allow me to
286 replicate my configuration between multiple identical computers. If
287 you have to manage large number of computers (like a rack of server or
288 clusters), you may want to look at other selectors offered by
289 'ifrename', such as the ability to base interface name on Bus
292 To test that ifrename works, do the following :
293 o load all your drivers, see section (2)
294 o check /proc/net/dev to see which interface exist
295 o bring all interfaces down : ifconfig ethX down
297 o check each interface with ifconfig
299 6) Configuring interfaces
300 -------------------------
301 Most likely, your distribution is already doing this part
302 properly. Just assign the proper IP and wireless configuration to each
303 of the interface name you have chosen.
304 This part is distribution specific, and I already document it
305 in the file DISTRIBUTIONS.txt.
307 In Debian, you would need to modify the file
308 /etc/network/interfaces like this :
310 --------- /etc/network/interfaces -----------
311 # AMD AMD PCnet LANCE PCI card
315 # HP 100VG J2585B PCI card
317 iface eth2 inet static
320 netmask 255.255.255.0
323 ---------------------------------------------
325 This was the last part. Now, at your next boot, all your
326 interfaces should be assigned the proper name and proper
329 CONFIGURATION VIA HOTPLUG
330 -------------------------
331 Dealing with removable interfaces is similar to built-in
332 interfaces, the only difference is that we will use the Hotplug
333 scripts instead of the init scripts. Another difference is that it
334 will require more work on your part because most distributions are not
339 The Hotplug configuration method is the best choice for any
340 removable network interface, such as :
341 o Pcmcia (16 bits) network cards
342 o CardBus (32 bits) network cards
343 o USB network dongles
344 o Hot-PCI network cards
345 It may also be used to manage other types of network
346 interfaces, although it may not be the best choice for them.
350 Conceptually, Hotplug is very simple. When something
351 interesting happens, the Linux kernel generates an Hotplug event. This
352 run the proper script from the /etc/hotplug directory.
353 There is 3 types of Hotplug events we care about :
354 o PCI event : a CardBus device is added or removed
355 from the system. The script /etc/hotplug/pci.agent is run.
356 o USB event : a USB device is added or removed
357 from the system. The script /etc/hotplug/usb.agent is run.
358 o Network event : a network interface is added or
359 removed from the system. The script /etc/hotplug/net.agent is run.
361 If we insert a CardBus network card in the system, the
363 1) Kernel detects new CardBus device
364 2) Kernel generates PCI Hotplug event
365 3) /etc/hotplug/pci.agent runs, find proper driver module
366 4) /etc/hotplug/pci.agent loads driver module
367 5) Driver module initialises, creates new network device
368 6) Kernel detects new network device
369 7) Kernel generates Network Hotplug event
370 8) /etc/hotplug/net.agent runs, configure network device
371 The sequence of events is similar for removals and USB devices.
373 3) Make ifup reentrant
374 ----------------------
375 <Most people should ignore this part>
376 The first problem is that we need to make sure the command
377 'ifup' is fully reentrant. If the system has built-in interfaces, the
378 'ifup' may reenter itself at boot time :
379 1) Init scripts start running
380 2) Init script calls 'ifup -a' to initialise built-in network
382 3) 'ifup' auto-loads driver module for built-in network
384 4) Driver module initialises, creates new network device
385 5) Kernel generates Network hotplug event
386 6) /etc/hotplug/net.agent runs, call 'ifup eth4'
387 You can produce the same reentrancy if want to manually load
388 module with the ifup command.
390 The default version of 'ifup' for Debian 3.0 is not reentrant and
391 may deadlock during boot or if you use it manually. The patch to make
392 'ifup' properly reentrant is available here :
393 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=231197
394 Later version of Debian (Sarge and later) have some workaround
395 that prevent deadlock in most case (but not fully eliminate them), so
396 for normal use the default 'ifup' should work fine.
398 Other distributions have very different version of ifup, and I
399 have not tried those (tell me about it).
401 4) Installing Hotplug for Debian Sarge (testing/unstable)
402 ---------------------------------------------------------
403 Thanks to the great work of many people, Debian Sarge has all
404 the necessary packages and hotplug support, and will work mostly 'out
406 You will need to install the following packages :
410 While the installation of Hotplug is simple, its configuration
411 may seem complex. The current network Hotplug script has 3 modes,
412 'all', 'auto' and 'hotplug', however for our purpose they all produce
413 the same results when configured. This is controlled by the variable
414 NET_AGENT_POLICY in /etc/default/hotplug.
416 In the mode "all", all interfaces are processed by
417 'ifup'. This will work without further configuration.
419 In the mode "auto", only interfaces listed in a auto statement
420 in /etc/network/interfaces will be processed by 'ifup'. If you choose
421 this mode, you need to put in /etc/network/interfaces a statement auto
422 with the complete list of all interfaces.
423 --------- /etc/network/interfaces -----------
424 # Enable Hotplug support for "auto" mode (Sarge and later)
425 auto eth0 eth1 eth2 eth3 eth4 wlan0 wlan1 prism0 prism1 airo0 airo1
426 ---------------------------------------------
427 Unfortunately, this will make 'ifup' complain at boot time
428 that it can't find those interfaces. This is why I don't recommend
431 In the mode "hotplug", hotplug network events are ignored by
432 ifup by default. To enable them, therefore making this mode equal to
433 "all", you will need to add the following lines to
434 /etc/network/interfaces :
435 --------- /etc/network/interfaces -----------
436 # Enable Hotplug support for "hotplug" mode (Sarge and later)
439 ---------------------------------------------
441 5) Installing Hotplug for Debian 3.0
442 ------------------------------------
443 Debian 3.0 doesn't come by default with hotplug, but the
444 hotplug package is available as regular Debian package (on the CD or
445 downloadable via apt-get), so you can just install that.
447 Unfortunately, this version of hotplug is not fully compatible
448 with kernel 2.6.X. You will need to do the following modifications to
449 the file /etc/hotplug/net.agent.
451 ------- /etc/hotplug/net.agent ------------------
452 --- net.agent-d1 Fri Feb 20 18:18:05 2004
453 +++ net.agent Fri Feb 20 18:22:50 2004
454 @@ -26,7 +26,7 @@ if [ "$INTERFACE" = "" ]; then
462 # interfaces that are registered after being "up" (?)
463 @@ -52,7 +52,7 @@ register)
464 mesg $1 $ACTION event not handled
469 # Assume that we want to run ifdown no matter what,
470 # because it is not going to remove the data from the
471 # ifstate database otherwise.
472 -------------------------------------------------
474 Compared to the version in Sarge, this older version of
475 hotplug is much more basic, and doesn't have any scanning at boot time
476 and doesn't need to be enabled in /etc/network/interfaces.
478 6) Installing hotplug, other cases
479 ----------------------------------
480 The canonical version of hotplug is available at :
481 http://linux-hotplug.sourceforge.net/
483 Most distributions have various version of hotplug with
484 various modifications on top of the canonical version, and chances are
485 that the canonical version won't completely work on your system.
486 All these various changing versions make it difficult for me
487 to tell what exactly need to be changed in the hotplug scripts to make
490 Some version of hotplug will do scan at boot time, see section
491 (4) for my comments on this.
493 My guess is that in a few release, all these problems will
494 sort themselves out. Just be patient.
496 7) Dealing with 'init' hotplug
497 ------------------------------
498 In addition to the standard kernel Hotplug events, modern
499 versions of the Hotplug scripts add init scripts that scan the system
500 buses and generate pseudo Hotplug events. For the PCI buses, the
501 script /etc/hotplug/pci.rc is run after the boot, for the USB bus,
502 /etc/hotplug/usb.rc is run.
503 The end result is that the Hotplug subsystem will also attempt
504 to configure built-in devices :
506 2) Init runs, start to initialise the OS
507 3) /etc/hotplug/pci.rc runs, generate pseudo Hotplug event
508 4) /etc/hotplug/pci.agent loads driver module
509 5) Driver module initialises, creates new network device
510 6) Kernel generates Network Hotplug event
511 7) /etc/hotplug/net.agent runs, configure network device
513 At this point, you realise that at initialisation, both
514 Hotplug and the regular init scripts (see "CONFIGURATION FROM INIT
515 SCRIPTS") are trying to configure the same devices in parallel. This
516 may create problem, and it is totally redundant.
517 Another reason I don't like this mechanism is that it blindly
518 attempt to load drivers for all hardware present on the system, and
519 don't use the configuration in /etc/modules.conf to select the proper
520 driver. It's fairly common to have multiple driver for some hardware,
521 and because of Murphy's law, Hotplug will usually load the wrong
522 one. It's also fairly common to have hardware on the system that
523 doesn't need enabling (for example, the IDE controller on my SCSI
524 machine), not loading the driver makes your kernel smaller and boot
526 Unfortunately, Hotplug did not provide a simple way to disable
527 such a feature. More importantly, there is no way to selectively
528 disable it (let say, disabled for network, enabled for sound).
530 One way to disable this functionality is to delete or rename
531 the files /etc/hotplug/pci.rc and /etc/hotplug/usb.rc.
533 8) Making hotplug scripts call ifrename
534 ---------------------------------------
535 The last hotplug step is to make sure that 'ifrename' is run
536 by the hotplug subsystem at the right time. As before, we want to run
537 it just before calling 'ifup'.
538 The latest version of the hotplug scripts have this
539 integrated. However, you need to check that the path they use for
540 calling 'ifrename' is the proper one on your system. And, for older
541 versions of hotplug scripts, you will need to add this support
544 Check the path for ifrename :
545 --------------------------
548 --------------------------
550 The patch to add 'ifrename' to hotplug looks like :
552 ------- /etc/hotplug/net.agent ------------------
553 --- net.agent-s2 Fri Feb 20 17:18:46 2004
554 +++ net.agent Fri Feb 20 17:32:43 2004
555 @@ -40,6 +40,21 @@ add|register)
556 # we can't do much here without distro-specific knowledge
557 # such as whether/how to invoke DHCP, set up bridging, etc.
559 + # Run ifrename as needed - Jean II
560 + # Remap interface names based on MAC address. This workaround
561 + # the dreaded configuration problem "all my cards are 'eth0'"...
562 + # This needs to be done before ifup otherwise ifup will get
563 + # confused by the name changed and because iface need to be
564 + # down to change its name.
565 + if [ -x /sbin/ifrename ] && [ -r /etc/iftab ]; then
566 + debug_mesg invoke ifrename for $INTERFACE
567 + NEWNAME=`/sbin/ifrename -i $INTERFACE`
568 + if [ -n "$NEWNAME" ]; then
569 + debug_mesg iface $INTERFACE is remapped to $NEWNAME
576 if [ -x /sbin/ifup ]; then
577 -------------------------------------------------
579 If your hotplug scrips already include ifrename support, you
580 should find a section in /etc/hotplug/net.agent looking like the patch
581 above. Otherwise, just cut'n'paste the patch above in the right place.
582 The path for 'ifrename' is used twice above, so don't forget
583 to modify both occurences...
586 9) Loading driver modules
587 -------------------------
588 Wow ! The most difficult part is done.
589 In theory, you don't need to do any specific configuration for
590 the driver modules to be loaded. The 'pci.agent' and 'usb.agent'
591 should load the right driver module for you.
592 Also, you don't need to define aliases in /etc/modprobe.conf,
593 it's useless (and may be counter productive).
595 If you use driver compiled statically in the kernel, you also
598 10) Renaming interfaces
599 -----------------------
600 We still use ifrename to assign names to interfaces. The
601 configuration of 'ifrename' is the same. To keep the possibility of
602 having multiple wireless cards (one in each CardBus slot), we use
603 wildcards in both the MAC address and the name :
605 --------- /etc/iftab -----------------------
606 # SMC 2835W wireless CardBus card
607 prism* mac 00:30:B4:*
608 ---------------------------------------------
610 If you insert two cards, they would be named prism0 and
611 prism1. Note that 'name wildcarding' is a feature only available in
612 2.6.X, so if you use 2.4.X you will need to be explicit and list each
615 --------- /etc/iftab -----------------------
616 # SMC 2835W wireless CardBus card
617 prism0 mac 00:30:B4:64:27:8B
618 prism1 mac 00:30:B4:64:27:8D
619 ---------------------------------------------
621 11) Configuring interfaces
622 -------------------------
623 At this point, configuration of Hotplug interfaces is done
624 just like their built-in counterparts. This part is still distribution
625 specific, and still already document in the file DISTRIBUTIONS.txt..
627 In Debian, you would need to modify the file
628 /etc/network/interfaces like this :
630 --------- /etc/network/interfaces -----------
631 # Enable Hotplug support (Sarge and later)
635 # SMC 2835W wireless CardBus card
636 iface prism0 inet static
639 netmask 255.255.255.0
641 wireless-essid THE_ESSID
644 ---------------------------------------------
646 Now, just cross your finger and plug the card in the slot...
648 PCMCIA INTERFACES (16 bits)
649 ---------------------------
650 The Pcmcia subsystem has quite some legacy, and can use
651 various configuration procedure. The Pcmcia subsystem fully use
652 hotplug for 32 bits card (if you are using the kernel Pcmcia modules,
653 which is the only option for 2.6.X). For 16 bits cards, we can't make
654 them fully hotplug yet and need the cardmgr and /etc/pcmcia directory,
655 however we can make their network configuration use hotplug.
657 To use Hotplug network configuration with 16 bits Pcmcia
658 cards, first make sure the Pcmcia subsystem is properly configured and
659 that cardmgr load the right module (in most case, it should). Then,
660 make sure that you don't have any configuration entries in
661 /etc/pcmcia/network.opts and /etc/pcmcia/wireless.opts. Make sure that
662 none of entries in your system network configuration use 'eth0' or
663 'wlan0' (in /etc/network/interfaces for Debian users).
664 Then, just follow the procedure described above for
665 "Configuration Using Hotplug" to configure your network cards.
667 You might want a little bit of explanation on why this magic
668 will work (which would help in case it doesn't work).
669 There is two types of Pcmcia network configuration scripts,
670 available as /etc/pcmcia/network. The original Pcmcia script configure
671 network cards using options found in /etc/pcmcia/network.opts and
672 /etc/pcmcia/wireless.opts. Most distributions replace it with a script
673 calling 'ifup'. By making sure that network.opts and wireless.opts are
674 "empty", we neutralise the first set of scripts. By making sure no
675 system configuration uses 'eth0' or 'wlan0', we neutralise the second
676 set of scripts, the script would call 'ifup' with the default
677 interface name, which is usually 'eth0', ifup would not find a
678 configuration for it and would just ignores it.
679 The card would still be configured because hotplug network
680 events are generated for every interfaces, not only for devices
681 managed by hotplug. So, net.agent would receive an event and perform
682 the necessary steps to configure it.
684 Personally, I'm still using the original Pcmcia scripts for my
685 Pcmcia cards as described in the file PCMCIA.txt, because I will
686 migrate my complex configurations over time.
687 You can also decide to not use Hotplug for Pcmcia cards and
688 modify the distribution Pcmcia scripts in /etc/pcmcia/* to handle
689 Pcmcia cards properly. You would need to modify /etc/pcmcia/network to
690 add 'ifrename' before 'ifup' the same way it was done for
691 /etc/hotplug/net.agent. But, as in the long term Pcmcia will migrate
692 to Hotplug, I would not bother...
694 MANUAL LOADING, DOCKING STATIONS
695 --------------------------------
696 Manual loading is used for built-in network interfaces that
697 are only use at specific time, and that you want disabled the rest of
698 the time. We assume that you still use modules so that when the
699 interface is not used you can remove the driver from the kernel.
701 First, you need to set the configuration for those interfaces,
702 the same way it's done for other network interfaces. The main
703 difference is that you need to specify that those interfaces should
704 not be enabled at boot time. It's also a good idea to disable Hotplug
706 With Debian, you just need to make sure that the 'auto"
707 keyword doesn't apply to this interface.
708 --------- /etc/network/interfaces -----------
709 # AMD AMD PCnet LANCE PCI card
711 ---------------------------------------------
713 If you use driver statically built in the kernel, you can just
714 enable and disable those interfaces with 'ifup ethX' and 'ifdown ethX'.
716 If you use both a modular system and 'ifrename', you will need
717 to change your habits when enabling those devices. The classical 'ifup
719 If you don't use Hotplug, you need to do :
720 -----------------------------------
724 -----------------------------------
725 If you use hotplug, you only need to do :
726 -----------------------------------
728 -----------------------------------
730 On the other hand, disabling the interface has not changed :
731 -----------------------------------
734 -----------------------------------
735 Using "modprobe -r" make sure that if the driver is composed
736 of multiple module all the modules are unloaded.
738 Docking stations for laptops may contain built-in
739 interfaces. My previous laptop had one, and Linux had no support for
740 it. To be able to simply manage my docking station, I had created two
741 little scripts to enable and disable my network interface.
742 After docking, you would run :
743 -------- /sbin/dock ----------------------------
748 ------------------------------------------------
749 And prior to undocking, you would run :
750 -------- /sbin/undock ----------------------------
754 ------------------------------------------------
755 Thanks to 'ifrename', the network interface in your dock will
756 always be properly configured regardless of if you have a Pcmcia
757 network card in the Pcmcia slot or not.
759 SCHEMES (MULTI-CONFIG)
760 ----------------------
761 Most Ethernet cards will only connect to a single network, or
762 can use DHCP to be auto-configured. With Wireless Cards, it's much
763 more likely that you will need multiple configurations, for example at
764 work, at home and on-the-go.
766 Most distributions have various level of support for such
767 schemes. Some distributions offer simple network schemes, while other
768 offer "overall" schemes changing the whole configuration. I document
769 the support for schemes in various distributions in the file
772 You can also use tools such as IfPlugd, WapRoamd or
773 Wlandetect. Those tools are a kind of "wireless-DHCP", they attempt to
774 automatically detect the proper wireless configuration and apply
775 it. Most will also attempt to detect network changes.
776 The main limitation of those tools is that they offer very
777 little manual control. If two valid alternatives are possible, you
778 can't switch between them. If a configuration can't be detected, they
780 That's the same concept as using DHCP versus Static IP
781 addresses. Some people are very happy with DHCP, my style is Static IP
784 If you use Debian and want to use simple manual schemes, these
785 are the things you need to do.
786 1) Make sure that 'ifscheme' and 'ifscheme-mapping' are
787 installed on the system. You may find them in a separate tar file on
789 2) Check the path for 'ifscheme-mapping' (using whereis).
790 3) Modify you /etc/network/interface to add proper mapping and
793 ------- /etc/network/interfaces ----------------------
794 # Enable Hotplug support (Sarge and later)
798 # SMC 2835W wireless CardBus card
800 script /sbin/ifscheme-mapping
802 iface prism0-any inet dhcp
804 wireless-mode managed
806 iface prism0-adhoc inet static
809 netmask 255.255.255.0
811 wireless-essid THE_ESSID
815 iface prism0-other inet static
818 netmask 255.255.255.0
819 broadcast 10.10.10.255
820 wireless-essid ANOTHER_ESSID
822 wireless-key "s:secure"
823 ------------------------------------------------------
827 A lot of modern wireless card don't have built in firmware and
828 need firmware loading. Recent kernel (2.6.X) have a firmware
829 loader. These are a few notes on how to use it.
831 First, read the documentation coming with your driver, because
832 each driver has specificities (like the name of the firmware file it
835 You need to compile your kernel with firmware loading
836 (CONFIG_FW_LOADER in "Generic Driver Options"). If your driver was
837 built from the kernel, chances are that it enabled this feature
838 already. Make sure you boot from this new kernel.
840 The 'sysfs' file system must be mounted. The easiest is to
841 mount it at boot time, add a line for it in /etc/fstab :
843 -------- /etc/fstab ------------------------------
844 sysfs /sys sysfs defaults 0 0
845 --------------------------------------------------
847 Then, you add the firmware file in the directory where it's
848 expected, which is /usr/lib/hotplug/firmware/ in most cases.
850 Most distributions nowadays have a version of the Hotplug
851 scripts that knows how to deal with firmware. If it is not the case,
852 just grab the 'firmware.agent' file from an alternate source and copy
853 it into your /etc/hotplug directory (make sure it's executable).
854 You can try the canonical version :
855 http://linux-hotplug.sourceforge.net/
856 Or Debian's version :
857 http://packages.debian.org/unstable/admin/hotplug
859 Note that firmware loading will usually only work with
860 interfaces that are fully managed by Hotplug. This is the only way to
861 ensure the that proper sequence of action is happening in the right
862 order every time. Firmware loading will usually not work properly for
863 interfaces configured in the init scripts.
864 This means that if you have a built-in interface that require
865 firmware loading, you should just use manage those interfaces like
866 removable interfaces (see section above). However, interface
867 configuration need to be explicitely triggered at boot time.
869 One possibility is to set-up Hotplug to be run from the init
870 script at boot time. This is usually an option for recent
871 distributions (it's not the case for Hotplug in Debian 3.0). But, we
872 have seen that this has some issues.
873 The other possibility is to use an hybrid between the init
874 script method and the hotplug method. First, you need to add an alias
875 for the driver in /etc/modprobe.conf. Then, you need to specify a
876 mapping for this interface in /etc/iftab, and specify a configuration
877 for this interface and that that it is enabled at boot time. Lastly,
878 you make sure that the network init scripts run 'ifrename
879 -p'. 'Ifrename' will trigger the module to load, and all the Hotplug
880 events will be generated properly to configure the interface.
882 DEVICES WITH MULTIPLE NAMES
883 ---------------------------
884 Some wireless drivers offer multiple network interfaces for
885 the same device. A classical example is the Aironet driver that
886 creates a 'ethX' and 'wifiY' for each card.
888 'ifrename' allow you a finer selection of interfaces than
889 'nameif'. For example, to only rename the pseudo-Ethernet network
890 interface name of the Aironet driver, you would do :
892 --------- /etc/iftab -----------------------
893 # Cisco Aironet 350 wireless Pcmcia card
894 airo* mac 00:07:0E:* arp 1
895 ---------------------------------------------
897 After that, your device would be available through 'eth0' and
900 You can rename both interfaces. You just need to remember that
901 'ifrename' start matching from the last line of the file, so you would
903 --------- /etc/iftab -----------------------
904 # Cisco Aironet 350 wireless Pcmcia card
906 airo* mac 00:07:0E:* arp 1
907 ---------------------------------------------
909 The current version of 'ifrename' support only the most useful
910 selectors, and is architectured such as adding selectors is relatively
911 trivial. If you find a case that 'ifrename' can't handle, you should
914 DEVICES WITHOUT MAC ADDRESSES
915 -----------------------------
916 Most Ethernet and Wireless devices have a fixed and unique MAC
917 address, and it is therefore advised to name them based on this
918 criteria. However, there is also network interfaces that don't have a
919 fixed and unique MAC address, for example Ethernet over USB, IP over
920 FireWire, PPP and tunnel interfaces.
921 The driver for those devices create the interface with a name
922 specific to the driver, such as ppp* for PPP interfaces and usb* for
923 Ethernet over USB, and therefore they are easy to identify and
924 configure, and few users feel the need to rename them. Moreover, some
925 of them, such as PPP, have their own configuration scripts and
926 methodology addressing their unique needs.
928 There is a few cases where you might want to rename interfaces
929 withour MAC addresses. One example is two Ethernet over USB
930 dongles. The way to do this is to use alternate ifrename
931 selectors. Choosing the right selector depend on what you want to
933 A quick theoretical example to illustrate :
934 --------- /etc/iftab -----------------------
935 # All other usbnet devices
937 # Specific usbnet devices
938 usb-p firmware "Prolific PL-2301/PL-2302"
939 usb-4 bus-info usb-00:02.0-1.4
940 ---------------------------------------------
944 If your interface doesn't show up as expected with ifconfig,
945 you will need to find out why. First, you need to be familiar with the
946 sequence of actions in the system and find which one did not happen.
948 You need to check if the driver module(s) was loaded using
951 You need to check if the interface was properly renamed with
952 'ifrename'. You can use 'ifrename -D -V' to debug your /etc/iftab.
953 Get the the list of interfaces on your system with 'cat
954 /proc/net/dev', and check if an interface is using the name you
955 assigned or 'eth0'. Check any suspicious interfaces with 'ifconfig
956 eth0', and check its MAC address. Note that some rare drivers don't
957 have a proper MAC address before brought up, which fools ifrename.
958 Verify that no line in /etc/iftab matches the all-zero MAC
959 address. The all-zero MAC address matches the loopback interface 'lo'
960 and various pseudo network devices, renaming the loopback interface is
963 You need to check which configuration was given to the
964 interface using 'ifconfig' and 'iwconfig'.
966 The Hotplug subsystem has also good debugging facilities.
967 To enable Hotplug debugging, just make sure the variable DEBUG
968 is defined in /sbin/hotplug :
969 --------- /sbin/hotplug ------------------------------
970 --- /sbin/hotplug-old Tue Mar 26 09:00:20 2002
971 +++ /sbin/hotplug Fri Feb 20 18:40:38 2004
976 -# DEBUG=yes export DEBUG
977 +DEBUG=yes export DEBUG
979 if [ "$DEBUG" != "" ]; then
980 mesg "arguments ($*) env (`env`)"
981 ------------------------------------------------------
982 Then, you can check your message logs for Hotplug events with
983 'tail -f /var/log/messages'. Verify that the various Hotplug events
984 happen as expected (pci, firmware, net...), and verify the log
985 messages from 'net.agent'.