Provided by: whereami_0.3.34-0.1_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)