<!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:

whereami.conf.5: whereami.conf.sgml
	docbook-to-man $< > $@
  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Andrew</firstname>">
  <!ENTITY dhsurname   "<surname>McMillan</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>December 24, 2001</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>debian@mcmillan.net.nz</email>">
  <!ENTITY dhusername  "Andrew McMillan">
  <!ENTITY dhucpackage "<refentrytitle>whereami.conf</refentrytitle>">
  <!ENTITY dhpackage   "whereami.conf">

  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2001</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>configuration file for <command>whereami</command>
    </refpurpose>
  </refnamediv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>The <filename>whereami.conf</filename> file specifies what <command>whereami</command>
    does on leaving, remaining at or arriving at locations.

    (Locations are detected by <command>whereami</command> according
    to specifications in the <filename>detect.conf</filename> file.)</para>

    <para>Comments are lines starting with the `#' character.
    Leading whitespace is ignored on all lines, including comment lines.</para>

    <para>Other lines are of the form:</para>
    <variablelist>
      <varlistentry>
        <term><option>-</option><replaceable>location</replaceable> <replaceable>action</replaceable></term>
        <listitem>
          <para>The action is performed if your system was previously at this location,
          but is now at another location.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>=</option><replaceable>location</replaceable> <replaceable>action</replaceable></term>
        <listitem>
          <para>The action is performed if your system is now at this location.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>+</option><replaceable>location</replaceable> <replaceable>action</replaceable></term>
        <listitem>
          <para>The action is performed if your system is now at this location,
          but was previously at another location.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>!</option><replaceable>location</replaceable> <replaceable>action</replaceable></term>
        <listitem>
          <para>The action is performed if your system is not at this location.</para>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>
  <refsect1>
    <title>HELPER SCRIPTS</title>

    <para>In addition to the normal commands available within any 
    shell script, <command>whereami</command> includes a number 
    of helper scripts which may be useful.</para>

    <variablelist>
      <varlistentry>
        <term>setmailrelay <replaceable>(none | queue [smarthost] | smarthost)</replaceable></term>
        <listitem>
          <para>
            Set the mail relay (i.e. smarthost) to "none" if you have
            a permanent connection, and can send e-mail directly to
            the recipient's mailserver.
          </para>
          <para>
            If you are not connected, set the relay to "queue" (optionally
            for a specific smarthost).
          </para>
          <para>
            Or send all mail to a specific smarthost, if that is what
            you need in this location.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>setresolver <replaceable>&lt;resolv.conf stanza&gt;</replaceable></term>
        <listitem>
          <para>
          The <replaceable>&lt;resolv.conf stanza&gt;</replaceable> should
          be something like: <replaceable>search localhost mydomain.com
          nameserver 1.2.3.4</replaceable> (all on one line) to specify the
          domain search path and the nameserver to use.
          </para>
          <para>
          If you have <command>resolvconf</command> installed, this script
          will interface with that to manupulate the /etc/resolv.conf file
          and control DNS resolution.  This is recommended.
          </para>
          <para>
          If you are not using resolvconf, then this will directly rewrite
          your /etc/resolv.conf file, inserting a section similar to the
          manner in which DHCP works.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>setproxy <replaceable>(start | stop | none | &lt;upstream_proxy&gt;)</replaceable></term>
        <listitem>
          <para>
          Use this script to reconfigure your local <command>oops</command>
          or <command>squid</command> proxy server to use a specific upstream
          proxy, no upstream proxy, or to stop the proxy server completely.
          </para>
          <para>The upstream proxy should be specified as "&lt;name or ip&gt;
          &lt;port&gt;", e.g.: <command>setproxy 192.168.55.3 3128</command>
          </para>
          <para>For a local <command>squid</command> proxy you can optionally
          also provide a complete set of parameters for the "cache_peer"
          directive (without the "cache_peer" name itself).  See the squid.conf
          file for full details of this syntax.
          e.g.: <command>setproxy 192.168.55.3 parent 3128 3140 login=user:password</command>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>settimezone <replaceable>timezone</replaceable></term>
        <listitem>
          <para>Use this to set your timezone differently.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>masqmail_route <replaceable>route_name</replaceable></term>
        <listitem>
          <para>
          Use this to reconfigure <command>masqmail</command> to use a 
          different masqmail routing.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
 
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>

    <para><command>whereami</command>(8), <filename>detect.conf</filename>(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/whereami.conf</filename></term>
        <listitem>
          <para>The file we are talking about in this here manpage.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>/etc/whereami/whereiam.sh</filename></term>
        <listitem>
          <para>The script that is built based on the information in this
          configuration file and then executed by <command>whereami</command>.</para>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>
  <refsect1>
    <title>LIMITATIONS</title>

    <para>There should be a configuration program so that the user does not
    have to do any script programming.</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:
-->
