Provided by: guessnet_0.56_i386 bug

NAME

       guessnet - guess which LAN a network interface is connected to

SYNOPSIS

       guessnet [options] [network_interface]

DESCRIPTION

       Guessnet  guesses which LAN a network interface is connected to.  Given
       a list of candidate profiles each of which includes a test description,
       guessnet  runs  all  the  tests  in parallel and prints the name of the
       profile whose test was the first one to succeed.  If no  test  succeeds
       within a certain timeout period then a default profile name is printed.
       After printing a profile name, guessnet  immediately  kills  any  tests
       that are still running and exits.

       Candidate  profiles are read either from a test description file or, in
       ifupdown mode, from /etc/network/interfaces.

OPTIONS

       Options follow the usual GNU conventions.  In  ifupdown  mode,  options
       can   also   be   specified   on   the   standard  input  in  the  form
       "<long-option-name>: <value>".

       -C, --config-file=filename
              Name of the configuration  file  to  use  if  not  specified  on
              command      line.       Default:      standard     input     or
              /etc/network/interfaces in ifupdown mode.

       --autofilter
              Only  useful  when  operating  in  ifupdown  mode  (see  below).
              Instructs guessnet to only consider logical interface names that
              start with physical interface name being mapped. (ie:  eth0-home
              only matches when mapping eth0) Default: false.

       --debug
              Print debugging messages.

       -d, --default=string
              Interface  name  to  print  if  no  known  networks  are  found.
              Default: none.

       --help Show a brief summary of command line options.

       -i, --ifupdown-mode
              Operate in ifupdown mode: parse the input as if  it  is  in  the
              format     of     /etc/network/interfaces    and    read    from
              /etc/network/interfaces instead of the  standard  input  if  the
              configuration  filename is not specified.  See the ifupdown mode
              section below for details.

       --init-time=int
              Time in seconds to wait for the interface to initialize when  it
              is not found already up at program startup.  Default: 3 seconds.

       --init-delay=int
              Sleep  a given number of seconds before starting operations. May
              be useful in case interface driver needs a little time to settle
              before reacting to commands.  Default: 0 seconds.

       --iwscan-tries=int
              Retry  wireless  network scanning a given amount. Useful if your
              driver needs some attempts to return a network  list.   Default:
              1.

       --syslog
              Send messages to syslog facility DAEMON, in addition to stderr.

       -t, --timeout=int
              Timeout  in  seconds  used  to  wait  for  tests  to  terminate.
              Default: 5 seconds.

       -v, --verbose
              Operate verbosely.

       --version
              Show the version number of the program.

TEST DESCRIPTION FILE

       guessnet takes as input a description of the tests it  should  perform.
       The test description file looks like this:

         # Empty lines and lines starting with '#' are ignored.
         # Other lines contain:
         #   <profile-name> <test-method> <parameters>

         # At home, look for a host with the given IP and MAC address
         home peer 192.168.1.1 00:01:02:03:04:05

         # At the university, check for the presence of at least one
         # of the following hosts
         university peer 130.136.1.1 05:06:03:02:01:0A
         university peer 130.136.1.2 15:13:B3:A2:2F:CD

         # If the peer doesn't reply to ARP packets coming from 0.0.0.0
         # then you can additionally specify a source address to use
         university peer 130.136.1.2 15:13:B3:A2:2F:CD 130.136.1.250

         # For the work network use a custom script
         work command /usr/local/bin/check_work

         # Commands are executed by "sh -c" so shell syntax can be used
         john-irda command grep -q `cat ~enrico/john-irda-id` /proc/net/irda/discovery

         # Location name and interface name are exported in NAME and IFACE
         weirdnet command /usr/local/bin/weirddetect "$NAME" "$IFACE"

         # Profile "none" is selected if no network signal is detected
         # (i.e. there is no cable plugged into the socket)
         no-net missing-cable

         # Match a wireless network with the given essid
         home wireless essid Home
         # You can also match the mac address of the access point
         home wireless mac 01:02:03:04:0A:0B
         # Or both
         home wireless essid Home mac 01:02:03:04:0A:0B
         # You can also match any open network
         anyopen wireless open

       Every non-comment line represents a test to perform.

       The first word in the line is the name that will be printed if the test
       succeeds.

       The second word is the test type.

       The remainder of the line contains parameters for  the  selected  test;
       these vary depending on the test type.

