# whereami - Location Detection

## Detection

/etc/whereami/detect.conf tells whereami how to detect the current location.

The simplest detect.conf is composed of lines specifying 'tests' as follows:

      testdhcp    '*.*.*.*'    dhcp
      testarp     eth0,00:24:5e:17:12:11,10.2.0.4  auckland
      testping    172.16.100.2,172.16.100.86       ceo7k

where each 'test' line is composed of three parts:
<command> <parameter> <location>

### Syntax

default <location> | Set this at the top of your scripts to choose the name of the location to use when all tests fail.
set <variable> <value> | Sets an environment variable. These variables may be referred to within the scripts. Most standard scripts use $INTERFACE, for example, to identify the interface being dealt with.
if <location>[,<location>...] ... tests ... [elif <location>[,<location>...] ... tests ...] [else ... tests ...] fi | If one of the listed locations has been previously found true, then the if... branch will be processed, otherwise the else... branch will be processed. The 'elif...' branch does what you would expect too. Note that these cannot be nested, however.
at <location>[,<location>...] | We are 'at' the listed locations.
notat <location>[,<location>...] | We are 'not at' the listed locations.
always ... test ... | Runs the test regardless of whether a previous test was successful. If we are within an inactive branch of an if ... elif ... else ... fi clause the test will not be processed, even when preceded by always.
<testscript> <parameter> <location>[,<location>...] | Anything else is assumed to be a script, which will be run by the whereami process with the second parameter. If the script exits with a 0 status, whereami will consider that the location(s) listed in the third parameter are current. Note: that tests will only be run until one is successful, unless the test is preceded by always.

Read the detect.conf(5) manual page for more information.

### Standard tests

The whole command normally appears on the same line in detect.conf. The HTML formatting here may break commands onto multiple lines for readability.

testdhcp | testdhcp [<interface>,](start|stop|restart|<IP address pattern>) <location>[,<location>...] | Gets a DHCP address (on the first call, or on the 'start' call) and compares it to the IP address pattern.
testarp | testarp [<interface>,]<MAC address>,<IP address> <location>[,<location>...] | Look for that MAC address in association with that IP address on the specified interface.
testmii | testmii <interface> <location>[,<location>...] | Check if there is a network present on the interface.
testmodule | testmodule <pattern for lsmod> <location>[,<location>...] | Look for the pattern somewhere in the output of lsmod.
testpci | testpci <pattern for lspci -v> <location>[,<location>...] | Look for the pattern somewhere in the output of lspci -v
testping | testping [<interface>,]<IP to find>,<IP to use> <location>[,<location>...] | Configure the interface as the specified IP address and try and ping the other one. Note that this uses fping for speed, and makes assumptions about how long it is reasonable to wait for a ping response on a LAN.
testpppoe | testpppoe <interface> <location>[,<location>...] | Attempts to establish a pppoe session.
testreceived | testreceived <interface> <location>[,<location>...] | Check to see if we have received packets on that interface.
testssid | testssid <SSID> <location>[,<location>...] | Look for a WLAN that is using that SSID.

## Examples

In my situation I have around 7 different locations I want to identify:

- Catalyst office in Wellington
- Client 1 office in Auckland
- Client 2 office in Sydney
- Client 3 office in Auckland
- Client 1 office in Wellington (mail is less important here)
- Client 2 office in Wellington (mail is less important here)
- Out of office (Wellington, Auckland and Sydney)
- At home (on the network)
- . . . as well as other locations

In most of these situations DHCP is set up, which makes things quite a bit easier because I can assume that the network adapter is configured once whereami is run. At Catalyst I also use the lspci command to see if my computer is in its docking station.

For the home network I don't have DHCP set up yet, so I use testarp to look for a MAC address.

Since being docked doesn't entail that I'm at Catalyst, I check for the docking station first; then I check for all the DHCP addresses I might have been assigned. Fortunately these all assign addresses in different class C ranges, so I don't have to get complicated and look up IP addresses and so forth, but the tests could be refined further if required.

Someday I would like to give whereami some 'hysteresis': the last active location would influence detection such that if I was last in Auckland then whereami will reckon that, if I am now off-line, I am off-line in Auckland (so it could configure the defaults for ppp appropriately).

## Creating tests

If the standard test programs (in /usr/share/whereami/...) are insufficient for your needs, you can create your own.

Each script to be used in detect.conf must:

- accept a single parameter
- exit with 0 on success and 1 otherwise

If you want to pass multiple parameters to your program then, for now, you will need to pass them a comma (or some other non-space character) separated list. You can use the standard tests (which are shell scripts) as examples to work from.

Having found out where you are, here are the actions that whereami can be configured to take.

whereami | Actions | © Andrew McMillan, 1999-2003 released under the GPL