README

  1Motivation
  2==========
  3
  4One of the nice things about network namespaces is that they allow one
  5to easily create and test complex environments.
  6
  7Unfortunately, these namespaces can not be used with actual switching
  8ASICs, as their ports can not be migrated to other network namespaces
  9(dev->netns_immutable) and most of them probably do not support the
 10L1-separation provided by namespaces.
 11
 12However, a similar kind of flexibility can be achieved by using VRFs and
 13by 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
 26The VRFs act as lightweight namespaces representing hosts connected to
 27the switch.
 28
 29This approach for testing switch ASICs has several advantages over the
 30traditional method that requires multiple physical machines, to name a
 31few:
 32
 331. Only the device under test (DUT) is being tested without noise from
 34other system.
 35
 362. Ability to easily provision complex topologies. Testing bridging
 37between 4-ports LAGs or 8-way ECMP requires many physical links that are
 38not always available. With the VRF-based approach one merely needs to
 39loopback more ports.
 40
 41These tests are written with switch ASICs in mind, but they can be run
 42on any Linux box using veth pairs to emulate physical loopbacks.
 43
 44Guidelines for Writing Tests
 45============================
 46
 47o Where possible, reuse an existing topology for different tests instead
 48  of recreating the same topology.
 49o Tests that use anything but the most trivial topologies should include
 50  an ASCII art showing the topology.
 51o Where possible, IPv6 and IPv4 addresses shall conform to RFC 3849 and
 52  RFC 5737, respectively.
 53o Where possible, tests shall be written so that they can be reused by
 54  multiple topologies and added to lib.sh.
 55o Checks shall be added to lib.sh for any external dependencies.
 56o Code shall be checked using ShellCheck [1] prior to submission.
 57
 581. https://www.shellcheck.net/
 59
 60Cleanups
 61--------
 62
 63o lib.sh brings in defer.sh (by way of ../lib.sh) by default. Consider
 64  making use of the defer primitive to schedule automatic cleanups. This
 65  makes it harder to forget to remove a temporary netdevice, kill a running
 66  process or perform other cleanup when the test script is interrupted.
 67
 68o When adding a helper that dirties the environment, but schedules all
 69  necessary cleanups through defer, consider prefixing it adf_ for
 70  consistency with lib.sh and ../lib.sh helpers. This serves as an
 71  immediately visible bit of documentation about the helper API.
 72
 73o Definitely do the above for any new code in lib.sh, if practical.
 74
 75Customization
 76=============
 77
 78The forwarding selftests framework uses a number of variables that
 79influence its behavior and tools it invokes, and how it invokes them, in
 80various ways. A number of these variables can be overridden. The way these
 81overridable variables are specified is typically one of the following two
 82syntaxes:
 83
 84	: "${VARIABLE:=default_value}"
 85	VARIABLE=${VARIABLE:=default_value}
 86
 87Any of these variables can be overridden. Notably net/forwarding/lib.sh and
 88net/lib.sh contain a number of overridable variables.
 89
 90One way of overriding these variables is through the environment:
 91
 92	PAUSE_ON_FAIL=yes ./some_test.sh
 93
 94The variable NETIFS is special. Since it is an array variable, there is no
 95way to pass it through the environment. Its value can instead be given as
 96consecutive arguments to the selftest:
 97
 98	./some_test.sh swp{1..8}
 99
100A way to customize variables in a persistent fashion is to create a file
101named forwarding.config in this directory. lib.sh sources the file if
102present, so it can contain any shell code. Typically it will contain
103assignments of variables whose value should be overridden.
104
105forwarding.config.sample is available in the directory as an example of
106how forwarding.config might look.