Provided by: guessnet_0.56_amd64 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)