NAME
detect.conf — provides the configuration for detection of locations for
whereami.
DESCRIPTION
Syntax
The detect.conf file specifies the tests that allow whereami to figure
out where it is. The environment of such tests can be manipulated
using the ’set’ command. Tests can be performed conditionally upon the
results of other tests using "if ... fi" constructs.
Comments are lines starting with the ‘#’ character. Leading whitespace
is ignored on all lines, including comment lines.
Internal Commands
The syntax of this file is fairly straightforward. Tests are specified
thus:
testname parameter locations
The command testname is run with the single parameter (which
may be split internally). If the return value is 0, the test
is considered ‘successful’ and the locations are considered
‘discovered’.
locations is a list of comma separated identifiers, each one
matching the regexp ‘‘[[:alnum:]._-]+’’.
On success, processing will skip all non-‘always’ statements
up to the next ‘if’ or ‘fi’ keyword, whichever is earlier.
if location statements ... [elif location statements ...]... [else
statements ...] fi
If the location is in the list of locations discovered so
far, then the statements in the ‘if’ branch will be
processed. Otherwise, if present, the statements in either
the ‘elif’ or the ‘else’ (as appropriate) branch will be
processed.
Note that nesting of ‘if’ blocks is not supported at this
time.
always testname parameter locations
A test preceded by the word ‘always’ is not skipped unless it
is within the inactive branch of an ‘if’ clause.
set variable value
The environment variable is defined as value for all
subsequent test scripts and in the shell script eventually
constructed by whereami.
at locations
The locations will be added to the "discovered" list.
notat locations
The locations will be removed from the "discovered" list.
echo quoted text string
The "quoted text string" will be displayed to the user on
stdout.
The parameter and locations may be lists, with a comma (",") used
to separate multiple values.
Tests
Any program may be used as a test so long as it accepts a single
parameter and returns zero on success and non-zero on failure.
If a parameter of the test script must contain a space, it parameter
will need to be quoted.
A number of tests are included in the whereami package.
testdhcp [interface,]pattern
Tests for the assignment by DHCP of an IP address matching
the specified address pattern. If not specified, the
interface defaults to ‘eth0’.
Note that the first execution of this test during a
particular run of whereami induces a DHCP request on the
specified interface.
testmii interface
Checks for the presence of a link on interface using the mii-
tool utility. If a link is not found then the interface will
be ’down’ed to limit side-effects on other detection later.
testpppoe interface
Tries to start a PPPoE connection on the specified interface.
Success is returned if the connection starts.
testarp interface,mac_address,ip_address
Performs an arping (Debian package: iputils-arping) to look
for the specified mac_address and ip_address combination on
the network connected to interface.
testping [interface,]ip_to_ping,ip_to_use
Uses the fping program to perform a fast ping to look for the
presence of a particular host on the local network.
testpci pattern
Searches for the pattern in the output of lspci -v.
This enables checking for specific hardware, such as a
particular type of docking station.
testmodule pattern
Searches for the pattern in the output of lsmod.
This is useful for checking for the presence of a particular
PCMCIA card, or possibly a particular kernel configuration.
testap [interface,]scan
testap pattern[,WEP Key]
testap [interface,]pattern,WEP Key
The pattern is a regexp (egrep regexp) used to match AP
essids: when this regexp matches a detected essid the test is
considered succesfull.
This check does not require encryption to be set up to work,
although it may not find stealthier equipment - use testssid
in that case.
The ’scan’ option will cause a new scan, and the first call
should have this option set. Subsequent calls will use the
results of that first scan, reducing the overhead for those
busy people who connect to many WLANs!
If a WEP key is supplied, and a pattern match is found, the
key will be assigned to that interface so that subsequent
tests should work correctly.
When using the WEP key you may in some cases desire to pass
additional parameters to iwconfig. These parameters may be
passed preceding the WEP key and separated with an
underscore. For example "restricted_0123-4567-89" will force
the card to be configured to insist on ’restricted’ mode at
the same time as the key was set.
testappassive [interface,]scan
testappassive pattern
testap [interface,]pattern
Checks whether the specified AP is present, passively. This
check does not alter the essid on the interface, or set the
WEP key like the testap test. It just uses iwlist interface
scan. This is useful where you have another external script
that sets up all the wifi settings, and running whereami a
second time destroys the running wifi connection, as can
happen on boot where networking is intialised before whereami
starting in run level 2.
The ’scan’ option will cause a new scan, and the first call
should have this option set. Subsequent calls will use the
results of that first scan, reducing the overhead for those
busy people who connect to many WLANs!
testprocsys proc-or-sys-path,egrep-pattern
Checks the specified /sys or /proc file to see if it contains
the given egrep expression. Non-existent file results in
failure, as well as a failed match. Useful for those
interfaces that require to hotplug to be configured so that
firmware can be loaded. On machine shutdown, hotplug can be
disabled before networking interfaces, and this enables
whereami to function correctly in those circumstances.
testssid ssid[,key]
Checks whether the wireless interface is in range of the
specified ssid, using the key if supplied. The key should be
formatted as for iwconfig. What works for me looks like
da18babe100ea4beadb74324bc ("128" bits) or fe3d1b3ed7 (40
bits).
This script will also respond to a TIMEOUT variable which is
set before it is called, but waiting for $TIMEOUT seconds for
the network to settle (default 2).
This is useful for checking which wireless LAN is in range.
testreceived [interface]
Checks whether the interface in question has received any
bytes.
This is useful for checking which network interface is
actually connected to a network.
EXAMPLES
The following examples show simple setups, firstly for a wired only
configuration, and secondly for a mixed wireless and wired setup.
A Simple Wired DHCP Configuration
# Simple wired DHCP with two networks
default undocked
testmii eth0 lan
if lan
set INTERFACE eth0
testdhcp restart dhcp
fi
if dhcp
testdhcp ’192.168.1.1’ home
testdhcp ’152.81.*.*’ univ
fi
A Wired and Wireless Configuration
# Configuration including both wired and wireless networks
default undocked
testmii eth0 lan
# We prefer a wired network, but if we aren’t wired
# we will look for a WLAN.
if lan
set INTERFACE eth0
testdhcp restart dhcp
else
set INTERFACE wlan0
testap scan wlan
fi
# Try WLANs until it we find one that works
if wlan
testap homessid,dead-beef-dead-beef-dead-beef-be wlhome_enc
testap homessid wlhome_open
fi
# If we are at a WLAN we should have the AP setup now
if wlan
# WLAN almost always will be DHCP
testdhcp restart dhcp
fi
# Now identify the actual network
if dhcp
testdhcp ’192.168.1.1’ home
testdhcp ’192.168.1.2’ wlhomeip
testdhcp ’152.81.*.*’ work
fi
SEE ALSO
whereami(8), whereami.conf(5)
Further documentation is available in the /usr/share/doc/whereami
directory.
FILES
/etc/whereami/detect.conf
The file we are talking about in this here manpage.
/etc/whereami/whereami.conf
Defines the actions performed as a result of entering,
leaving, or remaining at a particular location.
LIMITATIONS
The ‘if’ syntax does not support nesting.
AUTHOR
This manual page was written by Andrew McMillan <awm@debian.org> for
the Debian GNU/Linux system (but may be used by others). Permission is
granted to copy, distribute and/or modify this document under the terms
of the GPL version 2.
detect.conf(5)