1 Sane network interface management with Hotplug
2 ----------------------------------------------
6 In the old days all wireless cards were managed by the
7 excellent Pcmcia subsystem and its rich configuration scripts, and
8 life was good. 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 system.
12 The USB subsystem already uses Hotplug. The Pcmcia subsystem
13 is migrating to it : CardBus cards (32 bits) already use Hotplug,
14 whereas Pcmcia cards (16 bits) still use the old Pcmcia scripts.
15 The Hotplug system is still in its infancy, but already shows
16 some good promise. Most users are disappointed at first by its
17 apparent lack of features compared to the Pcmcia scripts. In this
18 document, we will show how to fully exploit the Hotplug system and try
19 to implement the equivalent of all the functionality of the Pcmcia
24 The target audience of this document is mostly power users and
25 distribution maintainers, but it should give enough clues to help
26 newbies. You should have read and understood DISTRIBUTIONS.txt. The
27 procedures described here are more advanced than the simple
28 configuration described in DISTRIBUTIONS.txt.
29 The main focus is of course on removable wireless interfaces,
30 but we will to talk about network interface management in general, so
31 this should apply also to built-in Ethernet cards.
35 Let's assume a Linux system and two or more network devices,
36 Device A and Device B. Those devices may be built-in or removable,
37 they may be present or absent from the system at any time, and they
38 may activated in any particular order.
39 The user wants to assign Configuration A to Device A and
40 Configuration B to Device B, without the possibility that Device A
41 gets assigned Configuration B.
42 Different users may have different definitions of what is
43 Device A. For some, it's a specific instance of a specific hardware,
44 for others any hardware that meets some criteria (a wireless card, an
46 The user may also want to have multiple configurations for a
47 given device such that the chosen configuration depends on various
48 factors, just as with the old Pcmcia schemes. Device A may need
49 Configuration A1 or Configuration A2 depending on those factors.
50 By default, all network interfaces are created using default
51 interface names (starting at "eth0" and going up). I call that the
52 "all my cards are eth0" problem : im most distributions, "eth0" points
53 to a single fixed configuration in the configuration
54 database. Clearly, this won't satisfy our requirements.
58 The distribution I use is Debian 3.0, and some parts of what I
59 say here will be specific to it. However, it should be easy to
60 translate this material to other distributions and I welcome additions
63 The example system is as follows :
64 o Linux 2.6.X SMP kernel with hotplug support
65 o Fully modular system (all network drivers as modules)
66 o PCI Ethernet card : AMD PCnet LANCE (pcnet32 - eth4)
67 o PCI Ethernet card : HP 100VG J2585B (hp100 - eth2)
68 o ISA Wireless card : Old AT&T Wavelan (wavelan - eth3)
69 o ISA-Pcmcia bridge : VADEM VG-469 (i82365 - slot 0)
70 o PCI-CardBus bridge : Ricoh RL5c475 (yenta_socket - slot 2)
71 o Pcmcia 802.11 card : Aironet 350 (airo_cs - eth0)
72 o Pcmcia 802.11 card : Lucent Orinoco (orinoco_cs - eth0)
73 o CardBus 802.11 card : SMC 2835W (prism54 - prism0)
75 This system just happens to be my Linux development box. It
76 has enough interfaces to make it interesting. All the examples I
77 present in this document are extracted from this system.
81 Most of the concept and tricks presented here are not really
82 new. The main contribution is to integrate them.
84 1) Removable network interfaces are managed by Hotplug
85 (Pcmcia, CardBus, USB...). We can't assume that those interfaces are
86 always present in this system and available at boot time (Pcmcia cards
87 were not made to be soldered in the Pcmcia slot). Therefore Hotplug is
89 2) Built-in PCI and ISA cards are managed by the init scripts,
90 as they have always been. The ISA subsystem will never have Hotplug
91 support, and hotplug is not necessary for PCI cards.
92 3) Built-in devices that are disable most of the time should
93 be enabled manually by the user. Therefore both Hotplug and the init
94 scripts should ignore those devices by default.
95 4) (1), (2) and (3) must be compatible on the same system and
96 play nice with each other.
98 5) A well defined and consistent network interface name is
99 assigned to each network hardware interface using 'ifrename'. Device A
100 is always named 'ethA' (or whatever name you like such as
102 6) No interface is called 'eth0' (or 'wlan0'). Any unknown
103 device would be 'eth0', so known devices should be called something
105 7) Multiple configurations for a single interface (schemes)
106 are managed by the ifup/ifdown subsystem.
108 CONFIGURATION FROM INIT SCRIPTS
109 -------------------------------
110 It may seem paradoxical, but before setting up Hotplug, we
111 need to make sure that the initialisation of network cards via init
112 scripts is done properly and doesn't get in the way of the Hotplug
114 The configuration of network cards via init scripts is the
115 traditional way networking is initialised in Linux. The advantage of
116 this method is that it's very well documented and understood, and has
117 not changed much over the years. Unfortunately, it doesn't adequately
118 support removable cards.
120 The init scripts perform the following 3 functions in order :
121 1) Load necessary driver modules
122 2) Rename interface to name chosen by the user
123 3) Configure those network interfaces
127 Configuration from init scripts is applicable to any built-in
128 network interface (ISA, PCI...), i.e., interfaces available at boot
129 time and that will never be removed from the system.
130 The Hotplug subsystem also has 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
135 2) Loading driver modules (if/as needed)
136 ----------------------------------------
137 Most distributions build the kernel drivers as modules. This
138 modular setup allows to minimise the amount of memory used by the
139 system and the flexible loading/unloading of drivers.
140 You can also compile your kernel with static drivers
141 (non-modular). In that case, the driver will always be available in
142 the kernel, you don't need to configure the module subsystem, so you
143 can skip directly to the next section.
145 There are 3 alternatives to manage device drivers as
147 1) Some distributions have an explicit list of modules
148 that are loaded at boot time. If you want to use that feature you need
149 to check the documentation of your distribution.
150 2) Some system, such as Hotplug, Discover or Kudzu,
151 can scan the various buses of the PC and load the appropriate
152 drivers. This is mostly configuration-free, but may not support all
153 devices and may load unnecessary modules.
154 3) The module subsystem also allows to load modules
155 'on-demand'. When an application try to access or configure a network
156 interface, the corresponding module is loaded.
158 I personally prefer to use the 'on-demand' feature of the
159 module subsystem, as this allow you to not have to specify a static
160 list of modules that need to be loaded, and only modules really needed
161 are loaded which saves kernel memory. You can also choose which module
162 to load when there are multiple modules available that support your
163 hardware (which happens quite often).
165 With kernel 2.6.X the module subsystem is configured in the
166 file /etc/modprobe.conf or files in the directory /etc/modprobe.d/. To
167 configure 'on-demand' module loading, on my test system I need to add
168 to the following lines to the configuration :
170 --------- /etc/modprobe.d/local or /etc/modprobe.conf ------
171 # HP 100VG J2585B PCI card
174 # AMD AMD PCnet LANCE PCI card
177 # Old AT&T Wavelan ISA card
179 options wavelan io=0x390 irq=15
180 ------------------------------------------------------------
182 Your distribution may already have lines for your interfaces,
183 either replace these or make sure they are correct (some distributions
184 are notorious for picking the wrong driver name in some cases). This
185 file also contains configuration for lot of other subsystems,
186 obviously you don't want to touch that.
187 In this file, you put the name you would like the interface to
188 have (we'll fix that in a minute). Note that for modern PCI cards this
189 is much more straightforward than for old ISA cards.
191 3) Installing 'ifrename'
192 ------------------------
193 You will need to install ifrename on your system. 'ifrename'
194 is part of the Wireless Tools package (version 27 and later) and is a
195 complete rewrite of the now obsolete 'nameif'.
196 Some distributions, such as Debian Sarge, offer a separate
197 package for 'ifrename', and in this case you should just install this
198 package. Other distributions may include ifrename as part of their
199 'wireless-tools' package (this should be the case for Gentoo, Fedora
200 and Mandrake). Other distributions, such as Debian 3.0, don't include
201 ifrename at all, so you should compile yourself a recent version of
202 Wireless Tools (v27 or later) and install it.
204 In any case, you should verify that 'ifrename' is properly
205 installed and check the path needed to call it :
206 --------------------------
209 --------------------------
210 Most distributions will install 'ifrename' in '/sbin', while if
211 you compile your own wireless tools, it will be in '/usr/local/sbin'.
213 4) Making the boot scripts call 'ifrename'
214 ------------------------------------------
215 You need to make sure 'ifrename' is run at boot time. Most
216 distributions don't do that yet by default.
217 This is a part that is distribution-specific, so you will need
218 to look into your own init files, or ask people familiar with your
219 distribution. It will need to run just before the call to 'ifup' or
222 In Debian 3.0 and Debian Sarge, it needs to be run from
223 /etc/init.d/networking, which is not the default. The necessary patch
226 ----------------------------------------------------------------
227 --- networking-orig Wed Feb 18 13:56:23 2004
228 +++ networking Fri Feb 20 14:51:06 2004
229 @@ -120,6 +120,15 @@ case "$1" in
233 + # Optionally remap interface names based on MAC address.
234 + # '/sbin/ifrename' is part of wireless-tools package.
235 + # /etc/iftab is currently not created by default. Jean II
236 + if [ -x /sbin/ifrename ] && [ -r /etc/iftab ]; then
237 + echo -n "Remapping network interfaces name: "
242 echo -n "Configuring network interfaces: "
245 ----------------------------------------------------------------
246 Don't forget to set the appropriate path to the ifrename
247 command (see step (3) above).
249 You may also want to also set the proper options for ifrename
250 (check the man page).
251 The option '-p' enables module autoloading compatibility.
252 The default version of 'ifrename' also includes some special
253 Debian support : using "ifrename -p -d", only the proper modules are
254 loaded. If you are using Debian, you should use this option.
256 5) Renaming interfaces
257 ----------------------
258 As stated above, we use 'ifrename' to assign names to
261 First, you need to get the MAC address of each of your
262 interfaces. You can read the MAC address on the label of the card, or
263 display it using the 'ifconfig -a' command. Remember that the
264 interface won't load yet with the proper name, so you may need to do a
267 -----------------------------
270 eth0 Link encap:Ethernet HWaddr 00:10:83:34:BA:E5
272 -----------------------------
274 The configuration of 'ifrename' is simple, you just specify
275 which name should be used for each MAC address in the file
278 --------- /etc/iftab ------------------------
279 # HP 100VG J2585B PCI card
282 # Old AT&T Wavelan ISA card
285 # AMD AMD PCnet LANCE PCI card
287 ---------------------------------------------
289 The '*' in the MAC address is a wildcard and allows me to
290 replicate my configuration between multiple identical computers. If
291 you have to manage large number of computers (like a rack of servers
292 or clusters), then you may want to look at other selectors offered by
295 To test that ifrename works, do the following :
296 o Load all your drivers, see section (2)
297 o Check /proc/net/dev to see which interface exist
298 o Bring all interfaces down : ifconfig ethX down
300 o Check each interface with ifconfig
301 o Bring all interfaces up : ifconfig ethX up
303 6) Configuring interfaces
304 -------------------------
305 Most likely, your distribution is already doing this part
306 properly. Just assign the proper IP and wireless configuration to each
307 of the interface names you have chosen.
308 This part is distribution specific, and I already document it
309 in the file DISTRIBUTIONS.txt.
311 In Debian, you would need to modify the file
312 /etc/network/interfaces so that it looks something like this :
314 --------- /etc/network/interfaces -----------
315 # AMD PCnet LANCE PCI card
319 # HP 100VG J2585B PCI card
321 iface eth2 inet static
323 netmask 255.255.255.0
326 ---------------------------------------------
328 This was the last part. Now, at your next boot, all your
329 interfaces should be assigned the proper name and the proper
332 CONFIGURATION VIA HOTPLUG
333 -------------------------
334 Dealing with removable interfaces is similar to dealing with
335 built-in interfaces, the main difference is that we will use the
336 Hotplug scripts instead of the init scripts. Another difference is
337 that it will likely require more work on your part because most
338 distributions are not fully ready for it.
342 The Hotplug configuration method is the best choice for any
343 removable network interface, such as :
344 o Pcmcia (16 bits) network cards
345 o CardBus (32 bits) network cards
346 o USB network dongles
347 o Hot-PCI network cards
348 It may also be used to manage other types of network
349 interfaces, although it may not be the best choice for them.
353 Conceptually, Hotplug is very simple. When something
354 interesting happens, the Linux kernel generates an Hotplug event. This
355 runs the proper script from the /etc/hotplug directory.
356 There are 3 types of Hotplug events we care about :
357 o PCI event : a CardBus device is added or removed
358 from the system. The script /etc/hotplug/pci.agent is run.
359 o USB event : a USB device is added or removed
360 from the system. The script /etc/hotplug/usb.agent is run.
361 o Network event : a network interface is added or
362 removed from the system. The script /etc/hotplug/net.agent is run.
364 If we insert a CardBus network card in the system, the
366 1) Kernel detects new CardBus device
367 2) Kernel generates PCI Hotplug event
368 3) /etc/hotplug/pci.agent runs, finds proper driver module
369 4) /etc/hotplug/pci.agent loads driver module
370 5) Driver module initialises, creates new network device
371 6) Kernel detects new network device
372 7) Kernel generates Network Hotplug event
373 8) /etc/hotplug/net.agent runs, configures network device
374 The sequence of events is similar for removals and USB devices.
376 3) Make sure ifup does not deadlock
377 -----------------------------------
378 <Most people should ignore this part>
379 The first problem is that we need to make sure the command
380 'ifup' does not deadlock by calling itself re-entrantly. If the system
381 has built-in interfaces, the 'ifup' may reenter itself at boot time
383 1) Init scripts start running
384 2) Init script calls 'ifup -a' to initialise built-in
386 3) 'ifup' auto-loads driver module for built-in network
388 4) Driver module initialises, creates new network device
389 5) Kernel generates Network hotplug event
390 6) /etc/hotplug/net.agent runs, call 'ifup eth4'
391 Note that you can produce the same reentrancy if you call ifup
392 manually on an interface which module is not yet loaded.
394 The default version of 'ifup' for Debian 3.0 and Debian Sarge
395 is not reentrant and can therefore deadlock if not used properly. The
396 patch to make 'ifup' properly reentrant is available here :
397 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=231197
398 Contemporary versions of Debian (Sarge and later) have a
399 net.agent script that contains workarounds to prevents deadlock
400 situations, so for normal use the default 'ifup' should work fine.
402 Other distributions have very different ifup programs and I
403 have not tried those (tell me about it !).
405 4) Installing Hotplug for Debian Sarge (testing/unstable)
406 ---------------------------------------------------------
407 Thanks to the great work of many people, Debian Sarge has all
408 the necessary packages and hotplug support, and will work mostly 'out
410 You will need to install the following packages :
414 While the installation of Hotplug is simple, its configuration
415 may seem complex. The current network Hotplug script has 3 modes :
416 'all', 'auto' and 'hotplug'. However for our purpose they all produce
417 the same results when configured. This mode is controlled by the
418 variable NET_AGENT_POLICY in /etc/default/hotplug.
420 In the mode "all", Hotplug will run ifup for all network
421 events. This will result in failure messages if some interfaces have
422 already been configured by the init scripts. This mode is not
425 In the mode "auto", Hotplug will run ifup only for those
426 interfaces listed in a auto stanza in /etc/network/interfaces. If
427 you choose this mode, you need to put in /etc/network/interfaces a
428 "auto" line for the interfaces you want to control with hotplug.
429 --------- /etc/network/interfaces -----------
430 # Enable Hotplug support for "auto" mode (Sarge and later)
431 auto eth0 eth1 eth2 eth3 eth4 wlan0 wlan1 prism0 prism1 airo0 airo1
432 ---------------------------------------------
433 This will result in some failure message at boot time, the
434 init script will attempt to enable all those interfaces, and generate
435 an error for all those not available at this time. It will also
436 generate an error messages for interface which have already been
437 configured by the init scripts. This mode is also not recommended.
439 In the mode "hotplug", hotplug network events are ignored by
440 ifup by default. To enable them you will need to add the following
441 lines to /etc/network/interfaces :
442 --------- /etc/network/interfaces -----------
443 # Enable Hotplug support for "hotplug" mode (Sarge and later)
446 ---------------------------------------------
448 To enable them for only selected interfaces, e.g., ethA, make
449 /etc/network/interfaces look like this :
450 --------- /etc/network/interfaces -----------
451 # Enable Hotplug support for "hotplug" mode (Sarge and later)
455 ---------------------------------------------
457 5) Installing Hotplug for Debian 3.0
458 ------------------------------------
459 Debian 3.0 doesn't come by default with hotplug, but the
460 hotplug package is available as regular Debian package (on the CD or
461 downloadable in Debian archive), so you can just install that.
463 Unfortunately, this version of hotplug is not fully compatible
464 with kernel 2.6.X. You will need to do the following modifications to
465 the file /etc/hotplug/net.agent.
467 ------- /etc/hotplug/net.agent ------------------
468 --- net.agent-d1 Fri Feb 20 18:18:05 2004
469 +++ net.agent Fri Feb 20 18:22:50 2004
470 @@ -26,7 +26,7 @@ if [ "$INTERFACE" = "" ]; then
478 # interfaces that are registered after being "up" (?)
479 @@ -52,7 +52,7 @@ register)
480 mesg $1 $ACTION event not handled
485 # Assume that we want to run ifdown no matter what,
486 # because it is not going to remove the data from the
487 # ifstate database otherwise.
488 -------------------------------------------------
490 Compared to the version in Sarge, this older version of
491 hotplug is much more basic, and doesn't have any scanning at boot time
492 and doesn't need to be enabled in /etc/network/interfaces.
494 6) Installing hotplug on other distributions
495 --------------------------------------------
496 The canonical version of hotplug is available at :
497 http://linux-hotplug.sourceforge.net/
499 Most distributions have customized hotplug packages and
500 chances are that the canonical version won't completely work on your
501 system. All these various changing versions make it difficult for me
502 to tell what exactly needs to be changed in the hotplug scripts to
503 make them work. However, most should work out of the box.
505 My guess is that in a few releases, all these problems will
506 sort themselves out. Just be patient.
508 7) Dealing with 'init' hotplug
509 ------------------------------
510 In addition to the standard kernel Hotplug events, modern
511 versions of the Hotplug scripts add init scripts that scan the system
512 buses and generate pseudo Hotplug events at boot time. For the PCI
513 buses, the script /etc/hotplug/pci.rc is run, for the USB bus,
514 /etc/hotplug/usb.rc is run.
515 The end result is that the Hotplug subsystem will also attempt
516 to configure built-in devices :
518 2) Init runs, start to initialise the OS
519 3) /etc/hotplug/pci.rc runs, generates pseudo Hotplug event
520 4) /etc/hotplug/pci.agent loads driver module
521 5) Driver module initialises, creates new network device
522 6) Kernel generates Network Hotplug event
523 7) /etc/hotplug/net.agent runs, configures network device
525 At this point, you realise that at initialisation, both
526 Hotplug and the regular init scripts (see "CONFIGURATION FROM INIT
527 SCRIPTS") are trying to configure the same devices in parallel. This
528 may create problems and is totally redundant.
529 Another reason I don't like this mechanism is that it blindly
530 attempts to load drivers for all hardware present on the system and
531 doesn't use the module loader configuration files to select preferred
532 drivers. It's fairly common to have multiple drivers for a given
533 hardware, and because of Murphy's law, Hotplug will usually load the
534 wrong one. It's also fairly common to have hardware on the system that
535 doesn't need enabling (for example, the IDE controller on my SCSI
536 machine), not loading the driver makes your kernel smaller and boot
539 Hotplug does have a way of disabling the loading of drivers
540 on a case by case basis. Drivers listed in /etc/hotplug/blacklist
542 Hotplug can be disabled for a whole subsystem by editing the
543 appropriate .rc script in /etc/hotplug, or just deleting/renaming
546 8) Making hotplug scripts call ifrename
547 ---------------------------------------
548 The last hotplug step is to make sure that 'ifrename' is run
549 by the hotplug subsystem at the right time. As before, we want to run
550 it just before calling 'ifup'.
551 The latest version of the hotplug scripts have this feature
552 integrated. However, you need to check that the path used for calling
553 'ifrename' is the proper one on your system. And, for older versions
554 of hotplug scripts, you will need to add this support yourself.
556 Check the path for ifrename :
557 --------------------------
560 --------------------------
562 The patch to add 'ifrename' to hotplug looks like :
564 ------- /etc/hotplug/net.agent ------------------
565 --- net.agent-s2 Fri Feb 20 17:18:46 2004
566 +++ net.agent Fri Feb 20 17:32:43 2004
567 @@ -40,6 +40,21 @@ add|register)
568 # we can't do much here without distro-specific knowledge
569 # such as whether/how to invoke DHCP, set up bridging, etc.
571 + # Run ifrename as needed - Jean II
572 + # Remap interface names based on MAC address. This works around
573 + # the dreaded configuration problem "all my cards are 'eth0'"...
574 + # This needs to be done before ifup, otherwise ifup will get
575 + # confused by the name change and because iface needs to be
576 + # down to change its name.
577 + if [ -x /sbin/ifrename ] && [ -r /etc/iftab ]; then
578 + debug_mesg invoke ifrename for $INTERFACE
579 + NEWNAME=`/sbin/ifrename -i $INTERFACE`
580 + if [ -n "$NEWNAME" ]; then
581 + debug_mesg iface $INTERFACE is remapped to $NEWNAME
588 if [ -x /sbin/ifup ]; then
589 -------------------------------------------------
591 If your hotplug scripts already include ifrename support then
592 you should find a section in /etc/hotplug/net.agent looking like the
593 patch above. Otherwise, just cut'n'paste the patch above in the right
595 The path for 'ifrename' is used twice above, so don't forget
596 to modify both occurences.
599 9) Loading driver modules
600 -------------------------
601 Wow ! The most difficult part is done.
602 In theory, you don't need to do any specific configuration for
603 the driver modules to be loaded. The 'pci.agent' and 'usb.agent'
604 should load the right driver module for you.
605 Also, you don't need to define aliases in /etc/modprobe.d/* or
606 in /etc/modprobe.conf, it's useless and may be counterproductive.
608 If you use a driver compiled statically in the kernel, you
609 also have nothing to do.
611 10) Renaming interfaces
612 -----------------------
613 We still use ifrename to assign names to interfaces. The
614 configuration of 'ifrename' is the same. To keep the possibility of
615 having multiple wireless cards (one in each CardBus slot), we use
616 wildcards in both the MAC address and the name :
618 --------- /etc/iftab -----------------------
619 # SMC 2835W wireless CardBus card
620 prism* mac 00:30:B4:*
621 ---------------------------------------------
623 If you insert two cards, they would be named prism0 and
624 prism1. Note that 'name wildcarding' is a feature only available in
625 2.6.X and 2.4.30 and later, so if you use older version of 2.4.X you
626 will need to be explicit and list each card separatly :
628 --------- /etc/iftab -----------------------
629 # SMC 2835W wireless CardBus card
630 prism0 mac 00:30:B4:64:27:8B
631 prism1 mac 00:30:B4:64:27:8D
632 ---------------------------------------------
634 11) Configuring interfaces
635 -------------------------
636 At this point, configuration of Hotplug interfaces is done
637 just like their built-in counterparts. This part is still distribution
638 specific, and still already documented in the file DISTRIBUTIONS.txt.
640 In Debian, you would need to modify the file
641 /etc/network/interfaces like this :
643 --------- /etc/network/interfaces -----------
644 # Enable Hotplug support (Sarge and later)
649 # SMC 2835W wireless CardBus card
650 iface prism0 inet static
652 netmask 255.255.255.0
654 wireless-essid THE_ESSID
657 ---------------------------------------------
659 Note that you should not have wireless-* lines if you are
660 using waproamd to set these parameters.
662 Now, just cross your fingers and plug the card in the slot...
664 PCMCIA INTERFACES (16 bits)
665 ---------------------------
666 The Pcmcia subsystem has quite some legacy, and can use
667 various configuration procedures. The Pcmcia subsystem exclusively
668 uses hotplug for 32 bits cards (if you are using the kernel Pcmcia
669 modules, which is the only option for 2.6.X). For 16 bit cards cardmgr
670 is still required for managing the sockets and loading
671 modules. Cardmgr is configured by files in the /etc/pcmcia directory.
673 To use Hotplug network configuration with 16 bits Pcmcia
674 cards, first make sure the Pcmcia subsystem is properly configured and
675 that cardmgr loads the right driver module (in most case, it
676 should). Then, make sure that you don't have any configuration entries
677 in /etc/pcmcia/network.opts and /etc/pcmcia/wireless.opts. Make sure
678 that none of the entries in your system network configuration use
679 'eth0' or 'wlan0' (in /etc/network/interfaces for Debian users).
680 Then, just follow the procedure described above for
681 "Configuration Using Hotplug" to configure your network cards.
683 You might want a little bit of explanation on why this magic
684 will work (which would help in case it doesn't work).
685 There are two types of Pcmcia network configuration scripts,
686 available as /etc/pcmcia/network. The original Pcmcia script
687 configures network cards using options found in
688 /etc/pcmcia/network.opts and /etc/pcmcia/wireless.opts. Most
689 distributions replace it with a script calling 'ifup'. By making sure
690 that network.opts and wireless.opts are "empty", we neutralise the
691 first set of scripts. By making sure no system configuration uses
692 'eth0' or 'wlan0', we neutralise the second set of scripts, the script
693 would call 'ifup' with the default interface name, which is usually
694 'eth0', ifup would not find a configuration for it and would just
696 The card would still be configured because hotplug network
697 events are generated for every interfaces, not only for devices
698 managed by hotplug. So, net.agent would receive an event and perform
699 the necessary steps to configure it.
701 Personally, I'm still using the original Pcmcia scripts for my
702 Pcmcia cards as described in the file PCMCIA.txt, because it still
703 works and I will migrate my complex configurations over time.
704 You can also decide to not use Hotplug for Pcmcia cards and
705 modify the distribution Pcmcia scripts in /etc/pcmcia/* to handle
706 Pcmcia cards with ifrename. You would need to modify
707 /etc/pcmcia/network to add 'ifrename' before 'ifup' the same way it
708 was done for /etc/hotplug/net.agent. But, as in the long term Pcmcia
709 will migrate to Hotplug, I would not bother...
711 MANUAL LOADING, DOCKING STATIONS
712 --------------------------------
713 Manual loading is used for built-in network interfaces that
714 are only use at specific time, and that you want disabled the rest of
715 the time. We assume that you still use modules so that when the
716 interface is not used you can remove the driver from the kernel.
718 First, you need to set the configuration for those interfaces,
719 the same way it's done for other network interfaces. The main
720 difference is that you need to specify that those interfaces should
721 not be enabled at boot time. It's also a good idea to disable Hotplug
723 With Debian, you just need to make sure that the 'auto"
724 keyword doesn't apply to this interface.
726 If you use drivers statically built in the kernel, make sure
727 that ifrename runs at boot time (see CONFIGURATION FROM INIT
728 SCRIPTS). Once it's done, you can just enable and disable those
729 interfaces with 'ifup ethX' and 'ifdown ethX'.
731 If you use both a modular system, make sure that the
732 'on-demand' module loading is properly configured :
734 --------- /etc/modprobe.d/local or /etc/modprobe.conf ------
735 # HP 100VG J2585B PCI card
738 # AMD AMD PCnet LANCE PCI card
740 ------------------------------------------------------------
742 Then, you should instruct 'ifup' to load module and use
743 ifrename prior to configuring the interface, and remove the module
744 when going down. With Debian, this is done with :
746 --------- /etc/network/interfaces -----------
747 # AMD AMD PCnet LANCE PCI card
750 pre-up /sbin/ifrename -p -n eth4
751 post-down /sbin/modprobe -r eth4
753 # HP 100VG J2585B PCI card
755 iface eth2 inet static
757 netmask 255.255.255.0
760 pre-up /sbin/ifrename -p -n eth2
761 post-down /sbin/modprobe -r eth2
762 ---------------------------------------------
764 We use the '-n' option of ifrename to specify the name of the
765 interface after renaming. This assume that the mapping for those
766 interfaces don't use wildcards. The '-p' option make sure ifrename
767 probes the module prior to using it.
768 Using "modprobe -r" make sure that if the driver is composed
769 of multiple module all the modules are unloaded.
771 To enable the interface, just use :
772 -----------------------------------
774 -----------------------------------
775 And to disable the interface :
776 -----------------------------------
778 -----------------------------------
780 This solution is obviously Debian specific, but could be
781 adapted to other distributions. If you can't manage to get your
782 distributions to use those tricks, you can do things manually.
783 If you don't use Hotplug, you enable an interface with :
784 -----------------------------------
788 -----------------------------------
789 If you use hotplug, you only need to do :
790 -----------------------------------
792 -----------------------------------
793 On the other hand, disabling the interface is done with :
794 -----------------------------------
797 -----------------------------------
800 Docking stations for laptops may contain built-in
801 interfaces. My previous laptop had one, and Linux had no support for
802 it. After docking, I was able to bring up the network ISA card in the
804 However, with most laptops and version of Linux, the issue is
805 that after docking, the new devices are not seen. The solutions is to
806 force a rescan of the PCI bus. Documentation is unclear on that, maybe
809 To be able to simply manage my docking station, I had created
810 two little scripts to enable and disable my network interface.
811 After docking, you would run :
812 -------- /sbin/dock ----------------------------
817 ------------------------------------------------
818 And prior to undocking, you would run :
819 -------- /sbin/undock ----------------------------
823 ------------------------------------------------
824 Thanks to 'ifrename', the network interface in your dock will
825 always be properly configured regardless of if you have a Pcmcia
826 network card in the Pcmcia slot or not.
829 SCHEMES (MULTI-CONFIG)
830 ----------------------
831 Most Ethernet cards will only connect to a single network, or
832 can use DHCP to be auto-configured. With Wireless Cards, it's much
833 more likely that you will need multiple configurations, for example at
834 work, at home and on-the-go.
836 Most distributions have various level of support for such
837 schemes. Some distributions offer simple network schemes, while other
838 offer "overall" schemes changing the whole configuration. I document
839 the support for schemes in various distributions in the file
842 You can also use tools such as ifplugd, waproamd or
843 wlandetect. Those tools are a kind of "wireless-DHCP", they attempt to
844 automatically detect the proper wireless configuration and apply
845 it. Most will also attempt to detect network changes.
846 The main limitation of those tools is that they offer very
847 little manual control. If two valid alternatives are possible, you
848 can't switch between them. If a configuration can't be detected, they
850 That's the same concept as using DHCP versus Static IP
851 addresses. Some people are very happy with DHCP, my style is Static IP
854 If you use Debian and want to use simple manual schemes, these
855 are the things you need to do.
856 1) Make sure that 'ifscheme' and 'ifscheme-mapping' are
857 installed on the system. You may find them in a separate tar file on
859 2) Check the path for 'ifscheme-mapping' (using whereis).
860 3) Modify you /etc/network/interface to add proper mapping and
863 ------- /etc/network/interfaces ----------------------
864 # Enable Hotplug support (Sarge and later)
868 # SMC 2835W wireless CardBus card
870 script /sbin/ifscheme-mapping
872 iface prism0-any inet dhcp
874 wireless-mode managed
876 iface prism0-adhoc inet static
879 netmask 255.255.255.0
881 wireless-essid THE_ESSID
885 iface prism0-other inet static
888 netmask 255.255.255.0
889 broadcast 10.10.10.255
890 wireless-essid ANOTHER_ESSID
892 wireless-key "s:secure"
893 ------------------------------------------------------
897 A lot of modern wireless card don't have built in firmware and
898 need firmware loading. Recent kernels (2.6.X) have a firmware
899 loader. These are a few notes on how to use it.
901 First, read the documentation coming with your driver, because
902 each driver has specificities (like the name of the firmware file it
903 requires). Some drivers may offer additional ways to load the
904 firmware, but in the long term things should be standardised around
905 the hotplug method to simplify packaging in distributions.
907 You need to compile your kernel with firmware loading
908 (CONFIG_FW_LOADER in "Generic Driver Options"). If your driver was
909 built from the kernel, chances are that it enabled this feature
910 already. Make sure you boot from this new kernel.
912 The 'sysfs' file system must be mounted. The easiest is to
913 mount it at boot time, add a line for it in /etc/fstab :
915 -------- /etc/fstab ------------------------------
916 sysfs /sys sysfs defaults 0 0
917 --------------------------------------------------
919 Then, you add the firmware file in the directory where it's
920 expected, which is /usr/lib/hotplug/firmware/ in most cases.
922 Most distributions nowadays have a version of the Hotplug
923 scripts that knows how to deal with firmware. If it is not the case,
924 just grab the 'firmware.agent' file from an alternate source and copy
925 it into your /etc/hotplug directory (make sure it's executable).
926 You can try the canonical version :
927 http://linux-hotplug.sourceforge.net/
928 Or Debian's version :
929 http://packages.debian.org/unstable/admin/hotplug
931 Note that firmware loading will usually only work with
932 interfaces that are fully managed by Hotplug. This is the only way to
933 ensure the that proper sequence of action is happening in the right
934 order every time. Firmware loading may not work properly for
935 interfaces configured in the init scripts.
936 This means that if you have a built-in interface that require
937 firmware loading, you should just use manage those interfaces like
938 removable interfaces (see section above). However, interface
939 configuration need to be explicitly triggered at boot time.
941 One possibility is to set-up Hotplug to be run from the init
942 script at boot time. This is usually an option for recent
943 distributions (it's not the case for Hotplug in Debian 3.0). But, we
944 have seen that this has some issues.
945 The other possibility is to use an hybrid between the init
946 script method and the hotplug method. First, you need to add an alias
947 for the driver in /etc/modprobe.conf. Then, you need to specify a
948 mapping for this interface in /etc/iftab, and specify a configuration
949 for this interface and that it is enabled at boot time. Lastly,
950 you make sure that the network init scripts run 'ifrename
951 -p'. 'ifrename' will trigger the module to load, and all the Hotplug
952 events will be generated properly to configure the interface.
954 DEVICES WITH MULTIPLE NAMES
955 ---------------------------
956 Some wireless drivers offer multiple network interfaces for
957 the same device. A classical example is the Aironet driver that
958 creates a 'ethX' and 'wifiY' for each card.
960 'ifrename' allows you a finer selection of interfaces than
961 'nameif'. For example, to only rename the pseudo-Ethernet network
962 interface name of the Aironet driver, you would do :
964 --------- /etc/iftab -----------------------
965 # Cisco Aironet 350 wireless Pcmcia card
966 airo* mac 00:07:0E:* arp 1
967 ---------------------------------------------
969 After that, your device would be available through 'eth0' and
972 You can rename both interfaces. You just need to remember that
973 'ifrename' starts matching from the last line of the file, so you
975 --------- /etc/iftab -----------------------
976 # Cisco Aironet 350 wireless Pcmcia card
978 airo* mac 00:07:0E:* arp 1
979 ---------------------------------------------
981 The current version of 'ifrename' supports only the most useful
982 selectors, but it is architectured such as adding selectors is relatively
983 trivial. If you find a case that 'ifrename' can't handle, you should
986 DEVICES WITHOUT MAC ADDRESSES
987 -----------------------------
988 Most Ethernet and Wireless devices have a fixed and unique MAC
989 address, and it is therefore advised to name them based on this
990 criteria. However, there are also network interfaces that don't have a
991 fixed and unique MAC address, for example Ethernet over USB, IP over
992 FireWire, PPP and tunnel interfaces.
993 The driver for those devices creates the interface with a name
994 specific to the driver, such as ppp* for PPP interfaces and usb* for
995 Ethernet over USB, and therefore they are easy to identify and
996 configure, and few users feel the need to rename them. Moreover, some
997 of them, such as PPP, have their own configuration scripts and
998 methodology addressing their unique needs.
1000 There are a few cases where you might want to rename
1001 interfaces without MAC addresses. One example is two Ethernet over USB
1002 dongles. The way to do this is to use alternate ifrename
1003 selectors. Choosing the right selector depends on what you want to
1005 A quick theoretical example to illustrate :
1006 --------- /etc/iftab -----------------------
1007 # All other usbnet devices
1009 # Specific usbnet devices
1010 usb-p firmware "Prolific PL-2301/PL-2302"
1011 usb-4 bus-info usb-00:02.0-1.4
1012 ---------------------------------------------
1016 If your interface doesn't show up as expected with ifconfig,
1017 you will need to find out why. First, you need to be familiar with the
1018 sequence of actions in the system and find which one did not happen.
1020 You need to check that the driver module(s) was loaded using
1023 You need to check if the interface was properly renamed with
1024 'ifrename'. You can use 'ifrename -D -V' to debug your /etc/iftab.
1025 Get the list of interfaces on your system with 'ifconfig -a'
1026 or 'cat /proc/net/dev', and check if an interface is using the name
1027 you assigned or 'eth0'. Check any suspicious interfaces with 'ifconfig
1028 eth0', and check its MAC address. Note that some rare drivers don't
1029 have a proper MAC address before brought up, which fools ifrename.
1030 Verify that no line in /etc/iftab matches the all-zero MAC
1031 address. The all-zero MAC address matches the loopback interface 'lo'
1032 and various pseudo network devices, renaming the loopback interface is
1035 You need to check which configuration was given to the
1036 interface using 'ifconfig' and 'iwconfig'.
1038 The Hotplug subsystem has also good debugging facilities.
1039 To enable Hotplug debugging, just make sure the variable DEBUG
1040 is defined in /sbin/hotplug :
1041 --------- /sbin/hotplug ------------------------------
1042 --- /sbin/hotplug-old Tue Mar 26 09:00:20 2002
1043 +++ /sbin/hotplug Fri Feb 20 18:40:38 2004
1048 -# DEBUG=yes export DEBUG
1049 +DEBUG=yes export DEBUG
1051 if [ "$DEBUG" != "" ]; then
1052 mesg "arguments ($*) env (`env`)"
1053 ------------------------------------------------------
1054 Then, you can check your message logs for Hotplug events with
1055 'tail -f /var/log/messages'. Verify that the various Hotplug events
1056 happen as expected (pci, firmware, net...), and verify the log
1057 messages from 'net.agent'.