tools/testing/selftests/net/forwarding/README

   1 Motivation
   2 ==========
   3
   4 One of the nice things about network namespaces is that they allow one
   5 to easily create and test complex environments.
   6
   7 Unfortunately, these namespaces can not be used with actual switching
   8 ASICs, as their ports can not be migrated to other network namespaces
   9 (dev->netns_local) and most of them probably do not support the
  10 L1-separation provided by namespaces.
  11
  12 However, a similar kind of flexibility can be achieved by using VRFs and
  13 by looping the switch ports together. For example:
  14
  15                              br0
  16                               +
  17                vrf-h1         |           vrf-h2
  18                  +        +---+----+        +
  19                  |        |        |        |
  20     192.0.2.1/24 +        +        +        + 192.0.2.2/24
  21                swp1     swp2     swp3     swp4
  22                  +        +        +        +
  23                  |        |        |        |
  24                  +--------+        +--------+
  25
  26 The VRFs act as lightweight namespaces representing hosts connected to
  27 the switch.
  28
  29 This approach for testing switch ASICs has several advantages over the
  30 traditional method that requires multiple physical machines, to name a
  31 few:
  32
  33 1. Only the device under test (DUT) is being tested without noise from
  34 other system.
  35
  36 2. Ability to easily provision complex topologies. Testing bridging
  37 between 4-ports LAGs or 8-way ECMP requires many physical links that are
  38 not always available. With the VRF-based approach one merely needs to
  39 loopback more ports.
  40
  41 These tests are written with switch ASICs in mind, but they can be run
  42 on any Linux box using veth pairs to emulate physical loopbacks.
  43
  44 Guidelines for Writing Tests
  45 ============================
  46
  47 o Where possible, reuse an existing topology for different tests instead
  48   of recreating the same topology.
  49 o Tests that use anything but the most trivial topologies should include
  50   an ASCII art showing the topology.
  51 o Where possible, IPv6 and IPv4 addresses shall conform to RFC 3849 and
  52   RFC 5737, respectively.
  53 o Where possible, tests shall be written so that they can be reused by
  54   multiple topologies and added to lib.sh.
  55 o Checks shall be added to lib.sh for any external dependencies.
  56 o Code shall be checked using ShellCheck [1] prior to submission.
  57
  58 1. https://www.shellcheck.net/
  59
  60 Customization
  61 =============
  62
  63 The forwarding selftests framework uses a number of variables that
  64 influence its behavior and tools it invokes, and how it invokes them, in
  65 various ways. A number of these variables can be overridden. The way these
  66 overridable variables are specified is typically one of the following two
  67 syntaxes:
  68
  69         : "${VARIABLE:=default_value}"
  70         VARIABLE=${VARIABLE:=default_value}
  71
  72 Any of these variables can be overridden. Notably net/forwarding/lib.sh and
  73 net/lib.sh contain a number of overridable variables.
  74
  75 One way of overriding these variables is through the environment:
  76
  77         PAUSE_ON_FAIL=yes ./some_test.sh
  78
  79 The variable NETIFS is special. Since it is an array variable, there is no
  80 way to pass it through the environment. Its value can instead be given as
  81 consecutive arguments to the selftest:
  82
  83         ./some_test.sh swp{1..8}
  84
  85 A way to customize variables in a persistent fashion is to create a file
  86 named forwarding.config in this directory. lib.sh sources the file if
  87 present, so it can contain any shell code. Typically it will contain
  88 assignments of variables whose value should be overridden.
  89
  90 forwarding.config.sample is available in the directory as an example of
  91 how forwarding.config might look.