bionic (5) detect.conf.5.gz

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)