The laptop-net package is a configuration mechanism for laptop computers that have built-in network interfaces. It extends the standard GNU/Linux networking administration tools to facilite moving the laptop between several different networking environments. In addition, for computers with supported network interfaces, it also automatically detects network cable insertion and removal.
The package is built around two basic concepts, which will be described below in greater detail. First, there is configuration information that describes how the network should be initialized for a particular location. This information is organized as a set of named schemes, each of which describes the network configuration for a particular location. For example, a typical network configuration would specify an @acronym{IP} address, an associated netmask, a gateway, etc. Second, there is configuration information that specifies higher-level details, such as a copy of `/etc/printcap' describing the printers available at that location. This higher-level information is organized as a set of named profiles, which are indexed by @acronym{IP}-address patterns. Together, these two mechanisms provide a flexible means for configuring the network environment.
The profile mechanism is modeled on a similar mechanism in the
boot-profiles package, written by Al Stone. The mechanism here
is my attempt to integrate this functionality directly into the
network-management code. The schemes mechanism is modeled on the
schemes mechanism of pcmcia-cs, written by David Hinds.
This package has been designed and tested on http://www.hp.com/ OmniBook model http://www.hp.com/notebooks/us/eng/products/omnibook_6000/omnibook_6000_summary.htm and http://www.hp.com/notebooks/us/eng/products/omnibook_500/omnibook_500_summary.htm computers, which were provided by Hewlett-Packard as part of their support for the development of this software. Although it has not yet been tried on other computers, the package is designed to be general and should port easily.
The package has been tested only on systems running http://www.debian.org/. And unfortunately one key piece of the code is specific to Debian, which means that porting this code to other GNU/Linux systems requires a little thought. However, the Debian-specific code has been isolated as well as possible from the rest of the package.
The configuration file defines some global configuration information for the program, and is named `/etc/laptop-net/config'. It is a Bourne shell script that is expected to set some shell variables defining the network configuration.
The laptop-net package organizes network-configuration information as a set of named schemes. Each scheme normally defines the network configuration for a particular location. But a scheme can also specify that http://www.ietf.org/rfc/rfc2131.txt} (@acronym{DHCP}) is to be used to obtain the network configuration; such a scheme can be used to configure the network at any location that provides @acronym{DHCP} service.
At any time, there is a selected scheme. On Debian systems, the selected scheme can be printed by running the command
/etc/init.d/laptop-net scheme
The initial scheme is named `default'. A new scheme name may be selected by running the command
/etc/init.d/laptop-net scheme name
Alternatively, the scheme can be automatically selected by specifying one or more @acronym{IP} addresses that are associated with a particular scheme. Then, when the laptop is connected to a network, it probes the local subnet for those addresses, and if one of them is found, it selects the associated scheme.
Schemes are defined by editing a configuration file named `/etc/laptop-net/schemes'. This file is a Bourne shell script that is expected to set some shell variables defining the network configuration. Some shell variables are passed in to the configuration file when it is executed. The script should use these variables to determine what to do:
There are many variables that may be set by the configuration file, but they are divided into groups according to the basic configuration type. There are three different configuration types, as follows.
Here are the variables specifically for dynamic configuration:
Here are the variables specifically for static configuration:
The following variables are required for static configuration. (Only one of @env{DOMAIN} and @env{SEARCH} need be set.) For dynamic configuration, they are optional and usually not needed.
Laptop-net has the ability to automatically choose the scheme by probing the network. This is accomplished by associating one or more @acronym{IP} addresses with some or all of your schemes. When the computer is connected to a network, it probes the network to see which of the @acronym{IP} addresses are located on the local subnet. If one of the @acronym{IP} addresses is found, the associated scheme is selected.
The association between scheme names and @acronym{IP} addresses is stored in a configuration file named `/etc/laptop-net/ip-map'; this file is normally called the IP map. The @acronym{IP} map consists of a number of one-line entries. Each line starts with the name of a scheme in the first column, and is followed by one or more @acronym{IP} addresses, separated by space or tab characters. Blank lines are allowed, as are comments that begin with the `#' character and extend to the end of the line.
If the @acronym{IP} map file contains one or more entries, then the network is probed by sending out an http://www.ietf.org/rfc/rfc826.txt} (@acronym{ARP}) request packet for each @acronym{IP} address appearing in the map. If an @acronym{ARP} reply packet is received, its source @acronym{IP} address is looked up in the map, and the associated scheme is selected. (Only the first reply is used; subsequent replies are ignored.) If no replies are received, then one of two things happens. If the selected scheme was manually selected by the user, then it is not changed. However, if the selected scheme was automatically selected by a previous network probe, then the `default' scheme is selected.
If the @acronym{IP} map file contains no entries, or if it doesn't exist, then the network is not probed and the selected scheme is not automatically changed.
Here is a complete example to give you an idea of the overall structure of the schemes file:
case $SCHEME in
home)
# At home we use static configuration.
ADDRESS=192.168.1.6
NETMASK=255.255.255.0
GATEWAY=192.168.1.254
SEARCH="ai.mit.edu mit.edu"
NAMESERVERS="24.128.44.6 24.128.52.6 24.128.1.80"
;;
offline)
# The offline scheme turns the network off.
;;
*)
# All other schemes use dynamic configuration.
DHCP=yes
;;
esac
And here is an associated @acronym{IP} map file:
home 192.168.1.1 192.168.1.2 office 192.168.2.1 192.168.2.2 192.168.2.3
The second layer of configuration is the profile layer, which adapts the software configuration of the computer to match the network environment. For example, if you have profiles for the home and for the office, you will usually need to have a different copy of the `/etc/printcap' file for each location, because each has different printers.
A profile consists of some files that are copied into the file system, and some shell scripts that are run when the profile is selected or deselected. Each profile also has a set of patterns that specify the @acronym{IP} addresses that this profile is associated with. Whenever the network is reconfigured, either to turn it on, turn it off, or change the network address, laptop-net searches the available profiles to find one that matches. If the new profile is different from the current one, then the current one is deselected and the new one is selected.
The behavior of profiles could have been integrated into the schemes layer. But profiles are implemented as a separate layer because it makes them more flexible. This is because a named scheme that uses dynamic configuration can have different @acronym{IP} addresses, and each of those addresses might map to a different profile. Or there might be two different schemes that map to the same profile, for example when you have a statically-configured scheme and a dynamically-configured scheme that can each be used at the same network location.
Profiles are defined by creating directories in the profiles directory, which is named `/etc/laptop-net/profiles'. A profile is a subdirectory of the profiles directory. The first character of the name of the subdirectory must be either a lower-case letter or a digit; other subdirectories are ignored. Some examples of profile subdirectories are
/etc/laptop-net/profiles/home /etc/laptop-net/profiles/office /etc/laptop-net/profiles/default
A profile subdirectory itself contains other files and subdirectories, each with a specific purpose, as follows.
(cd files.d; /bin/cp -pr * /)which means that all file permissions are preserved, and that the contents of subdirectories are also copied. This also means that files starting with the character `.' will not be copied.
before-select /etc/laptop-net/profiles home
The management of profiles consists of two processes. First is the profile matching process, in which the set of available profiles is searched to find one that matches the current @acronym{IP} address. Second is the profile selection process, in which the current profile is deselected and the new one selected.
Profile matching follows a simple search pattern. First, the current @acronym{IP} address is determined. This can have one of three values:
Next, the profiles are searched in alphabetical order by name. Each profile is tested by examining the contents of its `patterns' file. (If the file doesn't exist or can't be read, the profile is ignored.) Each pattern in the file is tested against the @acronym{IP} address, and if one of the patterns matches, then this profile is considered to match the address.
This search pattern can be exploited to create a default profile, which is used when nothing else matches. To do this, create a profile with a name that will always sort after all other profile names (e.g. `zzz-default'), and give it a single pattern `*'.
Once the new profile has been determined by the matching process, it must be selected. (Note, however, that nothing is done if the new profile is the same as the current one.) The selection process has two phases. First, if there is a current profile, we perform the following steps to deselect it:
Next, if there is a new profile, we perform the following steps to select it:
It is worth mentioning that the selection process provides for situations in which there is no profile. Thus, when there is no current profile, the new profile is still correctly selected. Likewise, when there is a current profile but no new one, the current one will still be deselected.
The one remaining complexity is the `rc.d/' directory, which requires a little background. Most GNU/Linux systems employ a mechanism called SysV init scripts, in which each system service has a corresponding shell script that is used to turn it on and off. The full details of how this works are unimportant, but in a nutshell, the script is called with the argument `start' to start the service, and `stop' to stop it. On Debian systems, these scripts are normally stored in the directory `/etc/init.d/', but on some other systems (e.g. Red Hat Linux) they are stored in `/etc/rc.d/init.d/'.
The `rc.d/' directory contains symbolic links to these scripts, with special names that control how they are started and stopped, and in what order. Each name consists of a letter, either `S' or `K', followed by two decimal digits, followed by the name of the script. Examples of these names for the `lpd' script would be `S20lpd' and `K20lpd'.
The names are interpreted as follows. When selecting a profile, we start all the services in the `rc.d/' directory. This means we find all of the links starting with `S', and in standard dictionary order, call each one with the argument `start'. When deselecting a profile, we find all the links starting with `K' and call them in order with the argument `stop'.
Note that the operating system has similar links stored in directories called `/etc/rcN.d/', where N is a digit. (The directories are called `/etc/rc.d/rcN.d/' on Red Hat systems.) Normally you should use the same link names as those that appear in the operating system's directories, since the system's maintainers have already determined appropriate orders for starting and stopping services. Furthermore, for best operation you should delete the operating system's links, since those services will now be controlled by laptop-net instead. (On Debian systems, the links are managed with the program @command{update-rc.d}; see that program's man page for instructions on how to remove the links.)
The profile mechanism also can be used with @acronym{PCMCIA} devices.
However, in order for this to work, it's necessary to edit the
pcmcia-cs configuration files. Specifically, the file
`/etc/pcmcia/network.opts' must be edited, and the following
functions defined there.
start_fn ()
{
/usr/share/laptop-net/profile-change $DEVICE
}
stop_fn ()
{
/usr/share/laptop-net/profile-change $DEVICE down
}
If these functions already exist, the calls to `profile-change' must be added into them. Note that it is important that `profile-change' be called every time that this script is invoked: otherwise the profile mechanism might get out of sync with the network.
Another consideration occurs because there might be an internal network interface and a @acronym{PCMCIA} network interface that are both active at the same time. If there is a possibility of such a situation, you must make sure that both devices are using the same profile! Otherwise the profile mechanism can get confused.
The profile mechanism is somewhat complicated, so let's look at a complete example to see how it might be used. First, here is a listing of the files in our example profiles directory.
/etc/laptop-net/profiles: total 20 drwxr-xr-x 2 root 4096 Jun 11 11:34 SHARED drwxr-xr-x 5 root 4096 Jun 8 23:33 home drwxr-xr-x 2 root 4096 Jun 8 23:34 offline drwxr-xr-x 5 root 4096 Jun 11 11:36 work drwxr-xr-x 3 root 4096 Jun 8 23:34 zzz-default
This shows four profile subdirectories, named `home', `offline', `work', and `zzz-default'. The subdirectory named `SHARED' isn't a profile, because it begins with an upper-case letter. We'll see later how this is used.
The simplest of these profiles is `offline':
/etc/laptop-net/profiles/offline: total 4 -rw-r--r-- 1 root 13 Jun 7 23:43 patterns
Here is the contents of the file `offline/patterns':
down unknown
This profile catches the case where the network is not running. It doesn't do anything in that case. Note that we could have omitted this profile and the end result would be exactly the same.
Next, let's look at one of the two primary profiles, `home':
/etc/laptop-net/profiles/home: total 24 drwxr-xr-x 2 root 4096 Jun 11 11:36 LOCAL -rwxr-xr-x 2 root 80 Jun 8 15:25 after-select -rwxr-xr-x 2 root 378 Jun 8 15:09 before-select drwxr-xr-x 3 root 4096 Jun 8 23:30 files.d -rw-r--r-- 1 root 12 Jun 7 22:59 patterns drwxr-xr-x 2 root 4096 Jun 11 11:39 rc.d
This profile uses most of the features of the profile mechanism: the `before-select' and `after-select' scripts, the `files.d/' directory, and the `rc.d/' directory. It additionally has a `LOCAL/' directory that is not directly used by the profile mechanism, but is referred to by one of the scripts. This profile matches the following `patterns':
192.168.1.*
When this profile is selected, the `before-select' script is run. This script uses information from the `SHARED' and `LOCAL' directories to create a file `/etc/fstab'. This is saved in the `files.d/' directory, where it will subsequently be copied into the root file system.
#!/bin/sh
PROFILE_DIR="$1"
PROFILE="$2"
FSTAB="$PROFILE_DIR/$PROFILE/files.d/etc/fstab"
FSTAB_SHARED="$PROFILE_DIR/SHARED/fstab"
FSTAB_LOCAL="$PROFILE_DIR/$PROFILE/LOCAL/fstab"
if [ ! -f "$FSTAB" ] \
|| [ "$FSTAB_SHARED" -nt "$FSTAB" ] \
|| [ "$FSTAB_LOCAL" -nt "$FSTAB" ]; then
cat "$FSTAB_SHARED" "$FSTAB_LOCAL" > "$FSTAB"
fi
Other files are also stored in the `files.d/' directory:
/etc/laptop-net/profiles/home/files.d: total 4 drwxr-xr-x 2 root 4096 Jun 11 11:35 etc /etc/laptop-net/profiles/home/files.d/etc: total 4 -rw-r--r-- 1 root 951 Jun 22 1999 printcap
Some system services are started and stopped from the `rc.d/' directory:
/etc/laptop-net/profiles/home/rc.d: total 0 lrwxrwxrwx 1 root 15 Jun 11 11:39 K20lpd -> /etc/init.d/lpd lrwxrwxrwx 1 root 19 Jun 11 11:39 K22ntpdate -> /etc/init.d/ntpdate lrwxrwxrwx 1 root 15 Jun 11 11:39 K23ntp -> /etc/init.d/ntp lrwxrwxrwx 1 root 15 Jun 11 11:39 S20lpd -> /etc/init.d/lpd lrwxrwxrwx 1 root 19 Jun 11 11:39 S22ntpdate -> /etc/init.d/ntpdate lrwxrwxrwx 1 root 15 Jun 11 11:39 S23ntp -> /etc/init.d/ntp
Then we run the `after-select' script, which changes the
pcmcia-cs "scheme" to match the current profile:
#!/bin/sh PROFILE_DIR="$1" PROFILE="$2" /sbin/cardctl scheme "$PROFILE"
And that's it for the `home' profile. The `work' profile is nearly identical, except for some of the contents of the files in `files.d/', and of course the `patterns' file:
18.*.*.* 128.52.*.*
Finally, we have the `zzz-default' profile, which is a kind of catch-all profile for locations that don't have specific profiles defined for them:
/etc/laptop-net/profiles/zzz-default: total 8 -rw-r--r-- 1 root 8 Jun 7 23:46 patterns drwxr-xr-x 2 root 4096 Jun 11 11:39 rc.d
`zzz-default' has a `patterns' file that matches any @acronym{IP} address. The profile's name starts with `zzz' so that this pattern isn't tested until all other profiles have been tried.
*.*.*.*
This profile isn't specialized in any way, except to turn the `ntp' service on when it is selected:
/etc/laptop-net/profiles/zzz-default/rc.d: total 0 lrwxrwxrwx 1 root 19 Jun 11 11:39 K22ntpdate -> /etc/init.d/ntpdate lrwxrwxrwx 1 root 15 Jun 11 11:39 K23ntp -> /etc/init.d/ntp lrwxrwxrwx 1 root 19 Jun 11 11:39 S22ntpdate -> /etc/init.d/ntpdate lrwxrwxrwx 1 root 15 Jun 11 11:39 S23ntp -> /etc/init.d/ntp
Another major feature of this package is automatic detection of the ethernet link beat. The link beat, when active, indicates that the physical ethernet connection is operating correctly; in other words, that the network cable is plugged into both the computer and the hub, and that both network interfaces are functioning. Unplugging the cable or turning off the network hub will stop the link beat.
On network interfaces that support link-beat detection, laptop-net monitors the link beat. When it detects that the link beat has stopped, it brings the network interface down. If the link beat later starts again, laptop-net brings the network interface back up. In either case, when the network interface goes up or down, laptop-net reinitializes the network and potentially switches to another profile.
In practice, the reason why this is useful is that it allows you to move the computer around by unplugging the network cable, moving the computer to another location, then plugging it back in. The software will detect these events and manage the interface as needed. Even better, if the machine uses dynamic configuration (and both of the networks support it), when the machine is plugged into the second network, it will get a new @acronym{IP} address and automatically select a new profile. So, for example, you can unplug the computer at the office, go home, plug it in, and continue working without any manual intervention to tell the computer where it is.
The one caveat for this support is that you should be fairly certain that any services currently using the network are stopped before you unplug the network cable. This includes any open network connections or mounted @acronym{NFS} volumes. Otherwise, you'll be left with dangling connections; and once the cable is unplugged it is difficult to shut these connections down cleanly. (One simple way to detect open @acronym{TCP} connections is to run the command `netstat -t' and look for connections whose `State' is `ESTABLISHED'.)
The other potential problem with link-beat detection is that it is not
supported by all network drivers; it depends on a feature called the
Media Independent Interface (@acronym{MII}). However,
@acronym{MII} is supported by most recent network cards, and most
importantly, it is supported by the cards currently in use by most
laptops. (The following Linux 2.4.5 drivers support @acronym{MII}, and
should provide link-beat detection capability: 3c59x,
8139too, e100, eepro100, epic100, fealnx,
hamachi, ioc3-eth, natsemi, pcnet32,
pegasus, sis900, starfire, sundance,
tlan, tulip, via-rhine, winbond-840, and
yellowfin.)
For network drivers that don't support @acronym{MII}, set the configuration variable @env{MII_SUPPORTED} to `"no"' and link-beat detection will be disabled.
Jump to: a - b - c - d - g - i - l - m - n - o - p - s
This document was generated on 22 April 2005 using texi2html 1.56k.