Adding upstream version 10.0.upstream/10.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 74 insertions, 24 deletions

diff --git a/doc/developer/topotests.rst b/doc/developer/topotests.rst
index b8f213b..9b9058b 100644
--- a/doc/developer/topotests.rst
+++ b/doc/developer/topotests.rst
@@ -8,14 +8,15 @@ Topotests is a suite of topology tests for FRR built on top of micronet.
 Installation and Setup
 ----------------------
 
-Topotests run under python3. Additionally, for ExaBGP (which is used
-in some of the BGP tests) an older python2 version (and the python2
-version of ``pip``) must be installed.
+Topotests run under python3.
 
-Tested with Ubuntu 20.04,Ubuntu 18.04, and Debian 11.
+Tested with Ubuntu 22.04,Ubuntu 20.04, and Debian 12.
 
-Instructions are the same for all setups (i.e. ExaBGP is only used for
-BGP tests).
+Python protobuf version < 4 is required b/c python protobuf >= 4 requires a
+protoc >= 3.19, and older package versions are shipped by in the above distros.
+
+Instructions are the same for all setups. However, ExaBGP is only used for
+BGP tests.
 
 Tshark is only required if you enable any packet captures on test runs.
 
@@ -35,15 +36,23 @@ Installing Topotest Requirements
        tshark \
        valgrind
    python3 -m pip install wheel
-   python3 -m pip install 'pytest>=6.2.4'
-   python3 -m pip install 'pytest-xdist>=2.3.0'
+   python3 -m pip install 'pytest>=6.2.4' 'pytest-xdist>=2.3.0'
    python3 -m pip install 'scapy>=2.4.5'
    python3 -m pip install xmltodict
-   # Use python2 pip to install older ExaBGP
-   python2 -m pip install 'exabgp<4.0.0'
+   python3 -m pip install git+https://github.com/Exa-Networks/exabgp@0659057837cd6c6351579e9f0fa47e9fb7de7311
    useradd -d /var/run/exabgp/ -s /bin/false exabgp
 
-   # To enable the gRPC topotest install:
+The version of protobuf package that is installed on your system will determine
+which versions of the python protobuf packages you need to install.
+
+.. code:: shell
+   # - Either - For protobuf version <= 3.12
+   python3 -m pip install 'protobuf<4'
+
+   # - OR- for protobuf version >= 3.21
+   python3 -m pip install 'protobuf>=4'
+
+   # To enable the gRPC topotest also install:
    python3 -m pip install grpcio grpcio-tools
 
 
@@ -116,9 +125,9 @@ If you prefer to manually build FRR, then use the following suggested config:
 
    ./configure \
        --prefix=/usr \
-       --localstatedir=/var/run/frr \
+       --sysconfdir=/etc \
+       --localstatedir=/var \
        --sbindir=/usr/lib/frr \
-       --sysconfdir=/etc/frr \
        --enable-vtysh \
        --enable-pimd \
        --enable-pim6d \
@@ -230,8 +239,8 @@ the number of the test we are interested in along with ``--errmsg`` option.
     ~/frr/tests/topotests# ./analyze.py -Ar run-save -T0 --errmsg
     bgp_multiview_topo1/test_bgp_multiview_topo1.py::test_bgp_converge: AssertionError: BGP did not converge:
 
-      IPv4 Unicast Summary (VIEW 1):
-      BGP router identifier 172.30.1.1, local AS number 100 vrf-id -1
+      IPv4 Unicast Summary:
+      BGP router identifier 172.30.1.1, local AS number 100 VIEW 1 vrf-id -1
       BGP table version 1
       RIB entries 1, using 184 bytes of memory
       Peers 3, using 2169 KiB of memory
@@ -266,8 +275,8 @@ select the first failed test case.
     >           assert False, "BGP did not converge:\n%s" % bgpStatus
     E           AssertionError: BGP did not converge:
     E
-    E             IPv4 Unicast Summary (VIEW 1):
-    E             BGP router identifier 172.30.1.1, local AS number 100 vrf-id -1
+    E             IPv4 Unicast Summary:
+    E             BGP router identifier 172.30.1.1, local AS number 100 VIEW 1 vrf-id -1
                   [...]
     E             Neighbor        V         AS   MsgRcvd   MsgSent   TblVer  InQ OutQ  Up/Down State/PfxRcd   PfxSnt Desc
     E             172.16.1.1      4      65001         0         0        0    0    0    never      Connect        0 N/A