IFUPDOWN MODE

       ifupdown,  Debian's  standard network configuration system, permits one
       to  define  different  "logical  interfaces"   (ifupdown's   name   for
       configuration  profiles) and to choose among them when one configures a
       network  interface.   The  choice  can  be  delegated  to  an  external
       "mapping" program.  guessnet can be used as such a program if it is run
       in "ifupdown mode".  guessnet runs in ifupdown mode if it is invoked as
       guessnet-ifupdown or if it is given the --ifupdown-mode option.

       In  ifupdown  mode  guessnet  reads test data directly from the logical
       interface definitions in /etc/network/interfaces  rather  than  from  a
       separate test description file.

       In  ifupdown mode if names are passed to guessnet on its standard input
       then guessnet  considers  only  those  logical  interface  definitions;
       otherwise  it considers them all. You can have ifupdown deliver data to
       guessnet's standard input using the map  directive.  See  interfaces(5)
       for  more  information.  If  names are preceded with "!" character then
       match  is  inverted,  meaning  that  all  logical  interfaces  will  be
       processed  except  for the ones specified in standard input. You cannot
       mix normal and negated interface names in the same  mapping  directive.
       Note:  when  using  autofilter  option  (see  above) you can broaden or
       tighten  the  automatic  matching  by  specifying  interface  names  as
       descripted.

       Please  note  that  you  have  to  specify  the fully qualified path to
       guessnet (/usr/sbin/guessnet-ifupdown), as otherwise it won't be run at
       system  boot, as /usr/sbin is not on PATH of networking init script any
       more. Also, you need to ensure /usr is actually mounted at that moment.

       In ifupdown mode options are selected by  passing  "<long-option-name>:
       <value>"  on  guessnet's  standard  input.   This  feature  is provided
       because ifupdown cannot pass command line arguments to mapping scripts.

       If   you   prefer   you   can   precede    the    test    keyword    in
       /etc/network/interfaces with the word guessnet.

       ifupdown  does not allow two option lines in /etc/network/interfaces to
       start with the same word.  To work  around  this  limitation,  multiple
       test  (or guessnet) lines can have different numerals suffixed to their
       initial keywords (test1, test2, or guessnet1, guessnet2, and so on).

       Here's an example of an /etc/network/interfaces file that has been  set
       up for guessnet:

       auto lo eth0

       iface lo inet loopback

       mapping eth0
            script /usr/sbin/guessnet-ifupdown
            # Scan all logical interfaces
            # More options can be given here, such as:
            # map timeout: 10
            # map verbose: true
            # map debug: true
            # map iwscan-tries: 23
            map default: none

       mapping eth1
            script /usr/sbin/guessnet-ifupdown
            # Disable open net checking, just comment out if you are
            # desperate enough :) (see relative stanza below)
            map !eth1-anyopen
            # Scan only logical interfaces named eth1-*
            map autofilter: true

       iface home inet static
            address 192.168.1.2
            netmask 255.255.255.0
            broadcast 192.168.1.255
            gateway 192.168.1.1

            # Lines for resolvconf (if you use it: see apt-cache show resolvconf)
            # dns-search casa
            # dns-nameservers 192.168.1.1 192.168.2.1

            # Two tests, in case one of the two machines is down when we test
            test1 peer address 192.168.1.1 mac 00:01:02:03:04:05
            test2 peer address 192.168.1.3 mac 00:01:02:03:04:06

       iface work inet static
            address 10.1.1.42
            netmask 255.255.255.0
            broadcast 10.1.1.255
            gateway 10.1.1.1
            test command /usr/local/bin/check_work

       iface work2 inet static
            address 192.168.2.23
            netmask 255.255.255.0
            broadcast 192.168.2.255
            gateway 192.168.2.1
            # A source address has to be specified in case the peer
            # doesn't reply to ARP packets coming from 0.0.0.0
            test peer address 192.168.2.1 mac 00:01:02:03:04:05 source 192.168.2.23

       iface eth1-home inet static
            wireless-essid Home
            wireless-key s:myverysecret
            address 192.168.1.5
            netmask 255.255.255.0
            gateway 192.168.1.1
            dns-nameservers 192.168.1.1
            # Match a wireless network with the given essid
            test wireless essid Home
            # You can also match the mac address of the access point
            #test wireless mac 01:02:03:04:0A:0B
            # Or both
            #test wireless essid Home mac 01:02:03:04:0A:0B

       iface eth1-work inet dhcp
            wireless-essid Work
            wireless-key s:myverysecretkey
            # Match a wireless network with the given essid
            # If you have spaces in the essid, use double quotes
            test wireless essid "Work place"

       iface eth1-anyopen inet dhcp
            # You can also match any open network, if you are desperate :)
            wireless-essid any
            wireless-mode auto
            test wireless open

       # If nothing else is found, try DHCP
       iface none inet dhcp

