| 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_immutable) 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 | Cleanups |
| 61 | -------- |
| 62 | |
| 63 | o 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 | |
| 68 | o 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 | |
| 73 | o Definitely do the above for any new code in lib.sh, if practical. |
| 74 | |
| 75 | Customization |
| 76 | ============= |
| 77 | |
| 78 | The forwarding selftests framework uses a number of variables that |
| 79 | influence its behavior and tools it invokes, and how it invokes them, in |
| 80 | various ways. A number of these variables can be overridden. The way these |
| 81 | overridable variables are specified is typically one of the following two |
| 82 | syntaxes: |
| 83 | |
| 84 | : "${VARIABLE:=default_value}" |
| 85 | VARIABLE=${VARIABLE:=default_value} |
| 86 | |
| 87 | Any of these variables can be overridden. Notably net/forwarding/lib.sh and |
| 88 | net/lib.sh contain a number of overridable variables. |
| 89 | |
| 90 | One way of overriding these variables is through the environment: |
| 91 | |
| 92 | PAUSE_ON_FAIL=yes ./some_test.sh |
| 93 | |
| 94 | The variable NETIFS is special. Since it is an array variable, there is no |
| 95 | way to pass it through the environment. Its value can instead be given as |
| 96 | consecutive arguments to the selftest: |
| 97 | |
| 98 | ./some_test.sh swp{1..8} |
| 99 | |
| 100 | A way to customize variables in a persistent fashion is to create a file |
| 101 | named forwarding.config in this directory. lib.sh sources the file if |
| 102 | present, so it can contain any shell code. Typically it will contain |
| 103 | assignments of variables whose value should be overridden. |
| 104 | |
| 105 | forwarding.config.sample is available in the directory as an example of |
| 106 | how forwarding.config might look. |