{"id":7435,"date":"2008-01-12T18:13:00","date_gmt":"2008-01-12T18:13:00","guid":{"rendered":"https:\/\/www.practicallynetworked.com\/?p=7435"},"modified":"2022-11-17T18:15:00","modified_gmt":"2022-11-17T18:15:00","slug":"hotplug-udev-txt","status":"publish","type":"post","link":"https:\/\/www.practicallynetworked.com\/hotplug-udev-txt\/","title":{"rendered":"HOTPLUG-UDEV.txt"},"content":{"rendered":"\n<pre class=\"wp-block-preformatted\">Sane network interface management with Hotplug or uDev\n\t\t------------------------------------------------------\n\nINTRODUCTION\n------------\n\tIn the old days all wireless cards were managed by the\nexcellent Pcmcia subsystem and its rich configuration scripts, and\nlife was good. Then came the wireless PCI cards, then the wireless\nUSB dongles. Some unification was needed, and rather than adapt the\nPcmcia subsystem for PCI and USB, it was decided to create the much\nsimpler Hotplug system.\n\tThe USB subsystem already uses Hotplug. The Pcmcia subsystem\nis migrating to it : CardBus cards (32 bits) already use Hotplug,\nwhereas Pcmcia cards (16 bits) often still use the old Pcmcia scripts.\n\tThe Hotplug system is now very mature. Most users comming from\nthe old Pcmcia scripts are disappointed at first by its apparent lack\nof features, however it is very flexible and powerful. The new uDev\nsystem depend on Hotplug and integrates tightly with it.\n\tIn this document, we will show how to fully exploit the\nHotplug system and try to implement the equivalent of all the\nfunctionality of the Pcmcia scripts.\n\n\nASSUMPTIONS\n-----------\n\tThe target audience of this document is mostly power users and\ndistribution maintainers, but it should give enough clues to help\nnewbies. You should have read and understood DISTRIBUTIONS.txt. The\nprocedures described here are more advanced than the simple\nconfiguration described in DISTRIBUTIONS.txt.\n\tThe main focus is of course on removable wireless interfaces,\nbut we will to talk about network interface management in general, so\nthis should apply also to built-in Ethernet cards.\n\n\nPROBLEM STATEMENT\n-----------------\n\tLet's assume a Linux system and two or more network devices,\nDevice A and Device B. Those devices may be built-in or removable,\nthey may be present or absent from the system at any time, and they\nmay activated in any particular order.\n\tThe user wants to assign Configuration A to Device A and\nConfiguration B to Device B, without the possibility that Device A\ngets assigned Configuration B.\n\tDifferent users may have different definitions of what is\nDevice A. For some, it's a specific instance of a specific hardware,\nfor others any hardware that meets some criteria (a wireless card, an\nEthernet card).\n\tThe user may also want to have multiple configurations for a\ngiven device such that the chosen configuration depends on various\nfactors, just as with the old Pcmcia schemes. Device A may need\nConfiguration A1 or Configuration A2 depending on those factors.\n\tBy default, all network interfaces are created using default\ninterface names (starting at \"eth0\" and going up). I call that the\n\"all my cards are eth0\" problem : im most distributions, \"eth0\" points\nto a single fixed configuration in the configuration\ndatabase. Clearly, this won't satisfy our requirements.\n\n\nEXAMPLE SYSTEM\n--------------\n\tThe distribution I use is Debian 3.0, and some parts of what I\nsay here will be specific to it. However, it should be easy to\ntranslate this material to other distributions and I welcome additions\nto this document.\n\n\tThe example system is as follows :\n\t\to Linux 2.6.X SMP kernel with hotplug support\n\t\to Fully modular system (all network drivers as modules)\n\t\to PCI Ethernet card : AMD PCnet LANCE (pcnet32 - eth4)\n\t\to PCI Ethernet card : HP 100VG J2585B (hp100 - eth2)\n\t\to ISA Wireless card : Old AT&amp;T Wavelan (wavelan - eth3)\n\t\to ISA-Pcmcia bridge : VADEM VG-469 (i82365 - slot 0)\n\t\to PCI-CardBus bridge : Ricoh RL5c475 (yenta_socket - slot 2)\n\t\to Pcmcia 802.11 card : Aironet 350 (airo_cs - eth0)\n\t\to Pcmcia 802.11 card : Lucent Orinoco (orinoco_cs - eth0)\n\t\to CardBus 802.11 card : SMC 2835W (prism54 - prism0)\n\n\tThis system just happens to be my Linux development box. It\nhas enough interfaces to make it interesting. All the examples I\npresent in this document are extracted from this system.\n\n\nBASIC CONCEPTS\n--------------\n\tMost of the concept and tricks presented here are not really\nnew. The main contribution is to integrate them.\n\n\t1) Removable network interfaces are managed by Hotplug\n(Pcmcia, CardBus, USB...). We can't assume that those interfaces are\nalways present in this system and available at boot time (Pcmcia cards\nwere not made to be soldered in the Pcmcia slot). Therefore Hotplug is\nthe way to go.\n\t2) The Hotplug system can use either the original Hotplug\nscripts or the uDev daemon with the uDev scripts.\n\t3) Built-in PCI and ISA cards are managed by the init scripts,\nas they have always been. The ISA subsystem will never have Hotplug\nsupport, and hotplug is not necessary for PCI cards.\n\t4) Built-in devices that are disable most of the time should\nbe enabled manually by the user. Therefore both Hotplug and the init\nscripts should ignore those devices by default.\n\t5) (1), (3) and (4) must be compatible on the same system and\nplay nice with each other.\n\n\t6) A well defined and consistent network interface name is\nassigned to each network hardware interface using 'ifrename'. Device A\nis always named 'ethA' (or whatever name you like such as\n'mynetworkcard').\n\t7) No interface is called 'eth0' (or 'wlan0'). Any unknown\ndevice would be 'eth0', so known devices should be called something\nelse. There are also other issues with using 'eth0'.\n\t8) Multiple configurations for a single interface (schemes)\nare managed by the ifup\/ifdown subsystem.\n\n\nCONFIGURATION FROM INIT SCRIPTS\n-------------------------------\n\tIt may seem paradoxical, but before setting up Hotplug, we\nneed to make sure that the initialisation of network cards via init\nscripts is done properly and doesn't get in the way of the Hotplug\nsubsystem.\n\tThe configuration of network cards via init scripts is the\ntraditional way networking is initialised in Linux. The advantage of\nthis method is that it's very well documented and understood, and has\nnot changed much over the years. Unfortunately, it doesn't adequately\nsupport removable cards.\n\n\tThe init scripts perform the following 3 functions in order :\n\t\t1) Load necessary driver modules\n\t\t2) Rename interface to name chosen by the user\n\t\t3) Configure those network interfaces\n\n\t1) Applicability\n\t----------------\n\tConfiguration from init scripts is applicable to any built-in\nnetwork interface (ISA, PCI...), i.e., interfaces available at boot\ntime and that will never be removed from the system.\n\tThe Hotplug subsystem also has the ability to configure some\nof the built-in network interfaces, such as PCI cards. However, there\nis a class of devices that will never have Hotplug support, such as\nISA and EISA cards.\n\n\t2) Loading driver modules (if\/as needed)\n\t----------------------------------------\n\tMost distributions build the kernel drivers as modules. This\nmodular setup allows to minimise the amount of memory used by the\nsystem and the flexible loading\/unloading of drivers.\n\tYou can also compile your kernel with static drivers\n(non-modular). In that case, the driver will always be available in\nthe kernel, you don't need to configure the module subsystem, so you\ncan skip directly to the next section.\n\n\tThere are 3 alternatives to manage device drivers as\nmodules.\n\t\t1) Some distributions have an explicit list of modules\nthat are loaded at boot time, usuall in \/etc\/modules. If you want to\nuse that feature you need to check the documentation of your\ndistribution.\n\t\t2) Some system, such as Hotplug, Discover or Kudzu,\ncan scan the various buses of the PC and load the appropriate\ndrivers. This is mostly configuration-free, but may not support all\ndevices and may load unnecessary modules.\n\t\t3) The module subsystem also allows to load modules\n'on-demand'. When an application try to access or configure a network\ninterface, the corresponding module is loaded.\n\n\tI personally prefer to use the 'on-demand' feature of the\nmodule subsystem, as this allow you to not have to specify a static\nlist of modules that need to be loaded, and only modules really needed\nare loaded which saves kernel memory. You can also choose which module\nto load when there are multiple modules available that support your\nhardware (which happens quite often).\n\n\tWith kernel 2.6.X the module subsystem is configured in the\nfile \/etc\/modprobe.conf or files in the directory \/etc\/modprobe.d\/. To\nconfigure 'on-demand' module loading, on my test system I need to add\nto the following lines to the configuration :\n\n--------- \/etc\/modprobe.d\/local or \/etc\/modprobe.conf ------\n# HP 100VG J2585B PCI card\nalias eth2 hp100\n\n# AMD AMD PCnet LANCE PCI card\nalias eth4 pcnet32\n\n# Old AT&amp;T Wavelan ISA card\nalias eth3 wavelan\noptions wavelan io=0x390 irq=15\n------------------------------------------------------------\n\n\tYour distribution may already have lines for your interfaces,\neither replace these or make sure they are correct (some distributions\nare notorious for picking the wrong driver name in some cases). This\nfile also contains configuration for lot of other subsystems,\nobviously you don't want to touch that.\n\tIn this file, you put the name you would like the interface to\nhave (we'll fix that in a minute). Note that for modern PCI cards this\nis much more straightforward than for old ISA cards.\n\n\tWhen loading modules on-demand, you usually can not use the\nname 'eth0' or other 'ethX' with a low number for your interfaces, as\non-demand module may fail to load them. If there is a unknown\ninterface or an interface not yet renamed on the system, it will be\neth0, and the system will assume the module for eth0 is already loaded\nand will fail to load the proper module.\n\tTo test on-demand loading of module, you can do :\n--------------------------\n&gt; \/sbin\/modprobe -r eth2\n&gt; \/sbin\/modprobe eth2\n--------------------------\n\n\t3) Installing 'ifrename'\n\t------------------------\n\tYou will need to install ifrename on your system. 'ifrename'\nis part of the Wireless Tools package (version 27 and later) and is a\ncomplete rewrite of the now obsolete 'nameif'.\n\tSome distributions, such as Debian 3.1\/4.0, offer a separate\npackage for 'ifrename', and in this case you should just install this\npackage. Other distributions may include ifrename as part of their\n'wireless-tools' package (this should be the case for Gentoo, Fedora\nand Mandrake). Other distributions, such as Debian 3.0 and Unbuntu\n7.10, don't include ifrename at all, so you should compile yourself a\nrecent version of Wireless Tools (v29 or later) and install it.\n\tThe installation of Wireless Tools is described in the INSTALL\nfile of the Wireless Tools package. If you plan to only use ifrename,\na good option is to compile a static version of Wireless Tools and\nonly copy the resulting ifrename executable.\n\n\tIn any case, you should verify that 'ifrename' is properly\ninstalled and check the path needed to call it :\n--------------------------\n&gt; which ifrename\n\/sbin\/ifrename\n&gt; whereis ifrename\nifrename: \/sbin\/ifrename \/usr\/man\/man8\/ifrename.8 \/usr\/share\/man\/man8\/ifrename.8.gz\n--------------------------\n\tMost distributions will install 'ifrename' in '\/sbin', while\nif you compile your own wireless tools, by default it will be in\n'\/usr\/local\/sbin' (see Makefile on how to change that).\n\tIf you are upgrading ifrename from a previous version, you\nshould make sure that the new version of ifrename is either installed\nin the same location (overwrite old version) or in a place earlier in\nthe PATH (check with whereis).\n\n\t4) Making the boot scripts call 'ifrename'\n\t------------------------------------------\n\tYou need to make sure 'ifrename' is run at boot time. Most\ndistributions don't do that yet by default.\n\tThis is a part that is distribution-specific, so you will need\nto look into your own init files, or ask people familiar with your\ndistribution. It will need to run just before the call to 'ifup' or\n'ifconfig' command.\n\n\tIn Debian 4.0 (Etch) and later, the 'ifrename' package adds it\nown init script at the right place, called \/etc\/init.d\/ifrename. You\ndon't have to do anything.\n\tIn Debian 3.0 (Woody) and Debian 3.1 (Sarge), ifrename needs\nto be run from \/etc\/init.d\/networking, which is not the default. The\nnecessary patch to the init script is below :\n\n----------------------------------------------------------------\n--- networking-orig     Wed Feb 18 13:56:23 2004\n+++ networking  Fri Feb 20 14:51:06 2004\n@@ -120,6 +120,15 @@ case \"$1\" in\n         doopt syncookies no\n         doopt ip_forward no\n \n+       # Optionally remap interface names based on MAC address.\n+       # '\/sbin\/ifrename' is part of wireless-tools package.\n+       # \/etc\/iftab is currently not created by default. Jean II\n+       if [ -x \/sbin\/ifrename ] &amp;&amp; [ -r \/etc\/iftab ]; then\n+           echo -n \"Remapping network interfaces name: \"\n+           ifrename -p\n+           echo \"done.\"\n+       fi\n+\n         echo -n \"Configuring network interfaces: \"\n         ifup -a\n        echo \"done.\"\n----------------------------------------------------------------\n\tDon't forget to set the appropriate path to the ifrename\ncommand (see step (3) above).\n\n\tYou may also want to also set the proper options for ifrename\n(check the man page).\n\tThe option '-p' enables module autoloading compatibility.\n\tThe default version of 'ifrename' also includes some special\nDebian support : using \"ifrename -p -d\", only the proper modules are\nloaded. If you are using Debian, you should use this option.\n\n\t5) Renaming interfaces\n\t----------------------\n\tAs stated above, we use 'ifrename' to assign names to\ninterfaces.\n\n\tFirst, you need to get the MAC address of each of your\ninterfaces. You can read the MAC address on the label of the card, or\ndisplay it using the 'ifconfig -a' command. Remember that the\ninterface won't load yet with the proper name, so you may need to do a\nbit looking around :\n\n-----------------------------\n# modprobe pcnet32\n# ifconfig eth0\neth0      Link encap:Ethernet  HWaddr 00:10:83:34:BA:E5  \n[...]\n-----------------------------\n\n\tThe configuration of 'ifrename' is simple, you just specify\nwhich name should be used for each MAC address in the file\n\/etc\/iftab :\n\n--------- \/etc\/iftab ------------------------\n# HP 100VG J2585B PCI card\neth2\t\tmac 08:00:09:*\n\n# Old AT&amp;T Wavelan ISA card\neth3\t\tmac 08:00:0E:*\n\n# AMD AMD PCnet LANCE PCI card\neth4\t\tmac 00:10:83:*\n---------------------------------------------\n\n\tThe '*' in the MAC address is a wildcard and allows me to\nreplicate my configuration between multiple identical computers. If\nyou have to manage large number of computers (like a rack of servers\nor clusters), then you may want to look at other selectors offered by\n'ifrename'.\n\n\tIn this example, we used the MAC address of the card. Using\nthe MAC address is not always an option, there is a section at the end\nof this document dedicated to those cases.\n\n\tTo test that ifrename works, do the following :\n\t\to Load all your drivers, see section (2)\n\t\to Check \/proc\/net\/dev to see which interface exist\n\t\to Bring all interfaces down : ifconfig ethX down\n\t\to Run ifrename\n\t\to Check each interface with ifconfig\n\t\to Bring all interfaces up : ifconfig ethX up\n\n\t6) Configuring interfaces\n\t-------------------------\n\tMost likely, your distribution is already doing this part\nproperly. Just assign the proper IP and wireless configuration to each\nof the interface names you have chosen.\n\tThis part is distribution specific, and I already document it\nin the file DISTRIBUTIONS.txt.\n\n\tIn Debian, you would need to modify the file\n\/etc\/network\/interfaces so that it looks something like this :\n\n--------- \/etc\/network\/interfaces -----------\n# AMD PCnet LANCE PCI card\nauto eth4\niface eth4 inet dhcp\n\n# HP 100VG J2585B PCI card\nauto eth2\niface eth2 inet static\n    address 10.0.0.2\n    netmask 255.255.255.0\n    broadcast 10.0.0.255\n    gateway 10.0.0.1\n---------------------------------------------\n\n\tThis was the last part. Now, at your next boot, all your\ninterfaces should be assigned the proper name and the proper\nconfiguration.\n\tIf this is not the case, there is a troubleshooting section at\nthe end of this document.\n\n\nCONFIGURATION VIA UDEV\n----------------------\n\tDealing with removable interfaces is similar to dealing with\nbuilt-in interfaces, the main difference is that we will use Hotplug\nevent with the uDev system instead of the init scripts. This requires\na fairly recent distributions, older distributions don't have uDev or\nuDev system not capable enough.\n\tNote that you can also use removable interfaces with the\noriginal Hotplug scripts. This is detailed in the next section. The\ninstallation of uDev changes a lot of things on a system, so may not\nbe for everybody, however recent version of Gnome and KDE seem to\nrequire it.\n\n\t1) Applicability\n\t----------------\n\tThe Hotplug configuration method is the best choice for any\nremovable network interface, such as :\n\t\to Pcmcia (16 bits) network cards\n\t\to CardBus (32 bits) network cards\n\t\to USB network dongles\n\t\to Hot-PCI network cards\n\tIt may also be used to manage other types of network\ninterfaces, although it may not be the best choice for them.\n\n\t2) How Hotplug works with the uDev scripts\n\t------------------------------------------\n\tWhen using uDev, the concept is similar to the original\nHotplug scripts, however the implementation is slightly less\ntransparent. Also, the name of the rules and the location of scripts\nvary from distribution from distribution.\n\n\tWhen something interesting happens, the Linux kernel generates\nan Hotplug event. The uDev deamon (udevd) receive the event, does some\nprocessing on its own, use the rules in \/etc\/udev\/rules.d\/, and\nfinally run the proper script in \/lib\/udev\/.\n\tThere are 3 types of Hotplug events we care about :\n\t\to PCI event : a CardBus device is added or removed\nfrom the system. The hotplug rule loads the driver, in my case\n\/etc\/udev\/rules.d\/z55_hotplug.rules.\n\t\to USB event : a USB device is added or removed from\nthe system. The hotplug rule loads the driver, in my case\n\/etc\/udev\/rules.d\/z55_hotplug.rules.\n\t\to Network event : a network interface is added or\nremoved from the system. The script \/lib\/udev\/net.agent is run.\n\n\tIf we insert a CardBus network card in the system, the\nfollowing happens :\n\t\t1) Kernel detects new CardBus device\n\t\t2) Kernel generates PCI Hotplug event\n\t\t3) udevd receive the event, runs the Hotplug rule.\n\t\t4) The Hotplug rule find the proper driver module and loads it.\n\t\t5) Driver module initialises, creates new network device\n\t\t6) Kernel detects new network device\n\t\t7) Kernel generates Network Hotplug event\n\t\t8) \/lib\/udev\/net.agent runs, configures network device\n\tThe sequence of events is similar for USB devices and for removals.\n\n\t3) Installing uDev for Debian Lenny\n\t-----------------------------------\n\tThanks to the great work of many people, Debian Lenny has all\nthe necessary packages and complete udev support, and will work mostly\n'out of the box'.\n\tYou will need to install the following packages :\n\t\to udev\n\t\to ifrename\n\n\tThe configuration of Hotplug and uDev is simple. You only have\nto modify the file \/etc\/network\/interfaces to enable your interfaces\nto be managed with Hotplug and uDev.\n\tBy default, ifup ignore all hotplug network events, as it\nassume network interfaces are configured using the static init\nscripts. To enable ifup to configure specific network interfaces on\nhotplug events, you need to list those interface in a \"allow-hotplug\"\nstatement.\n\tFor example, your \/etc\/network\/interfaces would include :\n--------- \/etc\/network\/interfaces -----------\n# Enable Hotplug support (Etch and later)\n#\nallow-hotplug prism0 acx0\n---------------------------------------------\n\n\t4) Installing uDev for Debian Etch (4.0)\n\t----------------------------------------\n\tThe uDev system provided with Debian Etch (4.0) is fully\nfunctional, except for one missing feature. This version of uDev can\nnot integrate with ifrename. The version of ifrename provided also\nlacks uDev support.\n\tIf you want to use uDev with Debian Etch (4.0), there are two\npossibilities. The first solution is use the uDev system to rename\ninterfaces, loosing some of the power of ifrename. The second solution\nis to upgrade both udevd and ifrename.\n\n\tThis is the procedure I personally use to upgrade udevd on\nDebian Etch (4.0) :\n\to Get the canonical version of udev 107 from :\n\t\thttp:\/\/www.kernel.org\/pub\/linux\/utils\/kernel\/hotplug\/udev.html\n\to Compile it with \"make\".\n\to Do not \"make install\" !\n\to Run \"strip udevd\"\n\to Save a copy of the original udevd \"cp \/sbin\/udevd \/sbin\/udevd.orig\"\n\to Copy the new udevd with \"cp udevd \/sbin\/udevd\".\n\tNote that udevd is an essential component of the OS. This\nprocedure should be safe, but I do not guarantee it will always be\nsafe.\n\n\tUpgrading ifrename is simple, this is like installing ifrename\nand is described above in this document.\n\n\tOnce those two packages are upgraded, you can go follow the\nprocedure going back to step (3).\n\n\t5) Installing uDev for Debian Sarge (3.1)\n\t-----------------------------------------\n\tThe uDev system provided with Debian Sarge (3.1) is a very old\nversion of uDev that is not integrated with the Hotplug scripts. In\nother words, if you install uDev with Sarge, you will still need to\nuse the original Hotplug scripts and configure your system with them.\n\n\t6) Installing uDev on other distributions\n\t--------------------------------------------\n\tThe canonical version of hotplug is available at :\n\t\thttp:\/\/www.kernel.org\/pub\/linux\/utils\/kernel\/hotplug\/udev.html\n\tThe mailing list for udev is the Hotplug mailins list :\n\t\thttp:\/\/linux-hotplug.sourceforge.net\/\n\t\thttp:\/\/marc.theaimsgroup.com\/?l=linux-hotplug-devel&r=1&w=2\n\n\tMost distributions have highly customized uDev packages and\nmost likely the canonical version won't completely work on your\nsystem. The udevd deamon is has usually little changes, however the\nrules and scripts are very different.\n\tTo be able to use uDev with ifrename, you will need uDev\nversion 107 and later, which has support for calling ifrename. You\nwill also need ifrename version 29.pre17 or later (I recommend version\n29). Most modern distributions should already have those versions.\n\tIf this is the case, you only need to install the uDev and\nifrename package. If there is no ifrename package, it's easy to\ncompile it from source and install it.\n\n\t7) Making uDev call ifrename\n\t----------------------------\n\tWe need to make sure that 'ifrename' is run by the uDev\nsubsystem at the right time. Because of the complex way uDev works,\nthe smooth integration can only be done one way. Other methods may\nleave the uDev system in a confused state, which may be a problem when\nthe card\/interface is removed.\n\n\tMost often, the only thing to do it to copy the file\n'19-udev-ifrename.rules' from the Wireless Tools package to the\ndirectory \"\/etc\/udev\/rules.d\/\". It should work on most system.\n\n\tWhat follow is a detailed explanation of what this additional\nrules does.\n\tuDev needs to call ifrename as an IMPORT rule, and with the\nright parameter. As I said, this requires uDev version 107 and later\nand ifrename version 29.pre17 or later.\n\tThe ifrename rule need to be called *before* the 'persistent'\nrules. I also like the ifrename rule to happen after local rules. The\nuDev rules are processed in alphabetical orders, which is why the\nrules filename start usually with numbers. However, those name vary\nbetwen distributions. Make sure the ifrename rule has a proper\nfilename for your distribution.\n\n\tThe rules we add looks like this :\n------ \/etc\/udev\/rules.d\/19-udev-ifrename.rules ------\n# Main ifrename rule.\n# If interface is found in \/etc\/iftab, subsequent rename rules are bypassed.\n# If interface is not found in \/etc\/iftab, subsequent rename rules applies.\nSUBSYSTEM==\"net\", ACTION==\"add\", IMPORT=\"\/sbin\/ifrename -u -i %k\", NAME:=\"%k\"\n------------------------------------------------------\n\n\tLastly, make sure the rule has the right path for ifrename :\n--------------------------\n&gt; which ifrename\n\/sbin\/ifrename\n--------------------------\n\n\t8) Loading driver modules\n\t-------------------------\n\tWow ! The most difficult part is done.\n\tIn theory, you don't need to do any specific configuration for\nthe driver modules to be loaded. The uDev system should load the right\ndriver module for you.\n\tAlso, you don't need to define aliases in \/etc\/modprobe.d\/* or\nin \/etc\/modprobe.conf, it's useless and may be counterproductive.\n\n\tIf you use a driver compiled statically in the kernel, you\nalso have nothing to do.\n\n\t9) Renaming interfaces\n\t-----------------------\n\tWe still use ifrename to assign names to interfaces. The\nconfiguration of 'ifrename' is the same. To keep the possibility of\nhaving multiple wireless cards (one in each CardBus slot), we use\nwildcards in both the MAC address and the name :\n\n--------- \/etc\/iftab -----------------------\n# SMC 2835W wireless CardBus card\nprism*\t\tmac 00:30:B4:*\n---------------------------------------------\n\n\tIf you insert two cards, they would be named prism0 and\nprism1. If you want to control which card get each name, you should\nnot use wildcards and set a specific line for each card :\n\n--------- \/etc\/iftab -----------------------\n# SMC 2835W wireless CardBus card\nprism0\t\tmac 00:30:B4:64:27:8B\nprism1\t\tmac 00:30:B4:64:27:8D\n---------------------------------------------\n\n\t10) Configuring interfaces\n\t--------------------------\n\tAt this point, configuration of uDev network interfaces is done\njust like their built-in counterparts. This part is still distribution\nspecific, and still already documented in the file DISTRIBUTIONS.txt.\n\n\tIn Debian, you would need to modify the file\n\/etc\/network\/interfaces like this :\n\n--------- \/etc\/network\/interfaces -----------\n# Enable Hotplug support (Etch and later)\n#\nallow-hotplug prism0\n\n# SMC 2835W wireless CardBus card\niface prism0 inet static\n    address 10.0.1.2\n    netmask 255.255.255.0\n    broadcast 10.0.1.255\n    wireless-essid THE_ESSID\n    wireless-mode ad-hoc\n    wireless-channel 5\n---------------------------------------------\n\n\tNote that you can also use graphical tools such as\nNetworkManager to configure interfaces at this point.\n\n\tNow, just cross your fingers and plug the card in the slot...\n\tIf it does not work, there is a troubleshooting section at the\nend of this document.\n\n\nCONFIGURATION VIA THE ORIGINAL HOTPLUG SCRIPTS\n----------------------------------------------\n\tThe previous section was dealing with removable interfaces\nwith Hotplug events and the uDev system. In various cases, or for old\ndistributions, it's preferable to use the original Hotplug\nscripts. The original Hotplug scripts are much less invasive on the\nsystem than uDev.\n\tUsing the original Hotplug scripts is similar to using uDev or\ndealing with built-in interfaces, the main difference is that the\nscript used are different. Another difference is that it will likely\nrequire more work on your part because most distributions do not have\nall part properly integrated.\n\n\t1) Applicability\n\t----------------\n\tThe Hotplug configuration method is the best choice for any\nremovable network interface, such as :\n\t\to Pcmcia (16 bits) network cards\n\t\to CardBus (32 bits) network cards\n\t\to USB network dongles\n\t\to Hot-PCI network cards\n\tIt may also be used to manage other types of network\ninterfaces, although it may not be the best choice for them.\n\n\t2) How the original Hotplug scripts works\n\t-----------------------------------------\n\tConceptually, Hotplug is very simple, and the Hotplug scripts\nare quite easy to follow.\n\n\tWhen something interesting happens, the Linux kernel generates\nan Hotplug event. This runs the main Hotplug script, which in turn\nruns the appropriate script from the \/etc\/hotplug directory.\n\tThere are 3 types of Hotplug events we care about :\n\t\to PCI event : a CardBus device is added or removed\nfrom the system. The script \/etc\/hotplug\/pci.agent is run.\n\t\to USB event : a USB device is added or removed\nfrom the system. The script \/etc\/hotplug\/usb.agent is run.\n\t\to Network event : a network interface is added or\nremoved from the system. The script \/etc\/hotplug\/net.agent is run.\n\n\tIf we insert a CardBus network card in the system, the\nfollowing happens :\n\t\t1) Kernel detects new CardBus device\n\t\t2) Kernel generates PCI Hotplug event\n\t\t3) \/etc\/hotplug\/pci.agent runs, finds proper driver module\n\t\t4) \/etc\/hotplug\/pci.agent loads driver module\n\t\t5) Driver module initialises, creates new network device\n\t\t6) Kernel detects new network device\n\t\t7) Kernel generates Network Hotplug event\n\t\t8) \/etc\/hotplug\/net.agent runs, configures network device\n\tThe sequence of events is similar for USB devices and for removals.\n\n\t3) Make sure ifup does not deadlock\n\t-----------------------------------\n\t&lt;Most people should ignore this part&gt;\n\t&lt;This applies only to Debian 3.0 and earlier&gt;\n\n\tThe first problem is that we need to make sure the command\n'ifup' does not deadlock by calling itself re-entrantly. If the system\nhas built-in interfaces, the 'ifup' may reenter itself at boot time\nvia Hotplug :\n\t\t1) Init scripts start running\n\t\t2) Init script calls 'ifup -a' to initialise built-in\n\t\t\tnetwork interfaces\n\t\t3) 'ifup' auto-loads driver module for built-in network\n\t\t\tinterface 'eth4'\n\t\t4) Driver module initialises, creates new network device\n\t\t5) Kernel generates Network hotplug event\n\t\t6) \/etc\/hotplug\/net.agent runs, call 'ifup eth4'\n\tNote that you can produce the same reentrancy if you call ifup\nmanually on an interface which module is not yet loaded.\n\n\tThe default version of 'ifup' for Debian 3.0 and Debian 3.1\nis not reentrant and can therefore deadlock if not used properly. The\npatch to make 'ifup' properly reentrant is available here :\n\t\thttp:\/\/bugs.debian.org\/cgi-bin\/bugreport.cgi?bug=231197\n\tContemporary versions of Debian (3.1 and later) have a\nnet.agent script that contains workarounds to prevents deadlock\nsituations, so for normal use the default 'ifup' should work fine.\n\tModern version of Debian (4.0 and later) have a version of\n'ifup' that is reentrant and that won't deadlock.\n\n\tOther distributions have very different ifup programs and I\nhave not tried those (tell me about it !).\n\n\t4) Installing uDev for Debian Etch (4.0) or Lenny\n\t-------------------------------------------------\n\tThanks to the great work of many people, Debian Etch and Lenny\nhas all the necessary packages and hotplug support, and will work\nmostly 'out of the box'.\n\tYou will need to install the following packages :\n\t\to hotplug\n\t\to ifrename\n\n\tThe configuration of network Hotplug has been much simplified\ncompared to Debian Sarge (3.0). You only have\nto modify the file \/etc\/network\/interfaces to enable your interfaces\nto be managed with Hotplug and uDev.\n\tBy default, ifup ignore all hotplug network events, as it\nassume network interfaces are configured using the static init\nscripts. To enable ifup to configure specific network interfaces on\nhotplug events, you need to list those interface in a \"allow-hotplug\"\nstatement.\n\tFor example, your \/etc\/network\/interfaces would include :\n--------- \/etc\/network\/interfaces -----------\n# Enable Hotplug support (Etch and later)\n#\nallow-hotplug prism0 acx0\n---------------------------------------------\n\n\t5) Installing Hotplug for Debian Sarge (3.1)\n\t--------------------------------------------\n\tThanks to the great work of many people, Debian Sarge has all\nthe necessary packages and hotplug support, and will work mostly 'out\nof the box'.\n\tYou will need to install the following packages :\n\t\to hotplug\n\t\to ifrename\n\n\tWhile the installation of Hotplug is simple, its configuration\nmay seem complex. The current network Hotplug script has 3 modes :\n'all', 'auto' and 'hotplug'. However for our purpose they all produce\nthe same results when configured. This mode is controlled by the\nvariable NET_AGENT_POLICY in \/etc\/default\/hotplug.\n\n\tIn the mode \"all\", Hotplug will run ifup for all network\nevents. This will result in failure messages if some interfaces have\nalready been configured by the init scripts. This mode is not\nrecommended.\n\n\tIn the mode \"auto\", Hotplug will run ifup only for those\ninterfaces listed in a auto stanza in \/etc\/network\/interfaces. If\nyou choose this mode, you need to put in \/etc\/network\/interfaces a\n\"auto\" line for the interfaces you want to control with hotplug.\n--------- \/etc\/network\/interfaces -----------\n# Enable Hotplug support for \"auto\" mode (Sarge and later)\nauto eth0 eth1 eth2 eth3 eth4 wlan0 wlan1 prism0 prism1 airo0 airo1\n---------------------------------------------\n\tThis will result in some failure message at boot time, the\ninit script will attempt to enable all those interfaces, and generate\nan error for all those not available at this time. It will also\ngenerate an error messages for interface which have already been\nconfigured by the init scripts. This mode is also not recommended.\n\n\tIn the mode \"hotplug\", hotplug network events are ignored by\nifup by default. To enable them you will need to add the following\nlines to \/etc\/network\/interfaces :\n--------- \/etc\/network\/interfaces -----------\n# Enable Hotplug support for \"hotplug\" mode (Sarge and later)\nmapping hotplug\n    script echo\n---------------------------------------------\n\n\tTo enable them for only selected interfaces, e.g., ethA, make\n\/etc\/network\/interfaces look like this :\n--------- \/etc\/network\/interfaces -----------\n# Enable Hotplug support for \"hotplug\" mode (Sarge and later)\nmapping hotplug\n    script grep\n    map ethA\n---------------------------------------------\n\n\t6) Installing Hotplug for Debian 3.0\n\t------------------------------------\n\tDebian 3.0 doesn't come by default with hotplug, but the\nhotplug package is available as regular Debian package (on the CD or\ndownloadable in Debian archive), so you can just install that.\n\n\tUnfortunately, this version of hotplug is not fully compatible\nwith kernel 2.6.X. You will need to do the following modifications to\nthe file \/etc\/hotplug\/net.agent.\n\n------- \/etc\/hotplug\/net.agent ------------------\n--- net.agent-d1        Fri Feb 20 18:18:05 2004\n+++ net.agent   Fri Feb 20 18:22:50 2004\n@@ -26,7 +26,7 @@ if [ \"$INTERFACE\" = \"\" ]; then\n fi\n \n case $ACTION in\n-register)\n+add|register)\n \n     case $INTERFACE in\n        # interfaces that are registered after being \"up\" (?)\n@@ -52,7 +52,7 @@ register)\n     mesg $1 $ACTION event not handled\n     ;;\n \n-unregister)\n+remove|unregister)\n     # Assume that we want to run ifdown no matter what,  \n     # because it is not going to remove the data from the \n     # ifstate database otherwise.\n-------------------------------------------------\n\n\tCompared to the version in Sarge, this older version of\nhotplug is much more basic, and doesn't have any scanning at boot time\nand doesn't need to be enabled in \/etc\/network\/interfaces.\n\n\t7) Installing hotplug on other distributions\n\t--------------------------------------------\n\tThe canonical version of hotplug is available at :\n\t\thttp:\/\/linux-hotplug.sourceforge.net\/\n\n\tMost distributions have customized hotplug packages and\nchances are that the canonical version won't completely work on your\nsystem. All these various changing versions make it difficult for me\nto tell what exactly needs to be changed in the hotplug scripts to\nmake them work. However, most should work out of the box.\n\tRemember also that in most cases, you can not have the\noriginal Hotplug scripts and uDev together. If uDev is already\ninstalled on your system, downgrading to the original Hotplug scripts\nmay be tricky.\n\n\tMy guess is that in a few releases, all these problems will\nsort themselves out. Just be patient.\n\n\t8) Dealing with 'init' hotplug\n\t------------------------------\n\tIn addition to the standard kernel Hotplug events, modern\nversions of the Hotplug scripts add init scripts that scan the system\nbuses and generate pseudo Hotplug events at boot time. For the PCI\nbuses, the script \/etc\/hotplug\/pci.rc is run, for the USB bus,\n\/etc\/hotplug\/usb.rc is run.\n\tThe end result is that the Hotplug subsystem will also attempt\nto configure built-in devices :\n\t\t1) Kernel boots\n\t\t2) Init runs, start to initialise the OS\n\t\t3) \/etc\/hotplug\/pci.rc runs, generates pseudo Hotplug event\n\t\t4) \/etc\/hotplug\/pci.agent loads driver module\n\t\t5) Driver module initialises, creates new network device\n\t\t6) Kernel generates Network Hotplug event\n\t\t7) \/etc\/hotplug\/net.agent runs, configures network device\n\n\tAt this point, you realise that at initialisation, both\nHotplug and the regular init scripts (see \"CONFIGURATION FROM INIT\nSCRIPTS\") are trying to configure the same devices in parallel. This\nmay create problems and is totally redundant.\n\tAnother reason I don't like this mechanism is that it blindly\nattempts to load drivers for all hardware present on the system and\ndoesn't use the module loader configuration files to select preferred\ndrivers. It's fairly common to have multiple drivers for a given\nhardware, and because of Murphy's law, Hotplug will usually load the\nwrong one. It's also fairly common to have hardware on the system that\ndoesn't need enabling (for example, the IDE controller on my SCSI\nmachine), not loading the driver makes your kernel smaller and boot\nfaster.\n\n\tHotplug does have a way of disabling the loading of drivers\non a case by case basis. Drivers listed in \/etc\/hotplug\/blacklist\nwill not be loaded.\n\tHotplug can be disabled for a whole subsystem by editing the\nappropriate .rc script in \/etc\/hotplug, or just deleting\/renaming\nthose files.\n\n\t9) Making hotplug scripts call ifrename\n\t---------------------------------------\n\tThe last hotplug step is to make sure that 'ifrename' is run\nby the hotplug subsystem at the right time. As before, we want to run\nit just before calling 'ifup'.\n\tThe latest version of the hotplug scripts have this feature\nintegrated. However, you need to check that the path used for calling\n'ifrename' is the proper one on your system. And, for older versions\nof hotplug scripts, you will need to add this support yourself.\n\n\tCheck the path for ifrename :\n--------------------------\n&gt; which ifrename\n\/sbin\/ifrename\n--------------------------\n\n\tThe patch to add 'ifrename' to hotplug looks like :\n\n------- \/etc\/hotplug\/net.agent ------------------\n--- net.agent-s2        Fri Feb 20 17:18:46 2004\n+++ net.agent   Fri Feb 20 17:32:43 2004\n@@ -40,6 +40,21 @@ add|register)\n            # we can't do much here without distro-specific knowledge\n            # such as whether\/how to invoke DHCP, set up bridging, etc.\n \n+           # Run ifrename as needed - Jean II\n+           # Remap interface names based on MAC address. This works around\n+           # the dreaded configuration problem \"all my cards are 'eth0'\"...\n+           # This needs to be done before ifup, otherwise ifup will get\n+           # confused by the name change and because iface needs to be\n+           # down to change its name.\n+           if [ -x \/sbin\/ifrename ] &amp;&amp; [ -r \/etc\/iftab ]; then\n+               debug_mesg invoke ifrename for $INTERFACE\n+               NEWNAME=`\/sbin\/ifrename -i $INTERFACE`\n+               if [ -n \"$NEWNAME\" ]; then\n+                   debug_mesg iface $INTERFACE is remapped to $NEWNAME\n+                   INTERFACE=$NEWNAME\n+               fi;\n+           fi\n+\n            # RedHat and similar\n            export IN_HOTPLUG=1\n            if [ -x \/sbin\/ifup ]; then\n-------------------------------------------------\n\n\tIf your hotplug scripts already include ifrename support then\nyou should find a section in \/etc\/hotplug\/net.agent looking like the\npatch above. Otherwise, just cut'n'paste the patch above in the right\nplace.\n\tThe path for 'ifrename' is used twice above, so don't forget\nto modify both occurences.\n\n\n\t9) Loading driver modules\n\t-------------------------\n\tWow ! The most difficult part is done.\n\tIn theory, you don't need to do any specific configuration for\nthe driver modules to be loaded. The 'pci.agent' and 'usb.agent'\nshould load the right driver module for you.\n\tAlso, you don't need to define aliases in \/etc\/modprobe.d\/* or\nin \/etc\/modprobe.conf, it's useless and may be counterproductive.\n\n\tIf you use a driver compiled statically in the kernel, you\nalso have nothing to do.\n\n\t10) Renaming interfaces\n\t-----------------------\n\tWe still use ifrename to assign names to interfaces. The\nconfiguration of 'ifrename' is the same. To keep the possibility of\nhaving multiple wireless cards (one in each CardBus slot), we use\nwildcards in both the MAC address and the name :\n\n--------- \/etc\/iftab -----------------------\n# SMC 2835W wireless CardBus card\nprism*\t\tmac 00:30:B4:*\n---------------------------------------------\n\n\tIf you insert two cards, they would be named prism0 and\nprism1. Note that 'name wildcarding' is a feature only available in\n2.6.X and 2.4.30 and later, so if you use older version of 2.4.X you\nwill need to be explicit and list each card separatly :\n\n--------- \/etc\/iftab -----------------------\n# SMC 2835W wireless CardBus card\nprism0\t\tmac 00:30:B4:64:27:8B\nprism1\t\tmac 00:30:B4:64:27:8D\n---------------------------------------------\n\n\t11) Configuring interfaces\n\t-------------------------\n\tAt this point, configuration of Hotplug network interfaces is\ndone just like their built-in counterparts. This part is still\ndistribution specific, and still already documented in the file\nDISTRIBUTIONS.txt.\n\n\tIn Debian, you would need to modify the file\n\/etc\/network\/interfaces like this :\n\n--------- \/etc\/network\/interfaces -----------\n# Enable Hotplug support (Etch and later)\n#\nallow-hotplug prism0 acx0\n\n# Enable Hotplug support (Sarge and later)\nmapping hotplug\n    script grep\n    map prism0\n\n# SMC 2835W wireless CardBus card\niface prism0 inet static\n    address 10.0.1.2\n    netmask 255.255.255.0\n    broadcast 10.0.1.255\n    wireless-essid THE_ESSID\n    wireless-mode ad-hoc\n    wireless-channel 5\n---------------------------------------------\n\n\tNote that you should not have wireless-* lines if you are\nusing waproamd to set these parameters.\n\n\tNow, just cross your fingers and plug the card in the slot...\n\n\nPCMCIA INTERFACES (16 bits)\n---------------------------\n\tThe Pcmcia subsystem has quite some legacy, and can use\nvarious configuration procedures. The Pcmcia subsystem exclusively\nuses hotplug for 32 bits cards (if you are using the kernel Pcmcia\nmodules, which is the only option for 2.6.X). For 16 bit cards cardmgr\nis still required for managing the sockets and loading\nmodules. Cardmgr is configured by files in the \/etc\/pcmcia directory.\n\n\tTo use Hotplug network configuration with 16 bits Pcmcia\ncards, first make sure the Pcmcia subsystem is properly configured and\nthat cardmgr loads the right driver module (in most case, it\nshould). Then, make sure that you don't have any configuration entries\nin \/etc\/pcmcia\/network.opts and \/etc\/pcmcia\/wireless.opts. Make sure\nthat none of the entries in your system network configuration use\n'eth0' or 'wlan0' (in \/etc\/network\/interfaces for Debian users).\n\tThen, just follow the procedure described above for\n\"Configuration Using Hotplug\" to configure your network cards.\n\n\tYou might want a little bit of explanation on why this magic\nwill work (which would help in case it doesn't work).\n\tThere are two types of Pcmcia network configuration scripts,\navailable as \/etc\/pcmcia\/network. The original Pcmcia script\nconfigures network cards using options found in\n\/etc\/pcmcia\/network.opts and \/etc\/pcmcia\/wireless.opts. Most\ndistributions replace it with a script calling 'ifup'. By making sure\nthat network.opts and wireless.opts are \"empty\", we neutralise the\nfirst set of scripts. By making sure no system configuration uses\n'eth0' or 'wlan0', we neutralise the second set of scripts, the script\nwould call 'ifup' with the default interface name, which is usually\n'eth0', ifup would not find a configuration for it and would just\nignore it.\n\tThe card would still be configured because hotplug network\nevents are generated for every interfaces, not only for devices\nmanaged by hotplug. So, net.agent would receive an event and perform\nthe necessary steps to configure it.\n\n\tPersonally, I'm still using the original Pcmcia scripts for my\nPcmcia cards as described in the file PCMCIA.txt, because it still\nworks and I will migrate my complex configurations over time.\n\tYou can also decide to not use Hotplug for Pcmcia cards and\nmodify the distribution Pcmcia scripts in \/etc\/pcmcia\/* to handle\nPcmcia cards with ifrename. You would need to modify\n\/etc\/pcmcia\/network to add 'ifrename' before 'ifup' the same way it\nwas done for \/etc\/hotplug\/net.agent. But, as in the long term Pcmcia\nwill migrate to Hotplug, I would not bother...\n\n\nMANUAL LOADING, DOCKING STATIONS\n--------------------------------\n\tManual loading is used for built-in network interfaces that\nare only use at specific time, and that you want disabled the rest of\nthe time. We assume that you still use modules so that when the\ninterface is not used you can remove the driver from the kernel.\n\n\tFirst, you need to set the configuration for those interfaces,\nthe same way it's done for other network interfaces. The main\ndifference is that you need to specify that those interfaces should\nnot be enabled at boot time. It's also a good idea to disable Hotplug\ninit scripts.\n\tWith Debian, you just need to make sure that the 'auto\"\nkeyword doesn't apply to this interface.\n\n\tIf you use drivers statically built in the kernel, make sure\nthat ifrename runs at boot time (see CONFIGURATION FROM INIT\nSCRIPTS). Once it's done, you can just enable and disable those\ninterfaces with 'ifup ethX' and 'ifdown ethX'.\n\n\tIf you use both a modular system, make sure that the\n'on-demand' module loading is properly configured :\n\n--------- \/etc\/modprobe.d\/local or \/etc\/modprobe.conf ------\n# HP 100VG J2585B PCI card\nalias eth2 hp100\n\n# AMD AMD PCnet LANCE PCI card\nalias eth4 pcnet32\n------------------------------------------------------------\n\n\tThen, you should instruct 'ifup' to load module and use\nifrename prior to configuring the interface, and remove the module\nwhen going down. With Debian, this is done with :\n\n--------- \/etc\/network\/interfaces -----------\n# AMD AMD PCnet LANCE PCI card\n# noauto\niface eth4 inet dhcp\n    pre-up \/sbin\/ifrename -p -n eth4\n    post-down \/sbin\/modprobe -r eth4\n\n# HP 100VG J2585B PCI card\n# noauto\niface eth2 inet static\n    address 10.0.0.2\n    netmask 255.255.255.0\n    broadcast 10.0.0.255\n    gateway 10.0.0.1\n    pre-up \/sbin\/ifrename -p -n eth2\n    post-down \/sbin\/modprobe -r eth2\n---------------------------------------------\n\n\tWe use the '-n' option of ifrename to specify the name of the\ninterface after renaming. This assume that the mapping for those\ninterfaces don't use wildcards. The '-p' option make sure ifrename\nprobes the module prior to using it.\n\tUsing \"modprobe -r\" make sure that if the driver is composed\nof multiple module all the modules are unloaded.\n\t\n\tTo enable the interface, just use :\n-----------------------------------\nifup eth4\n-----------------------------------\n\tAnd to disable the interface :\n-----------------------------------\nifdown eth4\n-----------------------------------\n\n\tThis solution is obviously Debian specific, but could be\nadapted to other distributions. If you can't manage to get your\ndistributions to use those tricks, you can do things manually.\n\tIf you don't use Hotplug, you enable an interface with :\n-----------------------------------\nmodprobe eth4\nifrename\nifup eth4\n-----------------------------------\n\tIf you use hotplug, you only need to do :\n-----------------------------------\nmodprobe eth4\n-----------------------------------\n\tOn the other hand, disabling the interface is done with :\n-----------------------------------\nifdown eth4\nmodprobe -r eth4\n-----------------------------------\n\n\n\tDocking stations for laptops may contain built-in\ninterfaces. My previous laptop had one, and Linux had no support for\nit. After docking, I was able to bring up the network ISA card in the\ndocking station.\n\tHowever, with most laptops and version of Linux, the issue is\nthat after docking, the new devices are not seen. The solutions is to\nforce a rescan of the PCI bus. Documentation is unclear on that, maybe\n'scanpci' may help.\n\n\tTo be able to simply manage my docking station, I had created\ntwo little scripts to enable and disable my network interface.\n\tAfter docking, you would run :\n-------- \/sbin\/dock ----------------------------\n#!\/bin\/sh\nmodprobe eth4\nifrename\nifup eth4\n------------------------------------------------\n\tAnd prior to undocking, you would run :\n-------- \/sbin\/undock ----------------------------\n#!\/bin\/sh\nifdown eth4\nmodprobe -r eth4\n------------------------------------------------\n\tThanks to 'ifrename', the network interface in your dock will\nalways be properly configured regardless of if you have a Pcmcia\nnetwork card in the Pcmcia slot or not.\n\n\nSCHEMES (MULTI-CONFIG)\n----------------------\n\tMost Ethernet cards will only connect to a single network, or\ncan use DHCP to be auto-configured. With Wireless Cards, it's much\nmore likely that you will need multiple configurations, for example at\nwork, at home and on-the-go.\n\n\tMost distributions have various level of support for such\nschemes. Some distributions offer simple network schemes, while other\noffer \"overall\" schemes changing the whole configuration. I document\nthe support for schemes in various distributions in the file\nDISTRIBUTIONS.txt.\n\n\tYou can also use tools such as ifplugd, waproamd or\nwlandetect. Those tools are a kind of \"wireless-DHCP\", they attempt to\nautomatically detect the proper wireless configuration and apply\nit. Most will also attempt to detect network changes.\n\tThe main limitation of those tools is that they offer very\nlittle manual control. If two valid alternatives are possible, you\ncan't switch between them. If a configuration can't be detected, they\nusually fail.\n\tThat's the same concept as using DHCP versus Static IP\naddresses. Some people are very happy with DHCP, my style is Static IP\naddresses.\n\n\tIf you use Debian and want to use simple manual schemes, these\nare the things you need to do.\n\t1) Make sure that 'ifscheme' and 'ifscheme-mapping' are\ninstalled on the system. You may find them in a separate tar file on\nmy web site.\n\t2) Check the path for 'ifscheme-mapping' (using whereis).\n\t3) Modify you \/etc\/network\/interface to add proper mapping and\nconfiguration.\n\n------- \/etc\/network\/interfaces ----------------------\n# Enable Hotplug support (Sarge and later)\nmapping hotplug\n    script echo\n\n# SMC 2835W wireless CardBus card\nmapping prism0\n    script \/sbin\/ifscheme-mapping\n\niface prism0-any inet dhcp\n    wireless-essid any\n    wireless-mode managed\n\niface prism0-adhoc inet static\n    address 10.0.1.2\n    network 10.0.1.0\n    netmask 255.255.255.0\n    broadcast 10.0.1.255\n    wireless-essid THE_ESSID\n    wireless-mode ad-hoc\n    wireless-channel 5\n\niface prism0-other inet static\n    address 10.10.10.2\n    network 10.10.10.0\n    netmask 255.255.255.0\n    broadcast 10.10.10.255\n    wireless-essid ANOTHER_ESSID\n    wireless-mode ad-hoc\n    wireless-key \"s:secure\"\n------------------------------------------------------\n\n\nFIRMWARE LOADING\n----------------\n\tA lot of modern wireless card don't have built in firmware and\nneed firmware loading. Recent kernels (2.6.X) have a firmware\nloader. These are a few notes on how to use it.\n\n\tFirst, read the documentation coming with your driver, because\neach driver has specificities (like the name of the firmware file it\nrequires). Some drivers may offer additional ways to load the\nfirmware, but in the long term things should be standardised around\nthe hotplug method to simplify packaging in distributions.\n\n\tYou need to compile your kernel with firmware loading\n(CONFIG_FW_LOADER in \"Generic Driver Options\"). If your driver was\nbuilt from the kernel, chances are that it enabled this feature\nalready. Make sure you boot from this new kernel.\n\n\tThe 'sysfs' file system must be mounted. The easiest is to\nmount it at boot time, add a line for it in \/etc\/fstab :\n\n-------- \/etc\/fstab ------------------------------\nsysfs\t\t\/sys\t      sysfs  defaults                   0      0\n--------------------------------------------------\n\n\tThen, you add the firmware file in the directory where it's\nexpected, which is \/lib\/firmware\/ in most cases, and\n\/usr\/lib\/hotplug\/firmware\/ on older systems.\n\n\tMost distributions nowadays have a version of the Hotplug\nscripts that knows how to deal with firmware. If it is not the case,\njust grab the 'firmware.agent' file from an alternate source and copy\nit into your \/etc\/hotplug directory (make sure it's executable).\n\tYou can try the canonical version :\n\t\thttp:\/\/linux-hotplug.sourceforge.net\/\n\tOr Debian's version :\n\t\thttp:\/\/packages.debian.org\/unstable\/admin\/hotplug\n\n\tNote that firmware loading will usually only work with\ninterfaces that are fully managed by Hotplug. This is the only way to\nensure the that proper sequence of action is happening in the right\norder every time. Firmware loading may not work properly for\ninterfaces configured in the init scripts.\n\tThis means that if you have a built-in interface that require\nfirmware loading, you should just use manage those interfaces like\nremovable interfaces (see section above). However, interface\nconfiguration need to be explicitly triggered at boot time.\n\n\tOne possibility is to set-up Hotplug to be run from the init\nscript at boot time. This is usually an option for recent\ndistributions (it's not the case for Hotplug in Debian 3.0). But, we\nhave seen that this has some issues.\n\tThe other possibility is to use an hybrid between the init\nscript method and the hotplug method. First, you need to add an alias\nfor the driver in \/etc\/modprobe.conf. Then, you need to specify a\nmapping for this interface in \/etc\/iftab, and specify a configuration\nfor this interface and that it is enabled at boot time. Lastly,\nyou make sure that the network init scripts run 'ifrename\n-p'. 'ifrename' will trigger the module to load, and all the Hotplug\nevents will be generated properly to configure the interface.\n\n\nDEVICES WITH MULTIPLE NAMES\/INTERFACES\n--------------------------------------\n\tSome wireless drivers offer multiple network interfaces for\nthe same device. A classical example is the Aironet driver that\ncreates a 'ethX' and 'wifiY' for each card.\n\n\t'ifrename' allows you a finer selection of interfaces than\n'nameif'. For example, to only rename the pseudo-Ethernet network\ninterface name of the Aironet driver, you would do :\n\n--------- \/etc\/iftab -----------------------\n# Cisco Aironet 350 wireless Pcmcia card\nairo*\t\tmac 00:07:0E:* arp 1\n---------------------------------------------\n\n\tAfter that, your device would be available through 'eth0' and\n'wifi0'.\n\n\tYou can rename both interfaces. You just need to remember that\n'ifrename' starts matching from the last line of the file, so you\nwould do :\n--------- \/etc\/iftab -----------------------\n# Cisco Aironet 350 wireless Pcmcia card\nwifi*\t\tmac 00:07:0E:* arp 801\nairo*\t\tmac 00:07:0E:* arp 1\n---------------------------------------------\n\n\tThe current version of 'ifrename' supports only the most useful\nselectors, but it is architectured such as adding selectors is relatively\ntrivial. If you find a case that 'ifrename' can't handle, you should\njust extend it.\n\n\nDEVICES WITHOUT MAC ADDRESSES\n-----------------------------\n\tMost Ethernet and Wireless devices have a fixed and unique MAC\naddress, and it is therefore advised to name them based on this\ncriteria. However, there are also network interfaces that don't have a\nfixed and unique MAC address, for example Ethernet over USB, IP over\nFireWire, PPP and tunnel interfaces.\n\tThe driver for those devices creates the interface with a name\nspecific to the driver, such as ppp* for PPP interfaces and usb* for\nEthernet over USB, and therefore they are easy to identify and\nconfigure, and few users feel the need to rename them. Moreover, some\nof them, such as PPP, have their own configuration scripts and\nmethodology addressing their unique needs.\n\n\tThere are a few cases where you might want to rename\ninterfaces without MAC addresses. One example is two Ethernet over USB\ndongles. The way to do this is to use alternate ifrename\nselectors. Choosing the right selector depends on what you want to\nachieve.\n\tA quick theoretical example to illustrate :\n--------- \/etc\/iftab -----------------------\n# All other usbnet devices\nusb*\t\tdriver usbnet\n# Specific usbnet devices\nusb-p\t\tfirmware \"Prolific PL-2301\/PL-2302\"\nusb-4\t\tbus-info usb-00:02.0-1.4\n---------------------------------------------\n\n\nTROUBLESHOOTING\n---------------\n\tIf your interface doesn't show up as expected with ifconfig,\nyou will need to find out why. First, you need to be familiar with the\nsequence of actions in the system and find which one did not happen.\n\n\t1) Interfaces on the system\n\t---------------------------\n\tYou first need to check which network interfaces are currently\navailable on your system and configuration was assigned to it. This is\nmostly done using 'ifconfig'.\n\tTo list only the configured network interfaces :\n--------------------------\n&gt; \/sbin\/ifconfig\n--------------------------\n\tThe list all network interfaces :\n--------------------------\n&gt; \/sbin\/ifconfig -a\n--------------------------\n\tYou can also use 'iwconfig' to check the wireless configuration.\n\n\t2) Modules\n\t----------\n\tYou need to check that the driver module(s) was loaded using\n'lsmod'.\n\n\tIf this device is configure via init scripts, you should test\nif the on-demand loading of module (module probing works). This is\ndone with :\n--------------------------\n&gt; \/sbin\/modprobe -r eth2\n&gt; \/sbin\/modprobe eth2\n--------------------------\n\n\tIf your module does not load, first you should check that the\nhardware is present. This depend on the bus used, for PCI bus you will\nuse 'lspci' and for USB bus you will use 'lsusb'.\n\tThe second step is to check if the driver for your hardware is\navailable on the system.\n\n\t3) Ifrename\n\t-----------\n\tYou need to check if the interface was properly renamed with\n'ifrename'. You can use 'ifrename -D -V' to debug your \/etc\/iftab.\n\tGet the list of interfaces on your system with 'ifconfig -a'\nor 'cat \/proc\/net\/dev', and check if an interface is using the name\nyou assigned or 'eth0'. Check any suspicious interfaces with 'ifconfig\neth0', and check its MAC address.\n\tVerify that no line in \/etc\/iftab matches the all-zero MAC\naddress. The all-zero MAC address matches the loopback interface 'lo'\nand various pseudo network devices, renaming the loopback interface is\nhighly discouraged.\n\tFinally, run ifrename in debug mode :\n--------------------------\n&gt; \/sbin\/ifrename -D -V\n--------------------------\n\n\tThe only case where running ifrename in debug mode would\ndiffer from when it is run normally are drivers that don't have valid\ndescriptor value until after ifrename is run. There are a few drivers,\nsuch as prism54, which don't have a proper MAC address before brought\nup. This obviously fools ifrename.\n\tA way to debug that is to change the way ifrename is called to\nsave the debug output. For example, you could call ifrename that way :\n------- \/etc\/hotplug\/net.agent ------------------\n\t\tNEWNAME=`\/sbin\/ifrename -i $INTERFACE -V 2&gt;&gt; \/var\/log\/ifrename`\n-------------------------------------------------\n\n\t4) Original Hotplug scripts\n\t---------------------------\n\tThe Hotplug subsystem has also good debugging facilities.\n\tTo enable Hotplug debugging, just make sure the variable DEBUG\nis defined in \/sbin\/hotplug :\n--------- \/sbin\/hotplug ------------------------------\n--- \/sbin\/hotplug-old      Tue Mar 26 09:00:20 2002\n+++ \/sbin\/hotplug       Fri Feb 20 18:40:38 2004\n@@ -22,7 +22,7 @@\n cd \/etc\/hotplug\n . hotplug.functions\n \n-# DEBUG=yes export DEBUG\n+DEBUG=yes export DEBUG\n \n if [ \"$DEBUG\" != \"\" ]; then\n     mesg \"arguments ($*) env (`env`)\"\n------------------------------------------------------\n\tThen, you can check your message logs for Hotplug events with\n'tail -f \/var\/log\/messages'. Verify that the various Hotplug events\nhappen as expected (pci, firmware, net...), and verify the log\nmessages from 'net.agent'.\n\n\t5) UDev\n\t-------\n\tThere are two main facilities to debug uDev, the 'udevtest'\nprogram and udev daemon debugging.\n\n\tThe uDev package comes with 'udevtest', a program that\nsimulate a hotplug event, however this has many limitations and is not\nexactly like the real thing.\n\tThe file 19-udev-ifrename.rules has a special rule to work\nwith udevtest. This rule runs ifrename in dry-run mode. This rule is\ndisabled by default, and if you intend to use udevtest you should\nenable this rule :\n--------- 19-udev-ifrename.rules ---------------------\n# Enable this rule to test with udevtest.\nENV{UDEV_LOG}==\"6\", SUBSYSTEM==\"net\", ACTION==\"add\", IMPORT=\"\/sbin\/ifrename -D -V -u -i %k\", NAME:=\"%k\"\n------------------------------------------------------\n\tThen, to test on a specific interface, you would run it like this :\n----------------------\n&gt; udevtest \/sys\/class\/net\/eth5\n[...]\nrun_program: '\/usr\/sbin\/ifrename' (stderr) 'Dry-run : Would rename eth0 to eth5.'\n[...]\nudev_rules_get_name: rule applied, 'eth0' becomes 'eth5'\n----------------------\n\tThe advantage of this procedure is that it's very simple to\ntry and all the output is on the console.\n\n\tThe enable udevd debugging, you need to change the default log\nlevel to \"debug\" in the file \/etc\/udev\/udev.conf :\n--------- \/etc\/udev\/udev.conf ------------------------\nudev_log=\"debug\"\n------------------------------------------------------\n\tYou will also need to reboot for this change to be\neffective. The alternative is to use 'udevcontrol'.\n\tMake sure the special udevtest rule for ifrename described\nabove is *NOT* enabled, i.e. it should be commented out or\neliminated.\n\tThe debug message may be spread in various log files depending\non the distribution. On Debian, I would find them with 'tail -f\n\/var\/log\/debug'.\n\n\n\n\n\tHave fun...\n\n\tJean<\/pre>\n","protected":false},"excerpt":{"rendered":"<p>Sane network interface management with Hotplug or uDev &#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212; INTRODUCTION &#8212;&#8212;&#8212;&#8212; In the old days all wireless cards were managed by the excellent Pcmcia subsystem and its rich configuration scripts, and life was good. Then came the wireless PCI cards, then the wireless USB dongles. Some unification was needed, and rather than adapt the Pcmcia subsystem for PCI and USB, it was decided to create the much simpler Hotplug system. The USB subsystem already uses Hotplug. The Pcmcia subsystem is migrating to it : CardBus cards (32 bits) already use Hotplug, whereas Pcmcia cards (16 bits) often still use the <\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[36],"tags":[],"class_list":["post-7435","post","type-post","status-publish","format-standard","hentry","category-resources"],"_links":{"self":[{"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/posts\/7435","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/comments?post=7435"}],"version-history":[{"count":1,"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/posts\/7435\/revisions"}],"predecessor-version":[{"id":7441,"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/posts\/7435\/revisions\/7441"}],"wp:attachment":[{"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/media?parent=7435"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/categories?post=7435"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.practicallynetworked.com\/wp-json\/wp\/v2\/tags?post=7435"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}