Supported tests

   peer
       Test description file syntax:
              profile peer IP-address [MAC-address] [IP-address]

       Ifupdown mode syntax:
              test   peer   address   IP-address   [mac  MAC-address]  [source
              IP-address]

       Description:
              Look for peer using ARP.  The test will  succeed  if  a  network
              interface  with  the  specified  IP  address (and MAC address if
              specified) is connected to the local network.

              One can omit the MAC address, in which case guessnet only  tests
              for the presence of a host with the specified IP address.

              If the peer whose presence you want to test for refuses to reply
              to ARP packets coming from 0.0.0.0 then specify some  source  IP
              address from which the peer will accept requests.

              Multiple  peers  can  be  specified (on multiple lines) but each
              peer must have a different IP address.  This restriction may  be
              eliminated in the future.

              You  can  also omit the IP address and only use the MAC: that is
              useful to test for the existance  of  physical  interfaces  with
              changing  IP  addresses.   This  kind  of scan uses an ICMP ping
              packet requires a source address in most cases,  as  hosts  tend
              not to reply to pings coming from nowhere.

   wireless
       Test description file syntax:
              profile wireless [essid essid] [mac MAC-address] [open|closed]

       Ifupdown mode syntax:
              test wireless [essid essid] [mac MAC-address] [open|closed]

       Description:
              Perform  a  wireless  scan  like iwlist scan does, and match the
              results.

              The test succeeds if the scan reports at least one  network  for
              which  all the tests (essid, mac of the access point, network is
              open or closed) match.

              In case more than one profile matches a network, only the  first
              one,  as  found  in  the configuration file, will succeed.  This
              allows prioritising profiles: for example, you can  prefer  your
              home  access point to an open network by listing it first in the
              configuration file.

   missing-cable
       Test description file syntax:
              profile missing-cable

       Ifupdown mode syntax:
              test missing-cable

       Description:
              Check for link beat.  The test is successful if link beat is not
              detected.

              This  feature  allows guessnet to detect the case where there is
              no cable plugged into a network socket; in this case it makes no
              sense to go through other detection phases.

              This  test  can  be used in ifupdown mode too if a dummy logical
              interface  is  defined  that  includes  the  test  missing-cable
              option.  Bear in mind that when the cable is unplugged, ifupdown
              will consider the interface  to  be  configured  as  this  dummy
              logical interface.  That is somewhat counterintuitive; one might
              prefer  the  interface  to  be  deconfigured   in   that   case.
              Unfortunately,  guessnet  is  not currently able to tell ifup to
              refrain from configuring  an  interface.   The  problem  can  be
              solved, however, by means of the ifplugd(8) program.

              Link  beat  detection  is not supported on all network hardware.
              If the interface or  its  driver  does  not  support  link  beat
              detection then this test does not succeed.

   command
       Test description file syntax:
              profile command command

       Ifupdown mode syntax:
              test command command

       Description:
              Test  using  an  arbitrary  command.   The  test  is  considered
              successful if the command terminates with exit status 0.

              Location name and interface name are exported to the script  via
              the NAME and IFACE environment variables.

              For  backward  compatibility,  script  can  be  used  instead of
              command.

Experimental tests

   pppoe
       Test description file syntax:
              profile pppoe

       Ifupdown mode syntax:
              test pppoe

       Description:
              Use the pppoe program to send PADI packets in order to look  for
              access  concentrators.  The test should succeed if a PPPOE modem
              is present on the given interface.

              Using this test requires that pppoe be installed on the system.

   wireless
       Test description file syntax:
              profile wireless [mac MAC-address] [essid ESSID]

       Ifupdown mode syntax:
              test wireless [mac MAC-address] [essid ESSID]

       Description:
              Test  certain  properties  of  the  wireless  interface.    More
              specifically,  test  the  MAC  address  and/or  the ESSID of the
              associated access point.  If both  are  given  then  MAC-address
              must precede ESSID.

              Blanks may be included in the ESSID.  For example,
                  prof1 wireless essid My LAN
              tests for an ESSID of "My LAN".

              Note  that  the  wireless  test does not attempt to change these
              properties; it only examines them.  This  test  is  designed  to
              work  with  programs  such  as  waproamd which independently and
              dynamically manage the  wireless  network  adapter  to  keep  it
              associated to an access point.

              Note that the wireless test is not yet implemented cleanly.

       Note  that  if  one  of  several tests terminates successfully then any
       other tests still running will be  terminated  with  the  KILL  signal.
       Therefore,  test  programs should not need to do any special cleanup on
       exit.

NOTES

   Getting remote host MAC addresses
       When you prepare the test data for guessnet you may need  to  know  the
       MAC  address  of  a  remote  interface in the local network.  There are
       various ways to obtain this.  The easiest is to use the arping  utility
       by  doing  "arping  [hostname]".  If you don't have arping installed on
       your system then try the command "arp -a [hostname]" which will display
       the  MAC  address if it is in the ARP cache of your machine.  You might
       want to ping the remote interface first to make sure that you have  the
       information   in   the  cache.   You  can  also  take  a  look  at  the
       /usr/share/doc/guessnet/examples/getmac script.

   Multiple tests
       Currently guessnet only  supports  specifying  one  kind  of  test  per
       profile.

SEE ALSO

       ifup(8), interfaces(5), arping(8), sh(1), pppoe(8), ifplugd(8).

AUTHOR

       Guessnet   was   written   by   Enrico  Zini  <enrico@debian.org>  with
       contributions from Thomas Hood.  The ARP  network  detection  code  was
       taken from laptop-netconf by Matt Kern <matt@debian.org>, which in turn
       in based on divine by Felix von Leitner <felix@fefe.de>.

       The Guessnet webpage is at http://guessnet.alioth.debian.org .

                                4 November 2007                    GUESSNET(8)