
                                 whereami
                                README File

                    Andrew McMillan <Andrew@cat-it.co.nz>

This is the Debian GNU/Linux prepackaged version of the whereami package.



1.	What is "whereami"

"whereami" is a utility for laptop users or people who use their machines
in different networks all the time.

The general strategy is as follows:
  - write small scripts that test which location you are in.
  - whereami is run at boot time, when a PCMCIA card is inserted or
    removed, or at suspend/resume.
  - whereami builds a script of actions based on:
       o where you are now
       o where you were last
  - whereami executes that script.

Along with 'whereami' are a number of useful programs and scripts to help
with automating the sorts of things that many of us want to do when we
arrive (or leave) each location.

As ever, I wrote whereami for my own reasons.  It meets my needs, and I'm
only too happy to include changes to make it fit with a wider audience.



2.	What do I need?

Before using whereami, you will need to configure several items:
   - scripts in the /etc/whereami/tests directory (see 'testing' below)
   - the whereami configuration file in /etc/whereami/whereami.conf
   - to run whereami after waking up, edit /etc/whereami/apm.conf

It is recommended that you have a basic understanding of shell scripting
before you start.  In general the shell scripting used in whereami is
cleanly compartmented and full examples are provided, so a novice should
be able to work through things without too much trouble!

A number of useful scripts are also provided in the /etc/whereami/scripts
directory to assist with tasks that are regularly a part of configuration
when your computer is set up in a different environment.


3.	The configuration file

"whereami" uses a configuration file which is normally in /etc/whereami/whereami.conf.

The format of this file is that the line up to the first space is a location name
preceded by a '-', '=' or '+'.  Lines beginning with a '-' will be processed if that
location was your previous location and you are now in a new location.  Lines
beginning with an '=' will be processed each time 'whereami' is run and that is
your location.  Lines beginning with a '+' (probably the most useful) will be processed
when the location has changed and this is the new location.

The second field is a command, with the remainder of the line being parameters for it
If the command is not recognised internally by 'whereami' then it is assumed to be 
external and 'whereami' will simply run it in a shell.

Supplied script commands are:
  bind-forwarders   - sets a forwarder in your /etc/named.conf and reloads bind
  netscape-option   - changes a (Netscape) preference in the specified file.
  kill-netscape     - tries to (gently first) stop any netscape which is running
  setmailrelay      - sets an appropriate mail relay for sendmail/postfix
  setresolver       - sets your DNS configuration in /etc/resolv.conf

(your command here!)


4.	How does it work

whereami (normally in /usr/sbin/whereami) is a shell script which operates in two parts.
	1) Find out where you are on a network
	2) Execute commands appropriate to your new location

The Main Things:

4.1)	Tests

All tests which are successful should "echo $LOCATION >>iwillbe".
All tests which mean that more testing is futile should set "LOCATED=1".


4.2)	The whereami.conf Configuration File

All lines to appear in the location script should start with a '+', '-' or '=',
followed by a location name (or the word 'any')i, followed by a space.  The remainder
of the line is the script commands which will be executed as appropriate.

+any will be executed at all times
-any will be executed at all times
=any will be executed at all times

+site1 will be executed when you first connect at 'site1' and were elsewhere
-site1 will be executed when you are elsewhere and you were at site1 last
=site1 will be executed whenever you are at site1 and you connect

In general, the [+=-]any line is useful for something you want to happen every
time you connect toa  network.

The '+' lines are useful for setting things like network resolvers, bind configs,
mail or internet connectivity settings and so forth.

The '-' lines are useful for un-setting things that are only set for a single
(or a very few) locations.

The '=' lines are most useful for setting things like mounting drives, and for
making regular copies of things onto backup locations.

That's an oversimplification, of course, and I'm sure that you will all think
of things that you can do with it that will go further than this.

