nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 Sane network interface management with Hotplug
2 ----------------------------------------------
3  
4 INTRODUCTION
5 ------------
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
20 scripts.
21  
22 ASSUMPTIONS
23 -----------
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.
32  
33 PROBLEM STATEMENT
34 -----------------
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
45 Ethernet card).
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.
55  
56 EXAMPLE SYSTEM
57 --------------
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
61 to this document.
62  
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)
74  
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.
78  
79 BASIC CONCEPTS
80 --------------
81 Most of the concept and tricks presented here are not really
82 new. The main contribution is to integrate them.
83  
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
88 the way to go.
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.
97  
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
101 'mynetworkcard').
102 6) No interface is called 'eth0' (or 'wlan0'). Any unknown
103 device would be 'eth0', so known devices should be called something
104 else.
105 7) Multiple configurations for a single interface (schemes)
106 are managed by the ifup/ifdown subsystem.
107  
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
113 subsystem.
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.
119  
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
124  
125 1) Applicability
126 ----------------
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
133 ISA and EISA cards.
134  
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.
144  
145 There are 3 alternatives to manage device drivers as
146 modules.
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.
157  
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).
164  
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 :
169  
170 --------- /etc/modprobe.d/local or /etc/modprobe.conf ------
171 # HP 100VG J2585B PCI card
172 alias eth2 hp100
173  
174 # AMD AMD PCnet LANCE PCI card
175 alias eth4 pcnet32
176  
177 # Old AT&T Wavelan ISA card
178 alias eth3 wavelan
179 options wavelan io=0x390 irq=15
180 ------------------------------------------------------------
181  
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.
190  
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.
203  
204 In any case, you should verify that 'ifrename' is properly
205 installed and check the path needed to call it :
206 --------------------------
207 > which ifrename
208 /sbin/ifrename
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'.
212  
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
220 'ifconfig' command.
221  
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
224 is below :
225  
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
230 doopt syncookies no
231 doopt ip_forward no
232  
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: "
238 + ifrename -p
239 + echo "done."
240 + fi
241 +
242 echo -n "Configuring network interfaces: "
243 ifup -a
244 echo "done."
245 ----------------------------------------------------------------
246 Don't forget to set the appropriate path to the ifrename
247 command (see step (3) above).
248  
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.
255  
256 5) Renaming interfaces
257 ----------------------
258 As stated above, we use 'ifrename' to assign names to
259 interfaces.
260  
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
265 bit looking around :
266  
267 -----------------------------
268 # modprobe pcnet32
269 # ifconfig eth0
270 eth0 Link encap:Ethernet HWaddr 00:10:83:34:BA:E5
271 [...]
272 -----------------------------
273  
274 The configuration of 'ifrename' is simple, you just specify
275 which name should be used for each MAC address in the file
276 /etc/iftab :
277  
278 --------- /etc/iftab ------------------------
279 # HP 100VG J2585B PCI card
280 eth2 mac 08:00:09:*
281  
282 # Old AT&T Wavelan ISA card
283 eth3 mac 08:00:0E:*
284  
285 # AMD AMD PCnet LANCE PCI card
286 eth4 mac 00:10:83:*
287 ---------------------------------------------
288  
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
293 'ifrename'.
294  
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
299 o Run ifrename
300 o Check each interface with ifconfig
301 o Bring all interfaces up : ifconfig ethX up
302  
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.
310  
311 In Debian, you would need to modify the file
312 /etc/network/interfaces so that it looks something like this :
313  
314 --------- /etc/network/interfaces -----------
315 # AMD PCnet LANCE PCI card
316 auto eth4
317 iface eth4 inet dhcp
318  
319 # HP 100VG J2585B PCI card
320 auto eth2
321 iface eth2 inet static
322 address 10.0.0.2
323 netmask 255.255.255.0
324 broadcast 10.0.0.255
325 gateway 10.0.0.1
326 ---------------------------------------------
327  
328 This was the last part. Now, at your next boot, all your
329 interfaces should be assigned the proper name and the proper
330 configuration.
331  
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.
339  
340 1) Applicability
341 ----------------
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.
350  
351 2) How Hotplug works
352 --------------------
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.
363  
364 If we insert a CardBus network card in the system, the
365 following happens :
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.
375  
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
382 via Hotplug :
383 1) Init scripts start running
384 2) Init script calls 'ifup -a' to initialise built-in
385 network interfaces
386 3) 'ifup' auto-loads driver module for built-in network
387 interface 'eth4'
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.
393  
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.
401  
402 Other distributions have very different ifup programs and I
403 have not tried those (tell me about it !).
404  
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
409 of the box'.
410 You will need to install the following packages :
411 o hotplug
412 o ifrename
413  
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.
419  
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
423 recommended.
424  
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.
438  
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)
444 mapping hotplug
445 script echo
446 ---------------------------------------------
447  
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)
452 mapping hotplug
453 script grep
454 map ethA
455 ---------------------------------------------
456  
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.
462  
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.
466  
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
471 fi
472  
473 case $ACTION in
474 -register)
475 +add|register)
476  
477 case $INTERFACE in
478 # interfaces that are registered after being "up" (?)
479 @@ -52,7 +52,7 @@ register)
480 mesg $1 $ACTION event not handled
481 ;;
482  
483 -unregister)
484 +remove|unregister)
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 -------------------------------------------------
489  
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.
493  
494 6) Installing hotplug on other distributions
495 --------------------------------------------
496 The canonical version of hotplug is available at :
497 http://linux-hotplug.sourceforge.net/
498  
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.
504  
505 My guess is that in a few releases, all these problems will
506 sort themselves out. Just be patient.
507  
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 :
517 1) Kernel boots
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
524  
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
537 faster.
538  
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
541 will not be loaded.
542 Hotplug can be disabled for a whole subsystem by editing the
543 appropriate .rc script in /etc/hotplug, or just deleting/renaming
544 those files.
545  
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.
555  
556 Check the path for ifrename :
557 --------------------------
558 > which ifrename
559 /sbin/ifrename
560 --------------------------
561  
562 The patch to add 'ifrename' to hotplug looks like :
563  
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.
570  
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
582 + INTERFACE=$NEWNAME
583 + fi;
584 + fi
585 +
586 # RedHat and similar
587 export IN_HOTPLUG=1
588 if [ -x /sbin/ifup ]; then
589 -------------------------------------------------
590  
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
594 place.
595 The path for 'ifrename' is used twice above, so don't forget
596 to modify both occurences.
597  
598  
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.
607  
608 If you use a driver compiled statically in the kernel, you
609 also have nothing to do.
610  
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 :
617  
618 --------- /etc/iftab -----------------------
619 # SMC 2835W wireless CardBus card
620 prism* mac 00:30:B4:*
621 ---------------------------------------------
622  
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 :
627  
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 ---------------------------------------------
633  
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.
639  
640 In Debian, you would need to modify the file
641 /etc/network/interfaces like this :
642  
643 --------- /etc/network/interfaces -----------
644 # Enable Hotplug support (Sarge and later)
645 mapping hotplug
646 script grep
647 map prism0
648  
649 # SMC 2835W wireless CardBus card
650 iface prism0 inet static
651 address 10.0.1.2
652 netmask 255.255.255.0
653 broadcast 10.0.1.255
654 wireless-essid THE_ESSID
655 wireless-mode ad-hoc
656 wireless-channel 5
657 ---------------------------------------------
658  
659 Note that you should not have wireless-* lines if you are
660 using waproamd to set these parameters.
661  
662 Now, just cross your fingers and plug the card in the slot...
663  
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.
672  
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.
682  
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
695 ignore it.
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.
700  
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...
710  
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.
717  
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
722 init scripts.
723 With Debian, you just need to make sure that the 'auto"
724 keyword doesn't apply to this interface.
725  
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'.
730  
731 If you use both a modular system, make sure that the
732 'on-demand' module loading is properly configured :
733  
734 --------- /etc/modprobe.d/local or /etc/modprobe.conf ------
735 # HP 100VG J2585B PCI card
736 alias eth2 hp100
737  
738 # AMD AMD PCnet LANCE PCI card
739 alias eth4 pcnet32
740 ------------------------------------------------------------
741  
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 :
745  
746 --------- /etc/network/interfaces -----------
747 # AMD AMD PCnet LANCE PCI card
748 # noauto
749 iface eth4 inet dhcp
750 pre-up /sbin/ifrename -p -n eth4
751 post-down /sbin/modprobe -r eth4
752  
753 # HP 100VG J2585B PCI card
754 # noauto
755 iface eth2 inet static
756 address 10.0.0.2
757 netmask 255.255.255.0
758 broadcast 10.0.0.255
759 gateway 10.0.0.1
760 pre-up /sbin/ifrename -p -n eth2
761 post-down /sbin/modprobe -r eth2
762 ---------------------------------------------
763  
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.
770  
771 To enable the interface, just use :
772 -----------------------------------
773 ifup eth4
774 -----------------------------------
775 And to disable the interface :
776 -----------------------------------
777 ifdown eth4
778 -----------------------------------
779  
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 -----------------------------------
785 modprobe eth4
786 ifrename
787 ifup eth4
788 -----------------------------------
789 If you use hotplug, you only need to do :
790 -----------------------------------
791 modprobe eth4
792 -----------------------------------
793 On the other hand, disabling the interface is done with :
794 -----------------------------------
795 ifdown eth4
796 modprobe -r eth4
797 -----------------------------------
798  
799  
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
803 docking station.
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
807 'scanpci' may help.
808  
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 ----------------------------
813 #!/bin/sh
814 modprobe eth4
815 ifrename
816 ifup eth4
817 ------------------------------------------------
818 And prior to undocking, you would run :
819 -------- /sbin/undock ----------------------------
820 #!/bin/sh
821 ifdown eth4
822 modprobe -r eth4
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.
827  
828  
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.
835  
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
840 DISTRIBUTIONS.txt.
841  
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
849 usually fail.
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
852 addresses.
853  
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
858 my web site.
859 2) Check the path for 'ifscheme-mapping' (using whereis).
860 3) Modify you /etc/network/interface to add proper mapping and
861 configuration.
862  
863 ------- /etc/network/interfaces ----------------------
864 # Enable Hotplug support (Sarge and later)
865 mapping hotplug
866 script echo
867  
868 # SMC 2835W wireless CardBus card
869 mapping prism0
870 script /sbin/ifscheme-mapping
871  
872 iface prism0-any inet dhcp
873 wireless-essid any
874 wireless-mode managed
875  
876 iface prism0-adhoc inet static
877 address 10.0.1.2
878 network 10.0.1.0
879 netmask 255.255.255.0
880 broadcast 10.0.1.255
881 wireless-essid THE_ESSID
882 wireless-mode ad-hoc
883 wireless-channel 5
884  
885 iface prism0-other inet static
886 address 10.10.10.2
887 network 10.10.10.0
888 netmask 255.255.255.0
889 broadcast 10.10.10.255
890 wireless-essid ANOTHER_ESSID
891 wireless-mode ad-hoc
892 wireless-key "s:secure"
893 ------------------------------------------------------
894  
895 FIRMWARE LOADING
896 ----------------
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.
900  
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.
906  
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.
911  
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 :
914  
915 -------- /etc/fstab ------------------------------
916 sysfs /sys sysfs defaults 0 0
917 --------------------------------------------------
918  
919 Then, you add the firmware file in the directory where it's
920 expected, which is /usr/lib/hotplug/firmware/ in most cases.
921  
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
930  
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.
940  
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.
953  
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.
959  
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 :
963  
964 --------- /etc/iftab -----------------------
965 # Cisco Aironet 350 wireless Pcmcia card
966 airo* mac 00:07:0E:* arp 1
967 ---------------------------------------------
968  
969 After that, your device would be available through 'eth0' and
970 'wifi0'.
971  
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
974 would do :
975 --------- /etc/iftab -----------------------
976 # Cisco Aironet 350 wireless Pcmcia card
977 wifi* mac 00:07:0E:*
978 airo* mac 00:07:0E:* arp 1
979 ---------------------------------------------
980  
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
984 just extend it.
985  
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.
999  
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
1004 achieve.
1005 A quick theoretical example to illustrate :
1006 --------- /etc/iftab -----------------------
1007 # All other usbnet devices
1008 usb* driver usbnet
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 ---------------------------------------------
1013  
1014 TROUBLESHOOTING
1015 ---------------
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.
1019  
1020 You need to check that the driver module(s) was loaded using
1021 'lsmod'.
1022  
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
1033 highly discouraged.
1034  
1035 You need to check which configuration was given to the
1036 interface using 'ifconfig' and 'iwconfig'.
1037  
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
1044 @@ -22,7 +22,7 @@
1045 cd /etc/hotplug
1046 . hotplug.functions
1047  
1048 -# DEBUG=yes export DEBUG
1049 +DEBUG=yes export DEBUG
1050  
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'.
1058  
1059  
1060 Have fun...
1061  
1062 Jean