@@ -386,8 +395,9 @@ for ``master`` branch:
    ./bootstrap.sh
    ./configure \
        --enable-address-sanitizer \
-       --prefix=/usr/lib/frr --sysconfdir=/etc/frr \
-       --localstatedir=/var/run/frr \
+       --prefix=/usr/lib/frr \
+       --sysconfdir=/etc \
+       --localstatedir=/var \
        --sbindir=/usr/lib/frr --bindir=/usr/lib/frr \
        --with-moduledir=/usr/lib/frr/modules \
        --enable-multipath=0 --enable-rtadv \
@@ -559,6 +569,8 @@ Here's an example of launching ``vtysh`` on routers ``rt1`` and ``rt2``.
 
    sudo -E pytest --vtysh=rt1,rt2 all-protocol-startup
 
+.. _debug_with_gdb:
+
 Debugging with GDB
 """"""""""""""""""
 
@@ -583,6 +595,12 @@ Here's an example of launching ``zebra`` and ``bgpd`` inside ``gdb`` on router
           --gdb-breakpoints=nb_config_diff \
           all-protocol-startup
 
+Finally, for Emacs users, you can specify ``--gdb-use-emacs``. When specified
+the first router and daemon to be launched in gdb will be launched and run with
+Emacs gdb functionality by using `emacsclient --eval` commands. This provides an
+IDE debugging experience for Emacs users. This functionality works best when
+using password-less sudo.
+
 Reporting Memleaks with FRR Memory Statistics
 """""""""""""""""""""""""""""""""""""""""""""
 
@@ -631,16 +649,26 @@ Detecting Memleaks with Valgrind
 """"""""""""""""""""""""""""""""
 
 Topotest can automatically launch all daemons with ``valgrind`` to check for
-memleaks. This is enabled by specifying 1 or 2 CLI arguments.
-``--valgrind-memleaks`` will enable general memleak detection, and
-``--valgrind-extra`` enables extra functionality including generating a
-suppression file. The suppression file ``tools/valgrind.supp`` is used when
-memleak detection is enabled.
+memleaks. This is enabled by specifying 1 to 3 CLI arguments.
+``--valgrind-memleaks`` enables memleak detection. ``--valgrind-extra`` enables
+extra functionality including generating a suppression file. The suppression
+file ``tools/valgrind.supp`` is used when memleak detection is enabled. Finally,
+``--valgrind-leak-kinds=KINDS`` can be used to modify what types of links are
+reported. This corresponds to valgrind's ``--show-link-kinds`` arg. The value is
+either ``all`` or a comma-separated list of types:
+``definite,indirect,possible,reachable``. The default is ``definite,possible``.
 
 .. code:: shell
 
    sudo -E pytest --valgrind-memleaks all-protocol-startup
 
+.. note:: GDB can be used in conjection with valgrind.
+
+   When you enable ``--valgrind-memleaks`` and you also launch various daemons
+   under GDB (debug_with_gdb_) topotest will connect the two utilities using
+   ``--vgdb-error=0`` and attaching to a ``vgdb`` process. This is very
+   useful for debugging bugs with use of uninitialized errors, et al.
+
 Collecting Performance Data using perf(1)
 """""""""""""""""""""""""""""""""""""""""
 
@@ -662,6 +690,28 @@ during the config_timing test.
 To specify different arguments for ``perf record``, one can use the
 ``--perf-options`` this will replace the ``-g`` used by default.
 
+Running Daemons under RR Debug (``rr record``)
+""""""""""""""""""""""""""""""""""""""""""""""
+
+Topotest can automatically launch any daemon under ``rr(1)`` to collect
+execution state. The daemon is run in the foreground with ``rr record``.
+
+The execution state will be saved in the router specific directory
+(in a `rr` subdir that rr creates) under the test's run directoy.
+
+Here's an example of collecting ``rr`` execution state from ``mgmtd`` on router
+``r1`` during the ``config_timing`` test.
+
+.. code:: console
+
+   $ sudo -E pytest --rr-routers=r1 --rr-daemons=mgmtd config_timing
+   ...
+   $ find /tmp/topotests/ -name '*perf.data*'
+   /tmp/topotests/config_timing.test_config_timing/r1/perf.data
+
+To specify additional arguments for ``rr record``, one can use the
+``--rr-options``.
+
 .. _topotests_docker:
 
 Running Tests with Docker