diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-08-05 09:56:23 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-08-05 09:56:23 +0000 |
commit | c15d6efd40655f717841d00839a43df1ead5cb26 (patch) | |
tree | 35d579f9a19170e2b39085669ca92533c2d161b4 /doc | |
parent | Adding upstream version 10.0.1. (diff) | |
download | frr-c15d6efd40655f717841d00839a43df1ead5cb26.tar.xz frr-c15d6efd40655f717841d00839a43df1ead5cb26.zip |
Adding upstream version 10.1.upstream/10.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
32 files changed, 465 insertions, 232 deletions
diff --git a/doc/developer/building-libyang.rst b/doc/developer/building-libyang.rst index a46c793..8d9876c 100644 --- a/doc/developer/building-libyang.rst +++ b/doc/developer/building-libyang.rst @@ -41,7 +41,7 @@ DEB packages are available as CI artifacts `here cd libyang git checkout v2.1.128 mkdir build; cd build - cmake -D CMAKE_INSTALL_PREFIX:PATH=/usr \ + cmake --install-prefix /usr \ -D CMAKE_BUILD_TYPE:String="Release" .. make sudo make install diff --git a/doc/developer/checkpatch.rst b/doc/developer/checkpatch.rst index d8fe007..4ef261b 100644 --- a/doc/developer/checkpatch.rst +++ b/doc/developer/checkpatch.rst @@ -761,15 +761,6 @@ Indentation and Line Breaks Macros, Attributes and Symbols ------------------------------ - **ARRAY_SIZE** - The ARRAY_SIZE(foo) macro should be preferred over - sizeof(foo)/sizeof(foo[0]) for finding number of elements in an - array. - - The macro is defined in include/linux/kernel.h:: - - #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) - **AVOID_EXTERNS** Function prototypes don't need to be declared extern in .h files. It's assumed by the compiler and is unnecessary. diff --git a/doc/developer/cross-compiling.rst b/doc/developer/cross-compiling.rst index af99262..c503487 100644 --- a/doc/developer/cross-compiling.rst +++ b/doc/developer/cross-compiling.rst @@ -148,7 +148,7 @@ be built and installed generally like: CC=${HOST_ARCH}-gcc \ CXX=${HOST_ARCH}-g++ \ cmake \ - -DCMAKE_INSTALL_PREFIX=/usr/${HOST_ARCH} \ + --install-prefix /usr/${HOST_ARCH} \ .. make make install diff --git a/doc/developer/logging.rst b/doc/developer/logging.rst index 52653d3..82cc8b2 100644 --- a/doc/developer/logging.rst +++ b/doc/developer/logging.rst @@ -77,7 +77,14 @@ are available: .. note:: - ``printfrr()`` does not support the ``%n`` format. + ``printfrr()`` does not support the ``%n`` format. It does support ISO C23 + ``%b``, ``%w99d`` and ``%wf99d`` additions, but the latter two are not + supported by the ``frr-format`` plugin yet, and all 3 aren't supported by + the older compilers still in use on some supported platforms. + + ``%b`` can be used with ``FMT_NSTD``, but ``%w99d`` and ``%wf99d`` require + work in the ``frr-format`` plugin before they are really usable. + AS-Safety ^^^^^^^^^ @@ -376,7 +383,8 @@ bgpd .. frrfmt:: %pBD (struct bgp_dest *) - Print prefix for a BGP destination. + Print prefix for a BGP destination. When using ``--enable-dev-build`` include + the pointer value for the bgp_dest. :frrfmtout:`fe80::1234/64` @@ -557,8 +565,9 @@ Integer formats cause compiler warnings when used without the plugin. Use with :c:macro:`FMT_NSTD` if necessary. - It is possible ISO C23 may introduce another format for these, possibly - ``%w64d`` discussed in `JTC 1/SC 22/WG 14/N2680 <http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2680.pdf>`_. + As anticipated, ISO C23 has introduced new modifiers for this, specifically + ``%w64d`` (= ``%Ld``) and ``%w64u`` (= ``%Lu``). Unfortunately, these new + modifiers are not supported by ``frr-format`` yet. .. frrfmt:: %Lu (uint64_t) diff --git a/doc/developer/mgmtd-dev.rst b/doc/developer/mgmtd-dev.rst index 2404ffe..b979af0 100644 --- a/doc/developer/mgmtd-dev.rst +++ b/doc/developer/mgmtd-dev.rst @@ -317,12 +317,25 @@ Likewise the client should be cleaned up in the daemon cleanup routine. Back-End XPATH mappings ^^^^^^^^^^^^^^^^^^^^^^^ -In order for ``mgmtd`` to direct configuration to your daemon you need to add +In order for ``mgmtd`` to direct YANG modeled data to your daemon you should add some XPATH mappings to ``mgmtd/mgmt_be_adapter.c``. These XPATHs determine which -configuration changes get sent over the *back-end* interface to your daemon. -There are 2 arrays to update the first for config support and the second for -operational state. - +YANG modeled data (e.g., config changes) get sent over the *back-end* interface +to your daemon. There are 4 arrays to possibly update: configuration, +operational, notification, and RPC. You only need to add entries to the array +that you require mapping for. + +Additionally the back-end client can specify these XPATH mappings when it +first connects to mgmtd using it's initial ``SUBSCRIBE`` message. + +NOTE: the notif array (``be_client_notif_xpaths``), is a slightly different from +the other 3 types (config, oper and rpc) in that it maps xpaths the back-end +client wishes to *receive* notifications for, not the ones it may generate. +Normally a back-end client is generating notifications; however, mgmtd supports +back-end clients also "subscribing" to receive these notifications as well from +other back-end clients through notif_xpath maps. + +Config Map Example +"""""""""""""""""" Below are the strings added for staticd config support: .. code-block:: c @@ -342,6 +355,9 @@ Below are the strings added for staticd config support: #endif }; + +Operational Map Example +""""""""""""""""""""""" Below are the strings added for zebra operational state support (note zebra is not conditionalized b/c it should always be present): @@ -358,6 +374,33 @@ not conditionalized b/c it should always be present): [MGMTD_BE_CLIENT_ID_ZEBRA] = zebra_oper_xpaths, }; + +RPC Map Example +""""""""""""""" +Below is the string added for ripd RPC support: + +.. code-block:: c + + static const char *const ripd_rpc_xpaths[] = { + "/frr-ripd", + NULL, + }; + + static const char *const *be_client_rpc_xpaths[MGMTD_BE_CLIENT_ID_MAX] = { + #ifdef HAVE_RIPD + [MGMTD_BE_CLIENT_ID_RIPD] = ripd_rpc_xpaths, + #endif + }; + + +Notification Map Example +"""""""""""""""""""""""" +There are no current back-end daemons that wish to receive other back-end +notifications so the array is empty. This may change in the future, and of +course any back-end daemon can utilize the connect (``BeSubscribeReq``) messages +as well. + + MGMTD Internals --------------- diff --git a/doc/developer/northbound/advanced-topics.rst b/doc/developer/northbound/advanced-topics.rst index edfc10b..eb75602 100644 --- a/doc/developer/northbound/advanced-topics.rst +++ b/doc/developer/northbound/advanced-topics.rst @@ -12,8 +12,7 @@ Auto-generated CLI commands In order to have less code to maintain, it should be possible to write a tool that auto-generates CLI commands based on the FRR YANG models. As a matter of fact, there are already a number of NETCONF-based CLIs that do -exactly that (e.g. `Clixon <https://github.com/clicon/clixon>`__, -ConfD’s CLI). +exactly that (e.g. `Clixon <https://github.com/clicon/clixon>`__). The problem however is that there isn’t an exact one-to-one mapping between the existing CLI commands and the corresponding YANG nodes from @@ -27,11 +26,6 @@ command for each YANG leaf, (leaf-)list and presence-container. The ripd’s ``timers basic`` command, for instance, would become three different commands, which would be undesirable. - This Tail-f’s® - `document <http://info.tail-f.com/hubfs/Whitepapers/Tail-f_ConfD-CLI__Cfg_Mode_App_Note_Rev%20C.pdf>`__ - shows how to customize ConfD auto-generated CLI commands using YANG - annotations. - The good news is that *libyang* allows users to create plugins to implement their own YANG extensions, which can be used to implement CLI annotations. If done properly, a CLI generator can save FRR developers @@ -76,8 +70,8 @@ Example of how this feature could be provided in the CLI: ``commit confirmed [minutes <1-60>]``. The ability to do confirmed commits should also be exposed in the northbound API so that the northbound plugins can also take advantage of it (in the case of the -Sysrepo and ConfD plugins, confirmed commits are implemented externally -in the *netopeer2-server* and *confd* daemons, respectively). +Sysrepo plugin, confirmed commit is implemented externally in the +*netopeer2-server* daemon). Proposed feature: enable/disable configuration commands/sections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/developer/northbound/architecture.rst b/doc/developer/northbound/architecture.rst index 5fd89c3..4e84f1d 100644 --- a/doc/developer/northbound/architecture.rst +++ b/doc/developer/northbound/architecture.rst @@ -116,7 +116,7 @@ multitude of different management APIs, all of them connected to the northbound layer of the FRR daemons. By default, only the CLI interface is compiled built-in in the FRR daemons. The other management interfaces are provided as optional plugins and need to be loaded during the daemon -initialization (e.g. *zebra -M confd*). This design makes it possible to +initialization (e.g. *zebra -M grpc*). This design makes it possible to integrate FRR with different NETCONF solutions without introducing vendor lock-in. The [[Plugins - Writing Your Own]] page explains how to write custom northbound plugins that can be tailored to all needs diff --git a/doc/developer/northbound/demos.rst b/doc/developer/northbound/demos.rst index 8a0f6ad..7c5ae0c 100644 --- a/doc/developer/northbound/demos.rst +++ b/doc/developer/northbound/demos.rst @@ -8,23 +8,3 @@ This short demo shows some of the capabilities of the new transactional CLI: |asciicast1| - -ConfD + NETCONF + Cisco YDK ---------------------------- - -This is a very simple demo of *ripd* being configured by a python -script. The script uses NETCONF to communicate with *ripd*, which has -the ConfD plugin loaded. The most interesting part, however, is the fact -that the python script is not using handcrafted XML payloads to -configure *ripd*. Instead, the script is using python bindings generated -using Cisco’s YANG Development Kit (YDK). - -- Script used in the demo: - https://gist.github.com/rwestphal/defa9bd1ccf216ab082d4711ae402f95 - -|asciicast2| - -.. |asciicast1| image:: https://asciinema.org/a/jL0BS5HfP2kS6N1HfgsZvfZk1.png - :target: https://asciinema.org/a/jL0BS5HfP2kS6N1HfgsZvfZk1 -.. |asciicast2| image:: https://asciinema.org/a/VfMElNxsjLcdvV7484E6ChxWv.png - :target: https://asciinema.org/a/VfMElNxsjLcdvV7484E6ChxWv diff --git a/doc/developer/northbound/links.rst b/doc/developer/northbound/links.rst index 6cec176..e8fb327 100644 --- a/doc/developer/northbound/links.rst +++ b/doc/developer/northbound/links.rst @@ -195,14 +195,6 @@ pyangbind - GitHub page: https://github.com/robshakir/pyangbind - Documentation: http://pynms.io/pyangbind/ -ConfD -^^^^^ - -- Official webpage (for ConfD Basic): - http://www.tail-f.com/confd-basic/ -- Training Videos: http://www.tail-f.com/confd-training-videos/ -- Forum: http://discuss.tail-f.com/ - Sysrepo ^^^^^^^ diff --git a/doc/developer/northbound/operational-data-rpcs-and-notifications.rst b/doc/developer/northbound/operational-data-rpcs-and-notifications.rst index 5cb70ca..07f92c2 100644 --- a/doc/developer/northbound/operational-data-rpcs-and-notifications.rst +++ b/doc/developer/northbound/operational-data-rpcs-and-notifications.rst @@ -10,10 +10,10 @@ Operational data ~~~~~~~~~~~~~~~~ Writing API-agnostic code for YANG-modeled operational data is -challenging. ConfD and Sysrepo, for instance, have completely different -APIs to fetch operational data. So how can we write API-agnostic -callbacks that can be used by both the ConfD and Sysrepo plugins, and -any other northbound client that might be written in the future? +challenging. Sysrepo, for instance, has completely different API to +fetch operational data. So how can we write API-agnostic callbacks +that can be used by both the Sysrepo plugin, and any other northbound +client that might be written in the future? As an additional requirement, the callbacks must be designed in a way that makes in-place XPath filtering possible. As an example, a @@ -94,27 +94,18 @@ in the northbound architecture: */ void *(*lookup_entry)(struct yang_list_keys *keys); -These callbacks were designed to provide maximum flexibility, and borrow -a lot of ideas from the ConfD API. Each callback does one and only one -task, they are indivisible primitives that can be combined in several -different ways to iterate over operational data. The extra flexibility -certainly has a performance cost, but it’s the price to pay if we want -to expose FRR operational data using several different management -interfaces (e.g. NETCONF via either ConfD or Sysrepo+Netopeer2). In the +These callbacks were designed to provide maximum flexibility. Each +callback does one and only one task, they are indivisible primitives +that can be combined in several different ways to iterate over operational +data. The extra flexibility certainly has a performance cost, but it’s the +price to pay if we want to expose FRR operational data using several +different management interfaces (e.g. Sysrepo+Netopeer2). In the future it might be possible to introduce optional callbacks that do things like returning multiple objects at once. They would provide enhanced performance when iterating over large lists, but their use would be limited by the northbound plugins that can be integrated with them. - NOTE: using the northbound callbacks as a base, the ConfD plugin can - provide up to 100 objects between each round trip between FRR and the - *confd* daemon. Preliminary tests showed FRR taking ~7 seconds - (asynchronously, without blocking the main pthread) to return a RIP - table containing 100k routes to a NETCONF client connected to *confd* - (JSON was used as the encoding format). Work needs to be done to find - the bottlenecks and optimize this operation. - The [[Plugins - Writing Your Own]] page explains how the northbound plugins can fetch operational data using the aforementioned northbound callbacks, and how in-place XPath filtering can be implemented. @@ -351,10 +342,10 @@ are being iterated over. If that is not done, the list entry returned by this callback can become a dangling pointer when used in another callback. -Currently the ConfD and Sysrepo plugins run only in the main pthread. -The plan in the short-term is to introduce a separate pthread only for -handling operational data, and use the main pthread only for handling -configuration changes, RPCs and notifications. +Currently the Sysrepo plugin runs only in the main pthread. The plan in the +short-term is to introduce a separate pthread only for handling operational +data, and use the main pthread only for handling configuration changes, +RPCs and notifications. RPCs and Actions ~~~~~~~~~~~~~~~~ @@ -396,8 +387,8 @@ some EXEC-level commands using YANG so that their functionality is exposed to other management interfaces other than the CLI. As an example, if the ``clear bgp`` command is modeled using a YANG RPC, and a corresponding ``rpc`` callback is written, then it should be possible to -clear BGP neighbors using NETCONF and RESTCONF with that RPC (the ConfD -and Sysrepo plugins have full support for YANG RPCs and actions). +clear BGP neighbors using NETCONF and RESTCONF with that RPC (the Sysrepo +plugin has full support for YANG RPCs and actions). Here’s an example of a very simple RPC modeled using YANG: @@ -568,8 +559,7 @@ Now sending the *authentication-failure* YANG notification should be as simple as calling the above function and provide the appropriate interface name. The notification will be processed by all northbound plugins that subscribed a callback to the ``nb_notification_send`` hook. -The ConfD and Sysrepo plugins, for instance, use this hook to relay the -notifications to the *confd*/*sysrepod* daemons, which can generate -NETCONF notifications to subscribed clients. When no northbound plugin -is loaded, ``nb_notification_send()`` doesn’t do anything and the -notifications are ignored. +The Sysrepo plugin, for instance, uses this hook to relay the notifications +to the *sysrepod* daemon, which can generate NETCONF notifications to subscribed +clients. When no northbound plugin is loaded, ``nb_notification_send()`` doesn’t +do anything and the notifications are ignored. diff --git a/doc/developer/northbound/plugins-sysrepo.rst b/doc/developer/northbound/plugins-sysrepo.rst index 0cfdb82..f4df68c 100644 --- a/doc/developer/northbound/plugins-sysrepo.rst +++ b/doc/developer/northbound/plugins-sysrepo.rst @@ -32,7 +32,7 @@ libyang cd libyang git checkout v2.1.148 mkdir build; cd build - cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr \ + cmake --install-prefix /usr \ -DCMAKE_BUILD_TYPE:String="Release" .. make sudo make install @@ -51,7 +51,7 @@ Sysrepo cd sysrepo/ git checkout v2.2.150 mkdir build; cd build - cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr \ + cmake --install-prefix /usr \ -DCMAKE_BUILD_TYPE:String="Release" .. make sudo make install diff --git a/doc/developer/static-linking.rst b/doc/developer/static-linking.rst index 5342fbf..e9bb928 100644 --- a/doc/developer/static-linking.rst +++ b/doc/developer/static-linking.rst @@ -44,7 +44,7 @@ when building libyang statically. The resultant cmake command is:: cmake -DENABLE_STATIC=ON -DENABLE_LYD_PRIV=ON \ - -DCMAKE_INSTALL_PREFIX:PATH=/usr \ + --install-prefix /usr \ -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE \ -DCMAKE_BUILD_TYPE:String="Release" .. diff --git a/doc/developer/topotests-markers.rst b/doc/developer/topotests-markers.rst index 9f92412..670bf0d 100644 --- a/doc/developer/topotests-markers.rst +++ b/doc/developer/topotests-markers.rst @@ -12,6 +12,7 @@ systems, all tests must be marked with at least one of the following markers: * eigrpd * isisd * ldpd +* mgmtd * nhrpd * ospf6d * ospfd @@ -64,12 +65,12 @@ Adding a single marker: import pytest ... - + # add after imports, before defining classes or functions: pytestmark = pytest.mark.bfdd - + ... - + def test_using_bfdd(): @@ -79,16 +80,16 @@ Adding multiple markers: import pytest ... - + # add after imports, before defining classes or functions: pytestmark = [ pytest.mark.bgpd, pytest.mark.ospfd, pytest.mark.ospf6d ] - + ... - + def test_using_bgpd_ospfd_ospf6d(): diff --git a/doc/developer/topotests.rst b/doc/developer/topotests.rst index 9b9058b..e1702c4 100644 --- a/doc/developer/topotests.rst +++ b/doc/developer/topotests.rst @@ -46,6 +46,7 @@ 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' @@ -712,6 +713,44 @@ Here's an example of collecting ``rr`` execution state from ``mgmtd`` on router To specify additional arguments for ``rr record``, one can use the ``--rr-options``. +.. _code_coverage: + +Code coverage +""""""""""""" +Code coverage reporting requires installation of the ``gcov`` and ``lcov`` +packages. + +Code coverage can automatically be gathered for any topotest run. To support +this FRR must first be compiled with the ``--enable-gcov`` configure option. +This will cause *.gnco files to be created during the build. When topotests are +run the statistics are generated and stored in *.gcda files. Topotest +infrastructure will gather these files, capture the information into a +``coverage.info`` ``lcov`` file and also report the coverage summary. + +To enable code coverage support pass the ``--cov-topotest`` argument to pytest. +If you build your FRR in a directory outside of the FRR source directory you +will also need to pass the ``--cov-frr-build-dir`` argument specifying the build +directory location. + +During the topotest run the *.gcda files are generated into a ``gcda`` +sub-directory of the top-level run directory (i.e., normally +``/tmp/topotests/gcda``). These files will then be copied at the end of the +topotest run into the FRR build directory where the ``gcov`` and ``lcov`` +utilities expect to find them. This is done to deal with the various different +file ownership and permissions. + +At the end of the run ``lcov`` will be run to capture all of the coverage data +into a ``coverage.info`` file. This file will be located in the top-level run +directory (i.e., normally ``/tmp/topotests/coverage.info``). + +The ``coverage.info`` file can then be used to generate coverage reports or file +markup (e.g., using the ``genhtml`` utility) or enable markup within your +IDE/editor if supported (e.g., the emacs ``cov-mode`` package) + +NOTE: the *.gcda files in ``/tmp/topotests/gcda`` are cumulative so if you do +not remove them they will aggregate data across multiple topotest runs. + + .. _topotests_docker: Running Tests with Docker diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index 68834ed..f720f62 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -167,13 +167,13 @@ as early as possible, i.e. the first 2-week window. For reference, the expected release schedule according to the above is: +---------+------------+------------+------------+ -| Release | 2023-11-07 | 2024-03-05 | 2024-07-02 | +| Release | 2024-03-12 | 2024-07-02 | 2024-11-05 | +---------+------------+------------+------------+ -| RC | 2023-10-24 | 2024-02-20 | 2024-06-18 | +| RC | 2024-02-27 | 2024-06-18 | 2024-10-22 | +---------+------------+------------+------------+ -| dev/X.Y | 2023-10-10 | 2024-02-06 | 2024-06-04 | +| dev/X.Y | 2024-02-13 | 2024-06-04 | 2024-10-08 | +---------+------------+------------+------------+ -| freeze | 2023-09-26 | 2024-01-23 | 2024-05-21 | +| freeze | 2024-01-30 | 2024-05-21 | 2024-09-24 | +---------+------------+------------+------------+ Here is the hint on how to get the dates easily: diff --git a/doc/developer/zebra.rst b/doc/developer/zebra.rst index be2952e..482df96 100644 --- a/doc/developer/zebra.rst +++ b/doc/developer/zebra.rst @@ -161,6 +161,21 @@ Zebra Protocol Commands The definitions of zebra protocol commands can be found at ``lib/zclient.h``. + +Zebra Dataplane +=============== + +The zebra dataplane subsystem provides a framework for FIB +programming. Zebra uses the dataplane to program the local kernel as +it makes changes to objects such as IP routes, MPLS LSPs, and +interface IP addresses. The dataplane runs in its own pthread, in +order to off-load work from the main zebra pthread. + +The zebra dataplane API is versioned; the version number must be +updated along with API changes. Plugins can test the current version +number and confirm that they are compatible with the current version. + + Dataplane batching ================== diff --git a/doc/user/bgp.rst b/doc/user/bgp.rst index 99d2a8c..150a915 100644 --- a/doc/user/bgp.rst +++ b/doc/user/bgp.rst @@ -589,26 +589,52 @@ Route Flap Dampening .. clicmd:: bgp dampening (1-45) (1-20000) (1-50000) (1-255) - This command enables BGP route-flap dampening and specifies dampening parameters. + This command enables (with optionally specified dampening parameters) or + disables route-flap dampening for all routes of a BGP instance. + +.. clicmd:: neighbor PEER dampening [(1-45) [(1-20000) (1-20000) (1-255)]] + + This command enables (with optionally specified dampening parameters) or + disables route-flap dampening for all routes learned from a BGP peer. + +.. clicmd:: neighbor GROUP dampening [(1-45) [(1-20000) (1-20000) (1-255)]] + + This command enables (with optionally specified dampening parameters) or + disables route-flap dampening for all routes learned from peers of a peer + group. half-life - Half-life time for the penalty + Half-life time for the penalty in minutes (default value: 15). reuse-threshold - Value to start reusing a route + Value to start reusing a route (default value: 750). suppress-threshold - Value to start suppressing a route + Value to start suppressing a route (default value: 2000). max-suppress - Maximum duration to suppress a stable route + Maximum duration to suppress a stable route in minutes (default value: + 60). The route-flap damping algorithm is compatible with :rfc:`2439`. The use of - this command is not recommended nowadays. + these commands is not recommended nowadays. At the moment, route-flap dampening is not working per VRF and is working only for IPv4 unicast and multicast. + With different parameter sets configurable for BGP instances, peer groups and + peers, the active dampening profile for a route is chosen on the fly, + allowing for various changes in configuration (i.e. peer group memberships) + during runtime. The parameter sets are taking precedence in the following + order: + + 1. Peer + 2. Peer group + 3. BGP instance + + The negating commands do not allow to exclude a peer/peer group from a peer + group/BGP instances configuration. + .. seealso:: https://www.ripe.net/publications/docs/ripe-378 @@ -1064,7 +1090,7 @@ BGP GR Global Mode Commands This command will enable BGP graceful restart functionality at the global level. -.. clicmd:: bgp graceful-restart disable +.. clicmd:: bgp graceful-restart-disable This command will disable both the functionality graceful restart and helper mode. @@ -1334,7 +1360,14 @@ OSPFv3 into ``address-family ipv4 unicast`` as OSPFv3 supports IPv6. .. clicmd:: redistribute <babel|connected|eigrp|isis|kernel|openfabric|ospf|ospf6|rip|ripng|sharp|static> [metric (0-4294967295)] [route-map WORD] -Redistribute routes from other protocols into BGP. + Redistribute routes from other protocols into BGP. + + Note - When redistributing a static route, or any better Admin Distance route, + into BGP for which the same path is learned dynamically from another BGP + speaker, if the redistribute path is more preferred from a BGP Best Path + standpoint than the dynamically learned path, then BGP will not export + the best path to Zebra(RIB) for installation into the routing table, + unless BGP receives the path before the static route is created. .. clicmd:: redistribute <table|table-direct> (1-65535)] [metric (0-4294967295)] [route-map WORD] @@ -1565,6 +1598,15 @@ Configuring Peers value is carried encoded as uint32. To enable backward compatibility we need to disable IEEE floating-point encoding option per-peer. +.. clicmd:: neighbor PEER extended-link-bandwidth + + By default bandwidth in extended communities is carried encoded as IEEE + floating-point format, and is limited to maximum of 25 Gbps. + + Enabling this parameter, you can use the bandwidth of to 4294967295 Mbps. + + This is disabled by default. + .. clicmd:: neighbor PEER enforce-first-as Discard updates received from the specified (eBGP) peer if the AS_PATH @@ -1785,6 +1827,17 @@ Configuring Peers Do not accept additional paths from this neighbor. +.. clicmd:: neighbor <A.B.C.D|X:X::X:X|WORD> addpath-rx-paths-limit (1-65535) + + Limit the maximum number of paths a BGP speaker can receive from a peer, optimizing + the transmission of BGP routes by selectively relaying pertinent routes instead of + the entire set. + + If this command is configured, the sender will only send the number of paths specified + in PATHS-LIMIT capability. + + To exchange this limit, both peers must support the PATHS-LIMIT capability. + .. clicmd:: neighbor PEER ttl-security hops NUMBER This command enforces Generalized TTL Security Mechanism (GTSM), as @@ -1810,7 +1863,7 @@ Configuring Peers This includes changing graceful-restart (LLGR also) timers, enabling/disabling add-path, and other supported capabilities. -.. clicmd:: neighbor PEER capability fqdn +.. clicmd:: neighbor PEER capability fqdn Allow BGP to negotiate the FQDN Capability with its peers. @@ -1819,7 +1872,7 @@ Configuring Peers This capability is activated by default. The ``no neighbor PEER capability fqdn`` avoid negotiation of that capability. This is useful for peers who - are not supporting this capability or supporting BGP Capabilities + are not supporting this capability or supporting BGP Capabilities Negotiation RFC 2842. .. clicmd:: neighbor <A.B.C.D|X:X::X:X|WORD> accept-own @@ -1943,6 +1996,13 @@ Configuring Peers outputs. It's easier to troubleshoot if you have a number of BGP peers and a number of routes to check. +.. clicmd:: bgp default dynamic-capability + + This command enables dynamic capability advertisement by default + for all the neighbors. + + For ``datacenter`` profile, this is enabled by default. + .. clicmd:: bgp default software-version-capability This command enables software version capability advertisement by default @@ -3201,6 +3261,31 @@ L3VPN SRv6 Specify the SRv6 locator to be used for SRv6 L3VPN. The Locator name must be set in zebra, but user can set it in any order. +L3VPN SRv6 SID reachability +--------------------------- + +In the context of IPv4 L3VPN over SRv6 specific usecase, 2001:db8:12::2 +is the peer IPv6 address of r2, and 2001:db8:2:2:: is the SRv6 SID +advertised by router r2 for prefix P. On r1, the SID reachability is +checked in order to install the prefix P. The below output indicates +that the 2001:db8:2:2:: prefix is valid. + + +.. code-block:: frr + + r1# show bgp nexthop detail + Current BGP nexthop cache: + 2001:db8:2:2:: valid [IGP metric 0], #paths 4 + gate 2001:db8:12::2, if eth0 + Last update: Tue Nov 14 10:36:28 2023 + Paths: + 1/1 192.168.2.0/24 VRF vrf10 flags 0x4018 + 1/3 192.168.2.0/24 RD 65002:10 VRF default flags 0x418 + 2001:db8:12::2 valid [IGP metric 0], #paths 0, peer 2001:db8:12::2 + if eth0 + Last update: Tue Nov 14 10:36:26 2023 + Paths: + General configuration ^^^^^^^^^^^^^^^^^^^^^ @@ -4017,6 +4102,10 @@ The following are available in the top level *enable* mode: Clear all peers. +.. clicmd:: clear bgp ipv4|ipv6 ASNUM + + Clear peers with the AS number in plain or dotted format. + .. clicmd:: clear bgp ipv4|ipv6 \* Clear all peers with this address-family activated. @@ -4848,8 +4937,8 @@ setting. .. clicmd:: bgp session-dscp (0-63) -This command allows bgp to control, at a global level, the TCP dscp values -in the TCP header. +This command allows the BGP daemon to control, at a global level, the DSCP value +used in outgoing packets for each BGP connection. .. _bgp-suppress-fib: diff --git a/doc/user/bmp.rst b/doc/user/bmp.rst index 0f46832..14d0849 100644 --- a/doc/user/bmp.rst +++ b/doc/user/bmp.rst @@ -23,6 +23,8 @@ The `BMP` implementation in FRR has the following properties: - 3: count of **prefixes** with loop in cluster id - 4: count of **prefixes** with loop in AS-path - 5: count of **prefixes** with loop in originator + - 7: count of **routes** in adj-rib-in + - 8: count of **routes** in Loc-RIB - 11: count of updates subjected to :rfc:`7607` "treat as withdrawal" handling due to errors - 65531: *experimental* count of prefixes rejected due to invalid next-hop @@ -146,6 +148,11 @@ associated with a particular ``bmp targets``: Send BMP Statistics (counter) messages at the specified interval (in milliseconds.) +.. clicmd:: bmp stats send-experimental + + Send BMP Statistics (counter) messages whose code is defined as + experimental (in the [65531-65534] range). + .. clicmd:: bmp monitor AFI SAFI <pre-policy|post-policy|loc-rib> Perform Route Monitoring for the specified AFI and SAFI. Only IPv4 and diff --git a/doc/user/installation.rst b/doc/user/installation.rst index fb9e23d..e49f104 100644 --- a/doc/user/installation.rst +++ b/doc/user/installation.rst @@ -274,6 +274,10 @@ options from the list below. Build with FPM module support. +.. option:: --enable-fpm-listener + + Build a small fpm listener for testing. + .. option:: --with-service-timeout=X Set timeout value for FRR service. The time of restarting or reloading FRR @@ -309,13 +313,6 @@ options from the list below. make these arrays at build time. Additionally if this parameter is not passed in FRR will default to 16 ECMP. -.. option:: --enable-shell-access - - Turn on the ability of FRR to access some shell options( telnet/ssh/bash/etc. ) - from vtysh itself. This option is considered extremely unsecure and should only - be considered for usage if you really really know what you are doing. This - option is deprecated and will be removed on Feb 1, 2024. - .. option:: --enable-gcov Code coverage reports from gcov require adjustments to the C and LD flags. @@ -329,11 +326,6 @@ options from the list below. Build with configuration rollback support. Requires SQLite3. -.. option:: --enable-confd=<dir> - - Build the ConfD northbound plugin. Look for the libconfd libs and headers - in `dir`. - .. option:: --enable-sysrepo Build the Sysrepo northbound plugin. @@ -430,7 +422,12 @@ options to the configuration script. Python dependency, documentation and tests ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -FRR's documentation and basic unit tests heavily use code written in Python. +FRR uses Python for these components: + +* configuration reloading (see :ref:`FRR-RELOAD <frr-reload>` for details), +* documentation, +* unit tests. + Additionally, FRR ships Python extensions written in C which are used during its build process. diff --git a/doc/user/isisd.rst b/doc/user/isisd.rst index d37dfa6..7412611 100644 --- a/doc/user/isisd.rst +++ b/doc/user/isisd.rst @@ -123,7 +123,7 @@ ISIS Timer Set LSP refresh interval in seconds, globally, for an area (level-1) or a domain (level-2). -.. clicmd:: max-lsp-lifetime [level-1 | level-2] (360-65535) +.. clicmd:: max-lsp-lifetime [level-1 | level-2] (350-65535) Set LSP maximum LSP lifetime in seconds, globally, for an area (level-1) or a domain (level-2). @@ -224,17 +224,17 @@ ISIS interface Add padding to IS-IS hello packets during adjacency formation only. -.. clicmd:: isis hello-interval (1-600) [level-1 | level-2] +.. clicmd:: isis hello-interval [level-1 | level-2] (1-600) Set Hello interval in seconds globally, for an area (level-1) or a domain (level-2). -.. clicmd:: isis hello-multiplier (2-100) [level-1 | level-2] +.. clicmd:: isis hello-multiplier [level-1 | level-2] (2-100) Set multiplier for Hello holding time globally, for an area (level-1) or a domain (level-2). -.. clicmd:: isis metric [(0-255) | (0-16777215)] [level-1 | level-2] +.. clicmd:: isis metric [level-1 | level-2] [(0-255) | (0-16777215)] Set default metric value globally, for an area (level-1) or a domain (level-2). Max value depend if metric support narrow or wide value (see @@ -301,7 +301,7 @@ Showing ISIS information Show summary information about ISIS. -.. clicmd:: show isis hostname +.. clicmd:: show isis [vrf <NAME|all>] hostname Show information about ISIS node. @@ -320,17 +320,17 @@ Showing ISIS information Show the ISIS database globally, for a specific LSP id without or with details. -.. clicmd:: show isis topology [level-1|level-2] [algorithm (128-255)] +.. clicmd:: show isis [vrf <NAME|all>] topology [level-1|level-2] [algorithm [(128-255)]] Show topology IS-IS paths to Intermediate Systems, globally, in area (level-1) or domain (level-2). -.. clicmd:: show isis route [level-1|level-2] [prefix-sid|backup] [algorithm (128-255)] +.. clicmd:: show isis [vrf <NAME|all>] route [level-1|level-2] [prefix-sid|backup] [algorithm [(128-255)]] Show the ISIS routing table, as determined by the most recent SPF calculation. -.. clicmd:: show isis fast-reroute summary [level-1|level-2] +.. clicmd:: show isis [vrf <NAME|all>] fast-reroute summary [level-1|level-2] Show information about the number of prefixes having LFA protection, and network-wide LFA coverage. @@ -435,7 +435,7 @@ Known limitations: clear the Node flag that is set by default for Prefix-SIDs associated to loopback addresses. This option is necessary to configure Anycast-SIDs. -.. clicmd:: show isis segment-routing node [algorithm (128-255)] +.. clicmd:: show isis segment-routing node [algorithm [(128-255)]] Show detailed information about all learned Segment Routing Nodes. @@ -462,10 +462,14 @@ To do so, it defines a set of Flex-Algo Definitions (FAD) which have the following characteristics: - a numeric identifier (ID) between 128 and 255 inclusive + - a set of constraints (basically, include or exclude a certain given set of links, designated by a admin-group) + - the calculation type (only the `Shortest-Path-First` is currently supported) + - the metric type (only the IGP inherited metric type is currently supported) + - some additional flags (not supported for the moment). A subset of routers advertises the Flex-Algo Definitions (FAD) to the other @@ -475,13 +479,18 @@ rules: - If a locally configured FAD is not advertised to the area, the router does not participate in the particular flex algorithm. + - If a given flex algorithm is running, the participation in this particular flex algorithm stops when its advertisements are over. + - A router includes its own FAD in the election process if and only if it is advertised to the other routers. + - If only one router advertises the FAD, the FAD is elected. + - If several FADs are advertised with different priorities, the one with the highest priority value is selected. + - If there are multiple advertisements of the FAD with the same highest priority, the FAD of the router with the highest IS-IS system-ID is selected. @@ -497,15 +506,11 @@ which flex algorithm they must use for a given packet. The following commands configure Flex-Algo at the 'router isis' configuration level. Segment-Routing prefixes must be configured for the Flex-Algo. -.. clicmd:: flexible-algorithm (128-255) +.. clicmd:: flex-algo (128-255) Add a Flex-Algo Definition (FAD) and enter the FAD configuration level. The algorithm ID value is in the range of 128 to 255 inclusive. -.. clicmd:: no flexible-algorithm (128-255) - - Unconfigure a Flex-Algo Definition. - .. clicmd:: affinity-map NAME bit-position (0-255) Add the specified 'affinity-map'. Affinity-map definitions are used in @@ -517,7 +522,7 @@ level. Segment-Routing prefixes must be configured for the Flex-Algo. admin-group 'bit-position' is set 1, else it is set to 0. The following commands configure Flex-Algo at the 'router isis' and -'flexible-algorithm (128-255)' configuration level. +'flex-algo (128-255)' configuration level. .. clicmd:: advertise-definition @@ -634,26 +639,14 @@ Debugging ISIS IS-IS Adjacency related packets. -.. clicmd:: debug isis checksum-errors - - IS-IS LSP checksum errors. - .. clicmd:: debug isis events IS-IS Events. -.. clicmd:: debug isis local-updates - - IS-IS local update packets. - .. clicmd:: debug isis packet-dump IS-IS packet dump. -.. clicmd:: debug isis protocol-errors - - IS-IS LSP protocol errors. - .. clicmd:: debug isis route-events IS-IS Route related events. @@ -663,11 +656,8 @@ Debugging ISIS IS-IS CSNP/PSNP packets. .. clicmd:: debug isis spf-events -.. clicmd:: debug isis spf-statistics -.. clicmd:: debug isis spf-triggers - IS-IS Shortest Path First Events, Timing and Statistic Data and triggering - events. + IS-IS Shortest Path First Events. .. clicmd:: debug isis update-packets @@ -846,7 +836,7 @@ A simple vrf example: ! interface eth0 vrf RED - ip router isis FOO vrf RED + ip router isis FOO isis network point-to-point isis circuit-type level-2-only ! diff --git a/doc/user/mgmtd.rst b/doc/user/mgmtd.rst index aa7ccaa..8b197bb 100644 --- a/doc/user/mgmtd.rst +++ b/doc/user/mgmtd.rst @@ -97,6 +97,8 @@ Following are some of the management operations supported: - Currently committing configurations from Candidate to Running database is only allowed, and not vice versa. +Front-End Native Protobuf API +""""""""""""""""""""""""""""" The exact set of message-based APIs are represented as Google Protobuf messages and can be found in the following file distributed with FRR codebase. @@ -104,6 +106,14 @@ messages and can be found in the following file distributed with FRR codebase. lib/mgmt.proto +Front-End Native (non-protobuf) API +""""""""""""""""""""""""""""""""""" +Additionally there exists a "native" API that does not utilize ``protobuf``s +this native API and the front-end messages and structures it supports are +documented in the header file ``lib/mgmt_msg_native.h``. + +Connecting to MGMTd +""""""""""""""""""" The MGMT daemon implements a MGMT Frontend Server that opens a UNIX socket-based IPC channel on the following path to listen for incoming connections from all possible Frontend clients: @@ -124,7 +134,9 @@ specification of this library can be found at: lib/mgmt_fe_client.h -Following is a list of message types supported on the MGMT Frontend Interface: +Following is a list of protobuf message types supported on the MGMT Frontend +Interface: + - SESSION_REQ<Client-Connection-Id, Destroy> - SESSION_REPLY<Client-Connection-Id, Destroy, Session-Id> - LOCK_DB_REQ <Session-Id, Database-Id> @@ -139,8 +151,21 @@ Following is a list of message types supported on the MGMT Frontend Interface: - COMMIT_CONFIG_REPLY <Session-Id, Source-Db-id, Dest-Db-Id, Status> - GET_DATA_REQ <Session-Id, Database-Id, Base-Yang-Xpath> - GET_DATA_REPLY <Session-Id, Database-id, Base-Yang-Xpath, Yang-Data-Set> - - REGISTER_NOTIFY_REQ <Session-Id, Database-Id, Base-Yang-Xpath> - - DATA_NOTIFY_REQ <Database-Id, Base-Yang-Xpath, Yang-Data-Set> + +Following is a list of native messages types supported by the MGMTd Front-End +API: + + - ERROR (receive) - received in response to any sent native message. + - TREE_DATA (receive) - returned data from a datastore + - GET_DATA (send) - get a tree of data + - NOTIFY (receive) - a notification received from mgmtd + - EDIT (send) - edit configuration datastore + - EDIT_REPLY (receive) - reply for an edit operation + - RPC (send) - sending (invoking) an RPC. + - RPC_REPLY (receive) - reply from invoking an RPC + - NOTIFY_SELECT (send) - specify the sub-set of notifications the front-end + wishes to receive, rather than the default of receiving all. + Please refer to the MGMT Frontend Client Developers Reference and Guide (coming soon) for more details. diff --git a/doc/user/ospf6d.rst b/doc/user/ospf6d.rst index ad58610..ea41ba5 100644 --- a/doc/user/ospf6d.rst +++ b/doc/user/ospf6d.rst @@ -494,11 +494,11 @@ Graceful Restart Configure Graceful Restart (RFC 5187) helper support. - By default, helper support is disabled for all neighbours. + By default, helper support is disabled for all neighbors. This config enables/disables helper support on this router - for all neighbours. + for all neighbors. To enable/disable helper support for a specific - neighbour, the router-id (A.B.C.D) has to be specified. + neighbor, the router-id (A.B.C.D) has to be specified. .. clicmd:: graceful-restart helper strict-lsa-checking diff --git a/doc/user/ospf_fundamentals.rst b/doc/user/ospf_fundamentals.rst index c566059..3032d27 100644 --- a/doc/user/ospf_fundamentals.rst +++ b/doc/user/ospf_fundamentals.rst @@ -12,7 +12,7 @@ OSPF Fundamentals :term:`distance-vector` protocols, such as :abbr:`RIP` or :abbr:`BGP`, where routers describe available `paths` (i.e. routes) to each other, in :term:`link-state` protocols routers instead describe the state of their links -to their immediate neighbouring routers. +to their immediate neighboring routers. .. index:: single: Link State Announcement @@ -127,7 +127,7 @@ LSA Flooding """""""""""" OSPF defines several related mechanisms, used to manage synchronisation of -:abbr:`LSDB` s between neighbours as neighbours form adjacencies and the +:abbr:`LSDB` s between neighbors as neighbors form adjacencies and the propagation, or `flooding` of new or updated :abbr:`LSA` s. @@ -259,7 +259,7 @@ called `intra-area routes`. LSA is originated for such a link. Stub - A link with no adjacent neighbours, or a host route. + A link with no adjacent neighbors, or a host route. - Link ID and Data @@ -339,8 +339,8 @@ The example below shows two :abbr:`LSA` s, both originated by the same router of different LSA types. The first LSA being the router LSA describing 192.168.0.49's links: 2 links -to multi-access networks with fully-adjacent neighbours (i.e. Transit -links) and 1 being a Stub link (no adjacent neighbours). +to multi-access networks with fully-adjacent neighbors (i.e. Transit +links) and 1 being a Stub link (no adjacent neighbors). The second LSA being a Network LSA, for which 192.168.0.49 is the :abbr:`DR`, listing the Router IDs of 4 routers on that network which diff --git a/doc/user/ospfd.rst b/doc/user/ospfd.rst index 3bc4487..70c15e7 100644 --- a/doc/user/ospfd.rst +++ b/doc/user/ospfd.rst @@ -28,6 +28,12 @@ Configuring OSPF Enable the OSPF API server. This is required to use ``ospfclient``. +.. option:: -l, --apiserver_addr <address> + + Specify the local IPv4 address to which to bind the OSPF API server socket. + If unspecified, connections are accepted to any address. Specification of + 127.0.0.1 can be used to limit socket access to local applications. + *ospfd* must acquire interface information from *zebra* in order to function. Therefore *zebra* must be running before invoking *ospfd*. Also, if *zebra* is restarted then *ospfd* must be too. @@ -239,6 +245,17 @@ To start OSPF process you have to specify the OSPF router. This configuration setting MUST be consistent across all routers within the OSPF domain. +.. clicmd:: neighbor A.B.C.D [poll-interval (1-65535)] [priority (0-255)] + + + Configures OSPF neighbors for non-broadcast multi-access (NBMA) networks + and point-to-multipoint non-broadcast networks. The `poll-interval` + specifies the rate for sending hello packets to neighbors that are not + active. When the configured neighbor is discovered, hello packets will be + sent at the rate of the hello-interval. The default `poll-interval` is 60 + seconds. The `priority` is used to for the Designated Router (DR) election + on non-broadcast multi-access networks. + .. clicmd:: network A.B.C.D/M area A.B.C.D .. clicmd:: network A.B.C.D/M area (0-4294967295) @@ -580,7 +597,7 @@ Interfaces Note that OSPF MD5 authentication requires that time never go backwards (correct time is NOT important, only that it never goes backwards), even across resets, if ospfd is to be able to promptly reestablish adjacencies - with its neighbours after restarts/reboots. The host should have system time + with its neighbors after restarts/reboots. The host should have system time be set at boot from an external or non-volatile source (e.g. battery backed clock, NTP, etc.) or else the system clock should be periodically saved to non-volatile storage and restored at boot if MD5 authentication is to be @@ -612,7 +629,7 @@ Interfaces Note that OSPF HMAC cryptographic authentication requires that time never go backwards (correct time is NOT important, only that it never goes backwards), even across resets, if ospfd is to be able to promptly reestablish adjacencies - with its neighbours after restarts/reboots. The host should have system time + with its neighbors after restarts/reboots. The host should have system time be set at boot from an external or non-volatile source (e.g. battery backed clock, NTP, etc.) or else the system clock should be periodically saved to non-volatile storage and restored at boot if HMAC cryptographic authentication is to be @@ -679,7 +696,7 @@ Interfaces it's recommended to set the hello delay and hello interval with the same values. The default value is 10 seconds. -.. clicmd:: ip ospf network (broadcast|non-broadcast|point-to-multipoint [delay-reflood]|point-to-point [dmvpn]) +.. clicmd:: ip ospf network (broadcast|non-broadcast|point-to-multipoint [delay-reflood|non-broadcast]|point-to-point [dmvpn]) When configuring a point-to-point network on an interface and the interface has a /32 address associated with then OSPF will treat the interface @@ -691,6 +708,13 @@ Interfaces point-to-point, but the HUB will be a point-to-multipoint. To make this topology work, specify the optional 'dmvpn' parameter at the spoke. + When the network is configured as point-to-multipoint and `non-broadcast` + is specified, the network doesn't support broadcast or multicast delivery + and neighbors cannot be discovered from OSPF hello received from the + OSPFAllRouters (224.0.0.5). Rather, they must be explicitly configured + using the :clicmd:`neighbor A.B.C.D` configuration command as they are + on non-broadcast networks. + When the network is configured as point-to-multipoint and `delay-reflood` is specified, LSAs received on the interface from neighbors on the interface will not be flooded back out on the interface immediately. @@ -739,6 +763,32 @@ Interfaces optional IPv4 address is specified, the prefix suppression will apply to the OSPF interface associated with the specified interface address. +.. clicmd:: ip ospf neighbor-filter NAME [A.B.C.D] + + Configure an IP prefix-list to use to filter packets received from + OSPF neighbors on the OSPF interface. The prefix-list should include rules + to permit or deny OSPF neighbors by IP source address. This is useful for + multi-access interfaces where adjacencies with only a subset of the + reachable neighbors are desired. Applications include testing partially + meshed topologies, OSPF Denial of Sevice (DoS) mitigation, and avoidance + of adjacencies with OSPF neighbors not meeting traffic engineering criteria. + + Example: + +.. code-block:: frr + + ! + ! Prefix-list to block neighbor with source address 10.1.0.2 + ! + ip prefix-list nbr-filter seq 10 deny 10.1.0.2/32 + ip prefix-list nbr-filter seq 200 permit any + ! + ! Configure the neighbor filter prefix-list on interface eth0 + ! + interface eth0 + ip ospf neighbor-filter nbr-filter + ! + .. clicmd:: ip ospf area (A.B.C.D|(0-4294967295)) @@ -838,11 +888,11 @@ Graceful Restart Configure Graceful Restart (RFC 3623) helper support. - By default, helper support is disabled for all neighbours. + By default, helper support is disabled for all neighbors. This config enables/disables helper support on this router - for all neighbours. + for all neighbors. To enable/disable helper support for a specific - neighbour, the router-id (A.B.C.D) has to be specified. + neighbor, the router-id (A.B.C.D) has to be specified. .. clicmd:: graceful-restart helper strict-lsa-checking @@ -937,7 +987,7 @@ Showing Information User can get that information as JSON format when ``json`` keyword at the end of cli is presented. -.. clicmd:: show ip ospf graceful-restart helper [detail] [json] +.. clicmd:: show ip ospf [{(1-65535)|vrf <NAME|all>}] graceful-restart helper [detail] [json] Displays the Graceful Restart Helper details including helper config changes. @@ -1082,7 +1132,7 @@ Router Information respectively the PCE IP address, Autonomous System (AS) numbers of controlled domains, neighbor ASs, flag and scope. For flag and scope, please refer to :rfc`5088` for the BITPATTERN recognition. Multiple 'pce neighbor' - command could be specified in order to specify all PCE neighbours. + command could be specified in order to specify all PCE neighbors. .. clicmd:: show ip ospf router-info diff --git a/doc/user/ripngd.rst b/doc/user/ripngd.rst index f898bed..f55ee39 100644 --- a/doc/user/ripngd.rst +++ b/doc/user/ripngd.rst @@ -136,7 +136,7 @@ functionality. range is very large for compatibility with other protocols. For RIPng, valid metric values are from 1 to 16. -.. clicmd:: set tag (1-4294967295) +.. clicmd:: set tag <untagged|(1-4294967295)> Set a tag on the matched route. diff --git a/doc/user/routemap.rst b/doc/user/routemap.rst index 791762a..1d2f4e3 100644 --- a/doc/user/routemap.rst +++ b/doc/user/routemap.rst @@ -176,10 +176,9 @@ Route Map Match Command Matches the specified `metric`. -.. clicmd:: match tag TAG +.. clicmd:: match tag <untagged|(1-4294967295)> - Matches the specified tag value associated with the route. This tag value - can be in the range of (1-4294967295). + Matches the specified tag (or untagged) value associated with the route. .. clicmd:: match local-preference METRIC @@ -241,9 +240,10 @@ Route Map Set Command .. program:: configure -.. clicmd:: set tag TAG +.. clicmd:: set tag <untagged|(1-4294967295)> + + Set a tag on the matched route. - Set a tag on the matched route. This tag value can be from (1-4294967295). Additionally if you have compiled with the :option:`--enable-realms` configure option. Tag values from (1-255) are sent to the Linux kernel as a realm value. Then route policy can be applied. See the tc man page. As diff --git a/doc/user/rpki.rst b/doc/user/rpki.rst index 76910ee..98f9b10 100644 --- a/doc/user/rpki.rst +++ b/doc/user/rpki.rst @@ -131,19 +131,13 @@ The following commands are available for independent of a specific cache server. The default value is 600 seconds. -.. clicmd:: rpki cache (A.B.C.D|WORD) PORT [SSH_USERNAME] [SSH_PRIVKEY_PATH] [KNOWN_HOSTS_PATH] [source A.B.C.D] preference (1-255) +.. clicmd:: rpki cache tcp HOST PORT [source A.B.C.D] preference (1-255) + Add a TCP cache server to the socket. - Add a cache server to the socket. By default, the connection between router - and cache server is based on plain TCP. Protecting the connection between - router and cache server by SSH is optional. Deleting a socket removes the - associated cache server and terminates the existing connection. +.. clicmd:: rpki cache ssh HOST PORT SSH_USERNAME SSH_PRIVKEY_PATH [KNOWN_HOSTS_PATH] [source A.B.C.D] preference (1-255) - A.B.C.D|WORD - Address of the cache server. - - PORT - Port number to connect to the cache server + Add a SSH cache server to the socket. SSH_USERNAME SSH username to establish an SSH connection to the cache server. @@ -159,7 +153,6 @@ The following commands are available for independent of a specific cache server. source A.B.C.D Source address of the RPKI connection to access cache server. - .. _validating-bgp-updates: Validating BGP Updates @@ -215,15 +208,18 @@ Displaying RPKI Display RPKI configuration state including timers values. -.. clicmd:: show rpki prefix <A.B.C.D/M|X:X::X:X/M> [(1-4294967295)] [vrf NAME] [json] +.. clicmd:: show rpki prefix <A.B.C.D/M|X:X::X:X/M> [ASN] [vrf NAME] [json] Display validated prefixes received from the cache servers filtered - by the specified prefix. + by the specified prefix. The AS number space has been increased + to allow the choice of using AS 0 because RFC-7607 specifically + calls out the usage of 0 in a special case. .. clicmd:: show rpki as-number ASN [vrf NAME] [json] Display validated prefixes received from the cache servers filtered - by ASN. + by ASN. The usage of AS 0 is allowed because RFC-76067 specifically + calls out the usage of 0 in a special case. .. clicmd:: show rpki prefix-table [vrf NAME] [json] @@ -264,9 +260,9 @@ RPKI Configuration Example rpki polling_period 1000 rpki timeout 10 ! SSH Example: - rpki cache example.com 22 rtr-ssh ./ssh_key/id_rsa preference 1 + rpki cache ssh example.com 22 rtr-ssh ./ssh_key/id_rsa preference 1 ! TCP Example: - rpki cache rpki-validator.realmv6.org 8282 preference 2 + rpki cache tcp rpki-validator.realmv6.org 8282 preference 2 exit ! exit-vrf @@ -275,9 +271,9 @@ RPKI Configuration Example rpki polling_period 1000 rpki timeout 10 ! SSH Example: - rpki cache example.com source 198.51.100.223 22 rtr-ssh ./ssh_key/id_rsa preference 1 + rpki cache ssh example.com source 198.51.100.223 22 rtr-ssh ./ssh_key/id_rsa preference 1 ! TCP Example: - rpki cache rpki-validator.realmv6.org 8282 preference 2 + rpki cache tcp rpki-validator.realmv6.org 8282 preference 2 exit ! router bgp 65001 diff --git a/doc/user/zebra.rst b/doc/user/zebra.rst index 30b0204..37644dc 100644 --- a/doc/user/zebra.rst +++ b/doc/user/zebra.rst @@ -1356,6 +1356,9 @@ FPM Commands User FPM configurations: 1 User FPM disable requests: 0 +.. clicmd:: show fpm status [json] + + Show the FPM status. .. clicmd:: clear fpm counters @@ -1450,29 +1453,41 @@ To program the PBR rules as rte_flows you additionally need to configure zebra Terminal Mode Commands ============================ -.. clicmd:: show ip route +.. clicmd:: show [ip|ipv6] route Display current routes which zebra holds in its database. :: Router# show ip route - Codes: K - kernel route, C - connected, S - static, R - RIP, - B - BGP * - FIB route. - - K* 0.0.0.0/0 203.181.89.241 - S 0.0.0.0/0 203.181.89.1 - C* 127.0.0.0/8 lo - C* 203.181.89.240/28 eth0 + Codes: K - kernel route, C - connected, L - local, S - static, + R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, t - Table-Direct, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + K>* 0.0.0.0/0 [0/100] via 192.168.119.1, enp13s0, 00:30:22 + S> 4.5.6.7/32 [1/0] via 192.168.119.1 (recursive), weight 1, 00:30:22 + * via 192.168.119.1, enp13s0, weight 1, 00:30:22 + K>* 169.254.0.0/16 [0/1000] is directly connected, virbr2 linkdown, 00:30:22 + L>* 192.168.119.205/32 is directly connected, enp13s0, 00:30:22 -.. clicmd:: show ipv6 route .. clicmd:: show [ip|ipv6] route [PREFIX] [nexthop-group] Display detailed information about a route. If [nexthop-group] is included, it will display the nexthop group ID the route is using as well. +.. clicmd:: show [ip|ipv6] route summary + + Display summary information about routes received from each protocol. + This command displays the entries received from each route and as such + this total can be more than the actual number of FIB routes. Finally + due to the way that linux supports local and connected routes the FIB + total may not be exactly what is shown in the equivalent `ip route show` + command to see the state of the linux kernel. + .. clicmd:: show interface [NAME] [{vrf VRF|brief}] [json] .. clicmd:: show interface [NAME] [{vrf all|brief}] [json] diff --git a/docker/debian/Dockerfile b/docker/debian/Dockerfile index d136538..b317b05 100644 --- a/docker/debian/Dockerfile +++ b/docker/debian/Dockerfile @@ -24,5 +24,5 @@ RUN chown -R frr:frr /etc/frr /var/run/frr ENTRYPOINT ["/usr/bin/tini", "--"] # Default CMD starts watchfrr -COPY docker-start /usr/lib/frr/docker-start +COPY --chmod=0755 docker-start /usr/lib/frr/docker-start CMD ["/usr/lib/frr/docker-start"] diff --git a/docker/ubuntu-ci/Dockerfile b/docker/ubuntu-ci/Dockerfile index 5a49806..5c4649d 100644 --- a/docker/ubuntu-ci/Dockerfile +++ b/docker/ubuntu-ci/Dockerfile @@ -23,13 +23,17 @@ RUN apt update && apt upgrade -y && \ libreadline-dev \ libsnmp-dev \ libsqlite3-dev \ + lsb-release \ libtool \ + lcov \ make \ perl \ pkg-config \ python3-dev \ python3-sphinx \ + screen \ texinfo \ + tmux \ && \ # Protobuf build requirements apt-get install -y \ @@ -89,18 +93,14 @@ RUN groupadd -r -g 92 frr && \ echo 'frr ALL = NOPASSWD: ALL' | tee /etc/sudoers.d/frr && \ mkdir -p /home/frr && chown frr.frr /home/frr -USER frr:frr +# Install FRR built packages +RUN mkdir -p /etc/apt/keyrings && \ + curl -s -o /etc/apt/keyrings/frrouting.gpg https://deb.frrouting.org/frr/keys.gpg && \ + echo deb '[signed-by=/etc/apt/keyrings/frrouting.gpg]' https://deb.frrouting.org/frr \ + $(lsb_release -s -c) "frr-stable" > /etc/apt/sources.list.d/frr.list && \ + apt-get update && apt-get install -y librtr-dev libyang2-dev libyang2-tools -# build and install libyang2 -RUN cd && pwd && ls -al && \ - git clone https://github.com/CESNET/libyang.git && \ - cd libyang && \ - git checkout v2.1.128 && \ - mkdir build; cd build && \ - cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr \ - -DCMAKE_BUILD_TYPE:String="Release" .. && \ - make -j $(nproc) && \ - sudo make install +USER frr:frr COPY --chown=frr:frr . /home/frr/frr/ @@ -111,6 +111,10 @@ RUN cd ~/frr && \ --sysconfdir=/etc \ --localstatedir=/var \ --sbindir=/usr/lib/frr \ + --enable-gcov \ + --enable-dev-build \ + --enable-mgmtd-test-be-client \ + --enable-rpki \ --enable-sharpd \ --enable-multipath=64 \ --enable-user=frr \ diff --git a/docker/ubuntu-ci/docker-start b/docker/ubuntu-ci/docker-start index 9a45c72..c383ea8 100755 --- a/docker/ubuntu-ci/docker-start +++ b/docker/ubuntu-ci/docker-start @@ -1,8 +1,5 @@ #!/bin/bash - if [ $(uname -a | grep -ci Ubuntu) -ge 1 ]; then - #for topotests under ubuntu host - sudo modprobe mpls-router mpls-iptunnel - sudo /etc/init.d/openvswitch-switch start + sudo modprobe mpls-router mpls-iptunnel vrf fi while true ; do sleep 365d ; done diff --git a/docker/ubuntu22-ci/README.md b/docker/ubuntu22-ci/README.md index 73f4a10..617192e 100644 --- a/docker/ubuntu22-ci/README.md +++ b/docker/ubuntu22-ci/README.md @@ -8,10 +8,18 @@ This builds an ubuntu 22.04 container for dev / test docker build -t frr-ubuntu22:latest -f docker/ubuntu-ci/Dockerfile . ``` -# Running Full Topotest +# Run ``` -docker run --init -it --privileged --name frr-ubuntu22 -v /lib/modules:/lib/modules frr-ubuntu22:latest bash -c 'cd ~/frr/tests/topotests ; sudo pytest -nauto --dist=loadfile' +docker run -d --init --privileged --name frr-ubuntu22 --mount type=bind,source=/lib/modules,target=/lib/modules frr-ubuntu22:latest +``` + +# Running full topotest (container stops at end) + +``` +docker run --init -it --privileged --name frr-ubuntu22 \ + -v /lib/modules:/lib/modules frr-ubuntu22:latest \ + bash -c 'cd /home/frr/frr/tests/topotests; sudo pytest -nauto --dist=loadfile' ``` # Extract results from the above run into `run-results` dir and analyze @@ -20,10 +28,11 @@ docker run --init -it --privileged --name frr-ubuntu22 -v /lib/modules:/lib/modu tests/topotests/analyze.py -C frr-ubuntu22 -Ar run-results ``` -# Running +# Extract coverage from a stopped container into host FRR source tree ``` -docker run -d --init --privileged --name frr-ubuntu22 --mount type=bind,source=/lib/modules,target=/lib/modules frr-ubuntu22:latest +docker export frr-ubuntu22 | tar --strip=3 --wildcards -vx '*.gc??' +lcov -b $(pwd) --capture --directory . --output-file=coverage.info ``` # make check @@ -38,10 +47,10 @@ docker exec frr-ubuntu22 bash -c 'cd ~/frr ; make check' docker exec -it frr-ubuntu22 bash ``` -# topotest -- when Host O/S is Ubuntu only +# Run a specific topotest ``` -docker exec frr-ubuntu22 bash -c 'cd ~/frr/tests/topotests/ospf_topo1 ; sudo pytest test_ospf_topo1.py' +docker exec frr-ubuntu22 bash -c 'cd ~/frr/tests/topotests ; sudo pytest ospf_topo1/test_ospf_topo1.py' ``` # stop & remove container |