detect.conf(5)							File Formats Manual						    detect.conf(5)

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.  Other-
		 wise, 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 net-
		 work 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 config-
		 ured 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  net-
		 working 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)