hotplug.txt

This package contains the Wireless tools, used to manipulate the Wireless Extensions. The Wireless

MANUAL LOADING, DOCKING STATIONS
--------------------------------
	Manual loading is used for built-in network interfaces that
are only use at specific time, and that you want disabled the rest of
the time. We assume that you still use modules so that when the
interface is not used you can remove the driver from the kernel.

	First, you need to set the configuration for those interfaces,
the same way it's done for other network interfaces. The main
difference is that you need to specify that those interfaces should
not be enabled at boot time. It's also a good idea to disable Hotplug
init scripts.
	With Debian, you just need to make sure that the 'auto"
keyword doesn't apply to this interface.

	If you use drivers statically built in the kernel, make sure
that ifrename runs at boot time (see CONFIGURATION FROM INIT
SCRIPTS). Once it's done, you can just enable and disable those
interfaces with 'ifup ethX' and 'ifdown ethX'.

	If you use both a modular system, make sure that the
'on-demand' module loading is properly configured :

--------- /etc/modprobe.d/local or /etc/modprobe.conf ------
# HP 100VG J2585B PCI card
alias eth2 hp100

# AMD AMD PCnet LANCE PCI card
alias eth4 pcnet32
------------------------------------------------------------

	Then, you should instruct 'ifup' to load module and use
ifrename prior to configuring the interface, and remove the module
when going down. With Debian, this is done with :

--------- /etc/network/interfaces -----------
# AMD AMD PCnet LANCE PCI card
# noauto
iface eth4 inet dhcp
    pre-up /sbin/ifrename -p -n eth4
    post-down /sbin/modprobe -r eth4

# HP 100VG J2585B PCI card
# noauto
iface eth2 inet static
    address 10.0.0.2
    netmask 255.255.255.0
    broadcast 10.0.0.255
    gateway 10.0.0.1
    pre-up /sbin/ifrename -p -n eth2
    post-down /sbin/modprobe -r eth2
---------------------------------------------

	We use the '-n' option of ifrename to specify the name of the
interface after renaming. This assume that the mapping for those
interfaces don't use wildcards. The '-p' option make sure ifrename
probes the module prior to using it.
	Using "modprobe -r" make sure that if the driver is composed
of multiple module all the modules are unloaded.
	
	To enable the interface, just use :
-----------------------------------
ifup eth4
-----------------------------------
	And to disable the interface :
-----------------------------------
ifdown eth4
-----------------------------------

	This solution is obviously Debian specific, but could be
adapted to other distributions. If you can't manage to get your
distributions to use those tricks, you can do things manually.
	If you don't use Hotplug, you enable an interface with :
-----------------------------------
modprobe eth4
ifrename
ifup eth4
-----------------------------------
	If you use hotplug, you only need to do :
-----------------------------------
modprobe eth4
-----------------------------------
	On the other hand, disabling the interface is done with :
-----------------------------------
ifdown eth4
modprobe -r eth4
-----------------------------------


	Docking stations for laptops may contain built-in
interfaces. My previous laptop had one, and Linux had no support for
it. After docking, I was able to bring up the network ISA card in the
docking station.
	However, with most laptops and version of Linux, the issue is
that after docking, the new devices are not seen. The solutions is to
force a rescan of the PCI bus. Documentation is unclear on that, maybe
'scanpci' may help.

	To be able to simply manage my docking station, I had created
two little scripts to enable and disable my network interface.
	After docking, you would run :
-------- /sbin/dock ----------------------------
#!/bin/sh
modprobe eth4
ifrename
ifup eth4
------------------------------------------------
	And prior to undocking, you would run :
-------- /sbin/undock ----------------------------
#!/bin/sh
ifdown eth4
modprobe -r eth4
------------------------------------------------
	Thanks to 'ifrename', the network interface in your dock will
always be properly configured regardless of if you have a Pcmcia
network card in the Pcmcia slot or not.


SCHEMES (MULTI-CONFIG)
----------------------
	Most Ethernet cards will only connect to a single network, or
can use DHCP to be auto-configured. With Wireless Cards, it's much
more likely that you will need multiple configurations, for example at
work, at home and on-the-go.

	Most distributions have various level of support for such
