tools/test/netfibs/README

   1 # $FreeBSD$
   2
   3 This directory holds scripts and a support program for multiple test cases
   4 exercising multi-IP FIBs.  At this time only IPv6 test cases are provided.
   5
   6 Makefile
   7 reflect.c
   8
   9         Makefile just builds reflect, a program to echo data on a TCP or UDP
  10         socket in very simplistic ways.  It has a couple of options to provide
  11         an address or port, a FIB to bind to or a FIB to add to a reflected
  12         message as well as some "magic" keyword handling to let the intiators
  13         control it.
  14
  15 initiator.sh and reflector.sh
  16
  17         intiator.sh runs two local test cases, one which shows a documented
  18         limitation.
  19
  20         All further tests are either exercising the sending or receiving of
  21         ICMP6, TCP or UDP packets with multiple FIBs.  initiator.sh and
  22         reflector.sh must run on two different nodes both having a network
  23         interface in the same broadcast domain (be it cross-over or on a
  24         bridge/switch).  The tests will use the IPv6 benchmarking working
  25         group (BMWG) prefix.  The prefix is hard coded into some tests.
  26         Control messages will synchronize reflector with initiator.  The
  27         reflector needs the reflect binary.  Apart from that the scripts
  28         depend on ping6, netcat, awk, tr and ipfw.  The interface to use can
  29         be set from the environment.  The commands can be run like:
  30
  31         env IFACE=ifname sh intiator.sh
  32         env IFACE=ifname sh reflector.sh
  33
  34         Both scripts also support a DEBUG environment variable for additional
  35         output.  A special value of 42 will enable sh(1) xtrace printing.
  36
  37         The output format is modeled after Test::Harness Perl as used in
  38         tools/regression/ but not always compliant following the test case name.
  39
  40         NOTE: at the time of writing reflector.sh can trigger kernel races
  41         unrelated to multi-FIB test leading to a panic(9).  "delay" calls
  42         are used to mitigate the problem some but are not always good enough.
  43         It is suggested to run one test case at a time manually disabling
  44         the others in both scripts.
  45
  46 forwarding.sh
  47
  48         forwarding.sh tests FIBs in the forwarding path, making sure that
  49         packets tagged on input are leaving on the correct FIB.
  50         The script must be run on three nodes with both edge nodes (left
  51         and right) being connected to the middle node on separate interfaces.
  52
  53         The script operates on the same principles and requirements as the
  54         two afore described ones.  Environment options equally apply, with
  55         the middle node also taking an IFACEFAR variable to name the interface
  56         to the right.   See the ASCII art at the beginning of the script for
  57         details. The script needs to be told which node it is running with
  58         the first argument:
  59
  60         env IFACE=ifname sh forwarding.sh left
  61         env IFACE=leftifname IFACEFAR=rightifname sh forwarding.sh middle
  62         env IFACE=ifname sh forwarding.sh right
  63
  64 # end