Provided by: guessnet_0.38-1_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.

       --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.

       -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

       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.

       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 guessnet-ifupdown
            # Scan all logical interfaces
            # More options can be given here, such as:
            # map timeout: 10
            # map verbose: true
            # map debug: true
            map default: none

       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

       # 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.

   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),
       waproamd(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 October 2004                     GUESSNET(8)