<!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 succesfull.</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 intialised 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; &lt;&dhemail;&gt; 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:
-->