schemes. Some distributions offer simple network schemes, while other
offer "overall" schemes changing the whole configuration. I document
the support for schemes in various distributions in the file
DISTRIBUTIONS.txt.

	You can also use tools such as ifplugd, waproamd or
wlandetect. Those tools are a kind of "wireless-DHCP", they attempt to
automatically detect the proper wireless configuration and apply
it. Most will also attempt to detect network changes.
	The main limitation of those tools is that they offer very
little manual control. If two valid alternatives are possible, you
can't switch between them. If a configuration can't be detected, they
usually fail.
	That's the same concept as using DHCP versus Static IP
addresses. Some people are very happy with DHCP, my style is Static IP
addresses.

	If you use Debian and want to use simple manual schemes, these
are the things you need to do.
	1) Make sure that 'ifscheme' and 'ifscheme-mapping' are
installed on the system. You may find them in a separate tar file on
my web site.
	2) Check the path for 'ifscheme-mapping' (using whereis).
	3) Modify you /etc/network/interface to add proper mapping and
configuration.

------- /etc/network/interfaces ----------------------
# Enable Hotplug support (Sarge and later)
mapping hotplug
    script echo

# SMC 2835W wireless CardBus card
mapping prism0
    script /sbin/ifscheme-mapping

iface prism0-any inet dhcp
    wireless-essid any
    wireless-mode managed

iface prism0-adhoc inet static
    address 10.0.1.2
    network 10.0.1.0
    netmask 255.255.255.0
    broadcast 10.0.1.255
    wireless-essid THE_ESSID
    wireless-mode ad-hoc
    wireless-channel 5

iface prism0-other inet static
    address 10.10.10.2
    network 10.10.10.0
    netmask 255.255.255.0
    broadcast 10.10.10.255
    wireless-essid ANOTHER_ESSID
    wireless-mode ad-hoc
    wireless-key "s:secure"
------------------------------------------------------

FIRMWARE LOADING
----------------
	A lot of modern wireless card don't have built in firmware and
need firmware loading. Recent kernels (2.6.X) have a firmware
loader. These are a few notes on how to use it.

	First, read the documentation coming with your driver, because
each driver has specificities (like the name of the firmware file it
requires). Some drivers may offer additional ways to load the
firmware, but in the long term things should be standardised around
the hotplug method to simplify packaging in distributions.

	You need to compile your kernel with firmware loading
(CONFIG_FW_LOADER in "Generic Driver Options"). If your driver was
built from the kernel, chances are that it enabled this feature
already. Make sure you boot from this new kernel.

	The 'sysfs' file system must be mounted. The easiest is to
mount it at boot time, add a line for it in /etc/fstab :

-------- /etc/fstab ------------------------------
sysfs		/sys	      sysfs  defaults                   0      0
--------------------------------------------------

	Then, you add the firmware file in the directory where it's
expected, which is /usr/lib/hotplug/firmware/ in most cases.

	Most distributions nowadays have a version of the Hotplug
