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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
|
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!-- Process this file with docbook-to-man to generate an nroff manual
page: `docbook-to-man manpage.sgml > manpage.1'. You may view
the manual page with: `docbook-to-man manpage.sgml | nroff -man |
less'. A typical entry in a Makefile or Makefile.am is:
detect.conf.5: detect.conf.sgml
docbook-to-man $< > $@
-->
<!-- $Id: detect.conf.sgml,v 1.17 2006/12/01 09:52:17 andrew Exp $ -->
<!ENTITY dhfirstname "<firstname>Andrew</firstname>">
<!ENTITY dhsurname "<surname>McMillan</surname>">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY dhdate "<date>November 4, 2002</date>">
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
allowed: see man(7), man(1). -->
<!ENTITY dhsection "<manvolnum>5</manvolnum>">
<!ENTITY dhemail "<email>awm@debian.org</email>">
<!ENTITY dhusername "Andrew McMillan">
<!ENTITY dhucpackage "<refentrytitle>detect.conf</refentrytitle>">
<!ENTITY dhpackage "detect.conf">
<!ENTITY debian "<productname>Debian GNU/Linux</productname>">
<!ENTITY gnu "<acronym>GNU</acronym>">
]>
<refentry>
<refentryinfo>
<address>
&dhemail;
</address>
<author>
&dhfirstname;
&dhsurname;
</author>
<copyright>
<year>2002</year>
<holder>&dhusername;</holder>
</copyright>
&dhdate;
</refentryinfo>
<refmeta>
&dhucpackage;
&dhsection;
</refmeta>
<refnamediv>
<refname>&dhpackage;</refname>
<refpurpose>provides the configuration for detection of locations for
<command>whereami</command>.
</refpurpose>
</refnamediv>
<refsect1>
<title>DESCRIPTION</title>
<para></para>
<refsect2>
<title>Syntax</title>
<para>The <filename>detect.conf</filename> file specifies the tests that
allow <command>whereami</command> 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.</para>
<para>Comments are lines starting with the `#' character. Leading
whitespace is ignored on all lines, including comment lines.</para>
</refsect2>
<refsect2>
<title>Internal Commands</title>
<para>The syntax of this file is fairly straightforward. Tests are specified thus:</para>
<variablelist>
<varlistentry>
<term><option>testname <replaceable>parameter</replaceable> <replaceable>locations</replaceable></option></term>
<listitem>
<para>The command <command>testname</command> is run with the single
<replaceable>parameter</replaceable> (which may be split internally).
If the return value is 0, the test is considered `successful' and the
<replaceable>locations</replaceable> are considered `discovered'.
</para>
<para><replaceable>locations</replaceable> is a list
of comma separated identifiers, each one matching the regexp
<quote>[[:alnum:]._-]+</quote>.</para>
<para>On success, processing will skip all non-`always' statements
up to the next `if' or `fi' keyword, whichever is earlier.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>if <replaceable>location</replaceable> <replaceable>statements ...</replaceable> [elif <replaceable>location</replaceable> <replaceable>statements ...</replaceable>]... [else <replaceable>statements ...</replaceable>] fi</option></term>
<listitem>
<para>If the <replaceable>location</replaceable> 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.</para>
<para>Note that nesting of `if' blocks is not supported at this time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>always testname <replaceable>parameter</replaceable> <replaceable>locations</replaceable></option></term>
<listitem>
<para>A test preceded by the word `always' is not skipped unless it is within the inactive
branch of an `if' clause.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>set <replaceable>variable</replaceable> <replaceable>value</replaceable></option></term>
<listitem>
<para>The environment <replaceable>variable</replaceable> is defined
as <replaceable>value</replaceable> for all subsequent test scripts
and in the shell script eventually constructed by <command>whereami</command>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>at <replaceable>locations</replaceable></option></term>
<listitem>
<para>The <replaceable>locations</replaceable> will be added to the "discovered" list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>notat <replaceable>locations</replaceable></option></term>
<listitem>
<para>The <replaceable>locations</replaceable> will be removed from the "discovered" list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>echo <replaceable>"quoted text string"</replaceable></option></term>
<listitem>
<para>The <replaceable>"quoted text string"</replaceable> will be displayed to the user
on stdout.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The <replaceable>parameter</replaceable> and <replaceable>locations</replaceable>
may be lists, with a comma (",") used to separate multiple values.</para>
</refsect2>
<refsect2>
<title>Tests</title>
<para>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.</para>
<para>If a parameter of the test script must contain a space, it
parameter will need to be quoted.</para>
<para>A number of tests are included in the whereami package.</para>
<variablelist>
<varlistentry>
<term>testdhcp <replaceable>[interface,]pattern</replaceable></term>
<listitem>
<para>Tests for the assignment by DHCP of an IP address matching the
specified address <replaceable>pattern</replaceable>.
If not specified, the <replaceable>interface</replaceable> defaults to `eth0'.</para>
<para>Note that the first execution of this test during a particular run
of <command>whereami</command> induces a DHCP request on the specified interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testmii <replaceable>interface</replaceable></term>
<listitem>
<para>Checks for the presence of a link on <replaceable>interface</replaceable> using
the <command>mii-tool</command> utility.
If a link is not found then the interface will be 'down'ed to limit
side-effects on other detection later.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testpppoe <replaceable>interface</replaceable></term>
<listitem>
<para>Tries to start a PPPoE connection on the specified interface. Success
is returned if the connection starts.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testarp <replaceable>interface</replaceable>,<replaceable>mac_address</replaceable>,<replaceable>ip_address</replaceable></term>
<listitem>
<para>Performs an <command>arping</command> (Debian package: iputils-arping) to look for the
specified <replaceable>mac_address</replaceable> and <replaceable>ip_address</replaceable> combination
on the network connected to <replaceable>interface</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testping [<replaceable>interface</replaceable>,]<replaceable>ip_to_ping</replaceable>,<replaceable>ip_to_use</replaceable></term>
<listitem>
<para>Uses the <command>fping</command> program to perform a fast ping to look for the
presence of a particular host on the local network.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testpci <replaceable>pattern</replaceable></term>
<listitem>
<para>Searches for the <replaceable>pattern</replaceable> in
the output of <command>lspci -v</command>.</para>
<para>This enables checking for specific hardware, such as a particular
type of docking station.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testmodule <replaceable>pattern</replaceable></term>
<listitem>
<para>Searches for the <replaceable>pattern</replaceable> in
the output of <command>lsmod</command>.</para>
<para>This is useful for checking for the presence of a particular PCMCIA
card, or possibly a particular kernel configuration.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testap [<replaceable>interface</replaceable>,]scan</term>
<term>testap <replaceable>pattern</replaceable>[,<replaceable>WEP Key</replaceable>]</term>
<term>testap [<replaceable>interface</replaceable>,]<replaceable>pattern</replaceable>,<replaceable>WEP Key</replaceable></term>
<listitem>
<para>The <replaceable>pattern</replaceable> is a regexp
(egrep regexp) used to match AP essids: when this regexp matches a
detected essid the test is considered successful.</para>
<para>This check does not require encryption to be set up to
work, although it may not find stealthier equipment - use
testssid in that case.</para>
<para>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!</para>
<para>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.</para>
<para>When using the <replaceable>WEP key</replaceable> 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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testappassive [<replaceable>interface</replaceable>,]scan</term>
<term>testappassive <replaceable>pattern</replaceable></term>
<term>testap [<replaceable>interface</replaceable>,]<replaceable>pattern</replaceable></term>
<listitem>
<para>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 <replaceable>interface</replaceable> 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 initialised before whereami starting
in run level 2.</para>
<para>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!</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testprocsys <replaceable>proc-or-sys-path</replaceable>,<replaceable>egrep-pattern</replaceable></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testssid <replaceable>ssid</replaceable>[,<replaceable>key</replaceable>]</term>
<listitem>
<para>Checks whether the wireless interface is in range of
the specified <replaceable>ssid</replaceable>, 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).</para>
<para>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).</para>
<para>This is useful for checking which wireless LAN
is in range.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>testreceived [<replaceable>interface</replaceable>]</term>
<listitem>
<para>Checks whether the <replaceable>interface</replaceable> in
question has received any bytes.</para>
<para>This is useful for checking which network interface is actually
connected to a network.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>EXAMPLES</title>
<para>The following examples show simple setups, firstly for
a wired only configuration, and secondly for a mixed wireless
and wired setup.
</para>
<example>
<title>A Simple Wired DHCP Configuration</title>
<programlisting>
# 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
</programlisting>
</example>
<example>
<title>A Wired and Wireless Configuration</title>
<programlisting>
# 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
</programlisting>
</example>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><command>whereami</command>(8), <command>whereami.conf</command>(5)</para>
<para>Further documentation is available in the /usr/share/doc/whereami directory.</para>
</refsect1>
<refsect1>
<title>FILES</title>
<variablelist>
<varlistentry>
<term><filename>/etc/whereami/detect.conf</filename></term>
<listitem>
<para>The file we are talking about in this here manpage.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/etc/whereami/whereami.conf</filename></term>
<listitem>
<para>Defines the actions performed as a result of entering, leaving,
or remaining at a particular location.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>LIMITATIONS</title>
<para>The `if' syntax does not support nesting.</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>This manual page was written by &dhusername; <&dhemail;> for
the &debian; system (but may be used by others). Permission is
granted to copy, distribute and/or modify this document under
the terms of the <acronym>GPL</acronym> version 2.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
|
