Provided by: whereami_0.3.34-0.4_all bug

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)