scripts that knows how to deal with firmware. If it is not the case,
just grab the 'firmware.agent' file from an alternate source and copy
it into your /etc/hotplug directory (make sure it's executable).
	You can try the canonical version :
		http://linux-hotplug.sourceforge.net/
	Or Debian's version :
		http://packages.debian.org/unstable/admin/hotplug

	Note that firmware loading will usually only work with
interfaces that are fully managed by Hotplug. This is the only way to
ensure the that proper sequence of action is happening in the right
order every time. Firmware loading may not work properly for
interfaces configured in the init scripts.
	This means that if you have a built-in interface that require
firmware loading, you should just use manage those interfaces like
removable interfaces (see section above). However, interface
configuration need to be explicitly triggered at boot time.

	One possibility is to set-up Hotplug to be run from the init
script at boot time. This is usually an option for recent
distributions (it's not the case for Hotplug in Debian 3.0). But, we
have seen that this has some issues.
	The other possibility is to use an hybrid between the init
script method and the hotplug method. First, you need to add an alias
for the driver in /etc/modprobe.conf. Then, you need to specify a
mapping for this interface in /etc/iftab, and specify a configuration
for this interface and that it is enabled at boot time. Lastly,
you make sure that the network init scripts run 'ifrename
-p'. 'ifrename' will trigger the module to load, and all the Hotplug
events will be generated properly to configure the interface.

DEVICES WITH MULTIPLE NAMES
---------------------------
	Some wireless drivers offer multiple network interfaces for
the same device. A classical example is the Aironet driver that
creates a 'ethX' and 'wifiY' for each card.

	'ifrename' allows you a finer selection of interfaces than
'nameif'. For example, to only rename the pseudo-Ethernet network
interface name of the Aironet driver, you would do :

--------- /etc/iftab -----------------------
# Cisco Aironet 350 wireless Pcmcia card
airo*		mac 00:07:0E:* arp 1
---------------------------------------------

	After that, your device would be available through 'eth0' and
'wifi0'.

	You can rename both interfaces. You just need to remember that
'ifrename' starts matching from the last line of the file, so you
would do :
--------- /etc/iftab -----------------------
# Cisco Aironet 350 wireless Pcmcia card
wifi*		mac 00:07:0E:*
airo*		mac 00:07:0E:* arp 1
---------------------------------------------

	The current version of 'ifrename' supports only the most useful
selectors, but it is architectured such as adding selectors is relatively
trivial. If you find a case that 'ifrename' can't handle, you should
just extend it.

DEVICES WITHOUT MAC ADDRESSES
-----------------------------
	Most Ethernet and Wireless devices have a fixed and unique MAC
address, and it is therefore advised to name them based on this
criteria. However, there are also network interfaces that don't have a
fixed and unique MAC address, for example Ethernet over USB, IP over
FireWire, PPP and tunnel interfaces.
	The driver for those devices creates the interface with a name
specific to the driver, such as ppp* for PPP interfaces and usb* for
Ethernet over USB, and therefore they are easy to identify and
configure, and few users feel the need to rename them. Moreover, some
of them, such as PPP, have their own configuration scripts and
methodology addressing their unique needs.

	There are a few cases where you might want to rename
interfaces without MAC addresses. One example is two Ethernet over USB
dongles. The way to do this is to use alternate ifrename
selectors. Choosing the right selector depends on what you want to
achieve.
	A quick theoretical example to illustrate :
--------- /etc/iftab -----------------------
# All other usbnet devices
usb*		driver usbnet
# Specific usbnet devices
usb-p		firmware "Prolific PL-2301/PL-2302"
usb-4		bus-info usb-00:02.0-1.4
---------------------------------------------

TROUBLESHOOTING
---------------
	If your interface doesn't show up as expected with ifconfig,
you will need to find out why. First, you need to be familiar with the
sequence of actions in the system and find which one did not happen.

	You need to check that the driver module(s) was loaded using
'lsmod'.

	You need to check if the interface was properly renamed with
'ifrename'. You can use 'ifrename -D -V' to debug your /etc/iftab.
	Get the list of interfaces on your system with 'ifconfig -a'
or 'cat /proc/net/dev', and check if an interface is using the name
you assigned or 'eth0'. Check any suspicious interfaces with 'ifconfig
eth0', and check its MAC address. Note that some rare drivers don't
have a proper MAC address before brought up, which fools ifrename.
	Verify that no line in /etc/iftab matches the all-zero MAC
address. The all-zero MAC address matches the loopback interface 'lo'
and various pseudo network devices, renaming the loopback interface is
highly discouraged.

	You need to check which configuration was given to the
interface using 'ifconfig' and 'iwconfig'.

	The Hotplug subsystem has also good debugging facilities.
	To enable Hotplug debugging, just make sure the variable DEBUG
is defined in /sbin/hotplug :
--------- /sbin/hotplug ------------------------------
--- /sbin/hotplug-old      Tue Mar 26 09:00:20 2002
+++ /sbin/hotplug       Fri Feb 20 18:40:38 2004
@@ -22,7 +22,7 @@
 cd /etc/hotplug
 . hotplug.functions
 
-# DEBUG=yes export DEBUG
+DEBUG=yes export DEBUG
 
 if [ "$DEBUG" != "" ]; then
     mesg "arguments ($*) env (`env`)"
------------------------------------------------------
	Then, you can check your message logs for Hotplug events with
'tail -f /var/log/messages'. Verify that the various Hotplug events
happen as expected (pci, firmware, net...), and verify the log
messages from 'net.agent'.


	Have fun...

	Jean