/usr/share/doc/whereami/html/detection.html is in whereami 0.3.34-0.3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 TRANSITIONAL//EN">
<HTML>
<HEAD>
<TITLE>whereami - Location Detection</TITLE>
<!-- $Id: detection.html,v 1.4 2005/05/15 09:18:01 andrew Exp $ -->
</HEAD>
<BODY FGCOLOR="#090933" BGCOLOR="#f0ffd0">
<TABLE WIDTH=100% BORDER=0 BGCOLOR="#faea0c" CELLSPACING=0 CELLPADDING=10><TR VALIGN=BOTTOM>
<TD ALIGN=CENTER><IMG SRC=images/q1.gif WIDTH=96 HEIGHT=126></TD>
<TD VALIGN=BOTTOM BGCOLOR="#d0b030"><H1 ALIGN=RIGHT VALIGN=BOTTOM><I>whereami</I> - Location Detection</H1></TD>
</TR></TABLE>
<HR><H2>Detection</H2>
<P>/etc/whereami/detect.conf tells <I>whereami</I> how to detect the current location.
<p>The simplest detect.conf is composed of lines specifying 'tests' as follows:
<pre>
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
</pre>
<p>where each 'test' line is composed of three parts:<br>
<command> <parameter> <location>
<h3>Syntax</h3>
<table width=100% valign=top border=1>
<tr valign=top><td>default <location></td>
<td>Set this at the top of your scripts to choose the name of the location
to use when all tests fail.</td>
</tr>
<tr valign=top><td>set <variable> <value></td>
<td>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.</td>
</tr>
<tr valign=top><td>if <location>[,<location>...]<br>
... tests ...<br>
[elif <location>[,<location>...]<br>
... tests ...]<br>
[else<br>
... tests ...]<br>
fi
</td>
<td>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.
<p>Note that these cannot be nested, however.</td>
</tr>
<tr valign=top><td>at <location>[,<location>...]</td>
<td>We are 'at' the listed locations.</td>
</tr>
<tr valign=top><td>notat <location>[,<location>...]</td>
<td>We are 'not at' the listed locations.</td>
</tr>
<tr valign=top><td>always ... test ...</td>
<td>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, <b>even</b> when preceded by <i>always</i>.</td>
</tr>
<tr valign=top><td wrap=none><testscript> <parameter> <location>[,<location>...]</td>
<td>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.<br>
<b>Note:</b> that tests will only be run until one is successful, unless the
test is preceded by <i>always</i>.</td>
</tr>
</table>
<p>
Read the detect.conf(5) manual page for more information.
<h3>Standard tests</h3>
<p>The whole command normally appears on the same line in detect.conf.
The HTML formatting here may break commands onto multiple lines for readability.
<table width=100% valign=top border=1>
<tr valign=top><td>testdhcp</td><td>testdhcp [<interface>,](start|stop|restart|<IP address pattern>) <location>[,<location>...]</td>
<td>Gets a DHCP address (on the first call, or on the 'start' call) and compares it to
the IP address pattern.</td>
</tr>
<tr valign=top><td>testarp</td><td>testarp [<interface>,]<MAC address>,<IP address> <location>[,<location>...]</td>
<td>Look for that MAC address in association with that IP address on the specified interface.</td>
</tr>
<tr valign=top><td>testmii</td><td>testmii <interface> <location>[,<location>...]</td>
<td>Check if there is a network present on the interface.</td>
</tr>
<tr valign=top><td>testmodule</td><td>testmodule <pattern for <I>lsmod</I>> <location>[,<location>...]</td>
<td>Look for the pattern somewhere in the output of <I>lsmod</I>.</td>
</tr>
<tr valign=top><td>testpci</td><td>testpci <pattern for <I>lspci -v</I>> <location>[,<location>...]</td>
<td>Look for the pattern somewhere in the output of <I>lspci -v</I></td>
</tr>
<tr valign=top><td>testping</td><td>testping [<interface>,]<IP to find>,<IP to use> <location>[,<location>...]</td>
<td>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.</td>
</tr>
<tr valign=top><td>testpppoe</td><td>testpppoe <interface> <location>[,<location>...]</td>
<td>Attempts to establish a pppoe session.</td>
</tr>
<tr><td>testreceived</td><td>testreceived <interface> <location>[,<location>...]</td>
<td>Check to see if we have received packets on that interface.</td>
</tr>
<tr valign=top><td>testssid</td><td>testssid <SSID> <location>[,<location>...]</td>
<td>Look for a WLAN that is using that SSID.</td>
</tr>
</table>
<HR><H2>Examples</H2>
<P>In my situation I have around 7 different locations I want to identify:<UL>
<LI>Catalyst office in Wellington</LI>
<LI>Client 1 office in Auckland</LI>
<LI>Client 2 office in Sydney</LI>
<LI>Client 3 office in Auckland</LI>
<LI>Client 1 office in Wellington (mail is less important here)</LI>
<LI>Client 2 office in Wellington (mail is less important here)</LI>
<LI>Out of office (Wellington, Auckland and Sydney)</LI>
<LI>At home (on the network)</LI>
<LI>. . . as well as other locations</LI>
</UL>
<P>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 <I>whereami</I> is run. At Catalyst
I also use the <I>lspci</I> command to see if my computer is in its docking station.</P>
<P>For the home network I don't have DHCP set up yet, so I use testarp to look for a MAC
address.
<P>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.</P>
<P>Someday I would like to give <I>whereami</I> some 'hysteresis':
the last active location would influence detection such that if I was last in Auckland
then <I>whereami</I> will reckon that, if I am now off-line, I am off-line in Auckland
(so it could configure the defaults for ppp appropriately).</P>
<HR><H2>Creating tests</H2>
<p>If the standard test programs (in /usr/share/whereami/...) are insufficient for your needs,
you can create your own.
<p>Each script to be used in detect.conf must:
<ul>
<li>accept a single parameter</li>
<li>exit with 0 on success and 1 otherwise</li>
</ul>
<p>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.
<HR>
<P>Having found out where you are, <A HREF=actions.html>here are the actions</A>
that <I>whereami</I> can be configured to take.</P>
<P> </P><HR>
<TABLE WIDTH=100%><TR>
<TD ALIGN=LEFT><FONT FACE=sans-serif SIZE=2>
<A HREF=index.html>whereami</A>
|
<A HREF=actions.html>Actions</A>
</FONT></TD>
<TD ALIGN=RIGHT><FONT FACE=sans-serif SIZE=2>© Andrew McMillan, 1999-2003 released under the <A HREF=http://www.gnu.org/>GPL</A></FONT></TD>
</TR></TABLE>
<HR>
</BODY>
</HTML>
|