diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/developer/building-frr-for-openwrt.rst | 4 | ||||
| -rw-r--r-- | doc/developer/fuzzing.rst | 164 | ||||
| -rw-r--r-- | doc/developer/index.rst | 1 | ||||
| -rw-r--r-- | doc/user/basic.rst | 2 | ||||
| -rw-r--r-- | doc/user/bgp.rst | 121 | ||||
| -rw-r--r-- | doc/user/ospf6d.rst | 7 | ||||
| -rw-r--r-- | doc/user/vrrp.rst | 2 | ||||
| -rw-r--r-- | doc/user/zebra.rst | 13 |
8 files changed, 294 insertions, 20 deletions
diff --git a/doc/developer/building-frr-for-openwrt.rst b/doc/developer/building-frr-for-openwrt.rst index 9bd1296dad..47cf2cbd43 100644 --- a/doc/developer/building-frr-for-openwrt.rst +++ b/doc/developer/building-frr-for-openwrt.rst @@ -51,7 +51,7 @@ to work and it may be needed to run a ``make`` for the entire build environment. Add ``V=s`` to get more debugging output. More information about OpenWrt buildsystem can be found `here -<https://openwrt.org/docs/guide-developer/build-system/use-buildsystem>`_. +<https://openwrt.org/docs/guide-developer/build-system/use-buildsystem>`__. Work with sources ----------------- @@ -59,7 +59,7 @@ Work with sources To update to a newer version, or change other options, you need to edit the ``feeds/packages/frr/Makefile``. More information about working with patches in OpenWrt buildsystem can be found `here -<https://openwrt.org/docs/guide-developer/build-system/use-patches-with-buildsystem>`_. +<https://openwrt.org/docs/guide-developer/build-system/use-patches-with-buildsystem>`__. Usage ----- diff --git a/doc/developer/fuzzing.rst b/doc/developer/fuzzing.rst new file mode 100644 index 0000000000..8a3318745e --- /dev/null +++ b/doc/developer/fuzzing.rst @@ -0,0 +1,164 @@ +.. _fuzzing: + +Fuzzing +======= + +This page describes the fuzzing targets and supported fuzzers available in FRR +and how to use them. Familiarity with fuzzing techniques and tools is assumed. + +Overview +-------- + +It is well known that networked applications tend to be difficult to fuzz on +their network-facing attack surfaces. Approaches involving actual network +transmission tend to be slow and are subject to intermediate devices and +networking stacks which tend to drop fuzzed packets, especially if the fuzzing +surface covers IP itself. Some time was spent on fuzzing FRR this way with some +mediocre results but attention quickly turned towards skipping the actual +networking and instead adding fuzzing targets directly in the packet processing +code for use by more traditional in- and out-of-process fuzzers. Results from +this approach have been very fruitful. + +The patches to add fuzzing targets are kept in a separate git branch. Typically +it is better to keep them in the main branch so they are kept up to date and do +not need to be constantly synchronized with the main codebase. Unfortunately, +changes to FRR to support fuzzing necessarily extend far beyond the +entrypoints. Checksums must be disarmed, interactions with the kernel must be +skipped, sockets and files must be avoided, desired under/overflows must be +marked, etc. There are the usual ``LD_PRELOAD`` libraries to emulate these +things (preeny et al) but FRR is a very kernel-reliant program and these +libraries tend to create annoying problems when used with FRR for whatever +reason. Keeping this code in the main codebase is cluttering, difficult to work +with / around, and runs the risk of accidentally introducing bugs even if +``#ifdef``'d out. Consequently it's in a separate branch that is rebased on +``master`` from time to time. + + +Code +---- + +The git branch with fuzzing targets is located here: + +https://github.com/FRRouting/frr/tree/fuzz + +To build libFuzzer targets, pass ``--enable-libfuzzer`` to ``configure``. +To build AFL targets, compile with ``afl-clang`` as usual. + +Fuzzing with sanitizers is strongly recommended, especially ASAN, which you can +enable by passing ``--enable-address-sanitizer`` to ``configure``. + +Suggested UBSAN flags: ``-fsanitize-recover=unsigned-integer-overflow,implicit-conversion -fsanitize=unsigned-integer-overflow,implicit-conversion,nullability-arg,nullability-assign,nullability-return`` +Recommended cflags: ``-Wno-all -g3 -O3 -funroll-loops`` + +Design +------ + +All fuzzing targets have support for libFuzzer and AFL. This is done by writing +the target as a libFuzzer entrypoint (``LLVMFuzzerTestOneInput()``) and calling +it from the AFL entrypoint in ``main()``. New targets should use this rule. + +When adding AFL entrypoints, it's a good idea to use AFL persistent mode for +better performance. Grep ``bgpd/bgp_main.c`` for ``__AFL_INIT()`` for an +example of how to do this in FRR. Typically it involves moving all internal +daemon setup into a setup function. Then this setup function is called exactly +once for the lifetime of the process. In ``LLVMFuzzerTestOneInput()`` this +means you need to call it at the start of the function protected by a static +boolean that is set to true, since that function is your entrypoint. You also +need to call it prior to ``__AFL_INIT()`` in ``main()`` because ``main()`` is +your entrypoint in the AFL case. + +Adding support to daemons +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This section describes how to add entrypoints to daemons that do not have any +yet. + +Because libFuzzer has its own ``main()`` function, when adding fuzzing support +to a daemon that doesn't have any targets already, ``main()`` needs to be +``#ifdef``'d out like so: + +.. code:: c + + #ifndef FUZZING_LIBFUZZER + + int main(int argc, char **argv) + { + ... + } + + #endif /* FUZZING_LIBFUZZER */ + + +The ``FUZZING_LIBFUZZER`` macro is set by ``--enable-libfuzzer``. + +Because libFuzzer can only be linked into daemons that have +``LLVMFuzzerTestOneInput()`` implemented, we can't pass ``-fsanitize=fuzzer`` +to all daemons in ``AM_CFLAGS``. It needs to go into a variable specific to +each daemon. Since it can be thought of as a kind of sanitizer, for daemons +that have libFuzzer support there are now individual flags variables for those +daemons named ``DAEMON_SAN_FLAGS`` (e.g. ``BGPD_SAN_FLAGS``, +``ZEBRA_SAN_FLAGS``). This variable has the contents of the generic +``SAN_FLAGS`` plus any fuzzing-related flags. It is used in daemons' +``subdir.am`` in place of ``SAN_FLAGS``. Daemons that don't support libFuzzer +still use ``SAN_FLAGS``. If you want to add fuzzing support to a daemon you +need to do this flag variable conversion; look at ``configure.ac`` for +examples, it is fairly straightforward. Remember to update ``subdir.am`` to use +the new variable. + +Do note that when fuzzing is enabled, ``SAN_FLAGS`` gains +``-fsanitize=fuzzer-no-link``; the result is that all daemons are instrumented +for fuzzing but only the ones with ``LLVMFuzzerTestOneInput()`` actually get +linked with libFuzzer. + + +Targets +------- + +A given daemon can have lots of different paths that are interesting to fuzz. +There's not really a great way to handle this, most fuzzers assume the program +has one entrypoint. The approach taken in FRR for multiple entrypoints is to +control which path is taken within ``LLVMFuzzerTestOneInput()`` using +``#ifdef`` and passing whatever controlling macro definition you want. Take a +look at that function for the daemon you're interested in fuzzing, pick the +target, add ``#define MY_TARGET 1`` somewhere before the ``#ifdef`` switch, +recompile. + +.. list-table:: Fuzzing Targets + + * - Daemon + - Target + - Fuzzers + * - bgpd + - packet parser + - libfuzzer, afl + * - ospfd + - packet parser + - libfuzzer, afl + * - pimd + - packet parser + - libfuzzer, afl + * - vrrpd + - packet parser + - libfuzzer, afl + * - vrrpd + - zapi parser + - libfuzzer, afl + * - zebra + - netlink + - libfuzzer, afl + * - zebra + - zserv / zapi + - libfuzzer, afl + + +Fuzzer Notes +------------ + +Some interesting seed corpuses for various daemons are available `here +<https://github.com/qlyoung/frr-fuzz/tree/master/samples>`_. + +For libFuzzer, you need to pass ``-rss_limit_mb=0`` if you are fuzzing with +ASAN enabled, as you should. + +For AFL, afl++ is strongly recommended; afl proper isn't really maintained +anymore. diff --git a/doc/developer/index.rst b/doc/developer/index.rst index 1ba0f31c8a..5a7da806ff 100644 --- a/doc/developer/index.rst +++ b/doc/developer/index.rst @@ -9,6 +9,7 @@ FRRouting Developer's Guide packaging process-architecture library + fuzzing tracing testing bgpd diff --git a/doc/user/basic.rst b/doc/user/basic.rst index 0bdcccaf74..7a450bec53 100644 --- a/doc/user/basic.rst +++ b/doc/user/basic.rst @@ -26,7 +26,7 @@ forms the initial command set for a routing beast as it is starting. Config files are generally found in |INSTALL_PREFIX_ETC|. Config Methods -^^^^^^^^^^^^^^ +-------------- There are two ways of configuring FRR. diff --git a/doc/user/bgp.rst b/doc/user/bgp.rst index 3572734ba9..0a562e1edf 100644 --- a/doc/user/bgp.rst +++ b/doc/user/bgp.rst @@ -962,6 +962,56 @@ Networks traditional did not check for existence. For versions 7.4 and beyond both traditional and datacenter the network must exist. +.. _bgp-ipv6-support: + +IPv6 Support +------------ + +.. index:: [no] neighbor A.B.C.D activate +.. clicmd:: [no] neighbor A.B.C.D activate + + This configuration modifies whether to enable an address family for a + specific neighbor. By default only the IPv4 unicast address family is + enabled. + + .. code-block:: frr + + router bgp 1 + address-family ipv6 unicast + neighbor 2001:0DB8::1 activate + network 2001:0DB8:5009::/64 + exit-address-family + + This configuration example says that network 2001:0DB8:5009::/64 will be + announced and enables the neighbor 2001:0DB8::1 to receive this announcement. + +.. index:: [no] bgp default ipv4-unicast +.. clicmd:: [no] bgp default ipv4-unicast + + By default, only the IPv4 unicast address family is announced to all + neighbors. Using the 'no bgp default ipv4-unicast' configuration overrides + this default so that all address families need to be enabled explicitly. + + .. code-block:: frr + + router bgp 1 + no bgp default ipv4-unicast + neighbor 10.10.10.1 remote-as 2 + neighbor 2001:0DB8::1 remote-as 3 + address-family ipv4 unicast + neighbor 10.10.10.1 activate + network 192.168.1.0/24 + exit-address-family + address-family ipv6 unicast + neighbor 2001:0DB8::1 activate + network 2001:0DB8:5009::/64 + exit-address-family + + This configuration demonstrates how the 'no bgp default ipv4-unicast' might + be used in a setup with two upstreams where each of the upstreams should only + receive either IPv4 or IPv6 annocuments. + + .. _bgp-route-aggregation: Route Aggregation @@ -1303,10 +1353,10 @@ Configuring Peers Optionally you can specify a shutdown message `MSG`. - Also, you can specify optionally _rtt_ in milliseconds to automatically + Also, you can specify optionally ``rtt`` in milliseconds to automatically shutdown the peer if round-trip-time becomes higher than defined. - Additional _count_ parameter is the number of keepalive messages to count + Additional ``count`` parameter is the number of keepalive messages to count before shutdown the peer if round-trip-time becomes higher than defined. .. index:: [no] neighbor PEER disable-connected-check @@ -1420,7 +1470,7 @@ Configuring Peers granular and offers much smarter matching criterion than number of received prefixes, making it more suited to implementing policy. - If _force_ is set, then ALL prefixes are counted for maximum instead of + If ``force`` is set, then ALL prefixes are counted for maximum instead of accepted only. This is useful for cases where an inbound filter is applied, but you want maximum-prefix to act on ALL (including filtered) prefixes. This option requires `soft-reconfiguration inbound` to be enabled for the peer. @@ -3122,16 +3172,16 @@ displays IPv6 routing table. Total number of prefixes 1 - If _wide_ option is specified, then the prefix table's width is increased + If ``wide`` option is specified, then the prefix table's width is increased to fully display the prefix and the nexthop. This is especially handy dealing with IPv6 prefixes and if :clicmd:`[no] bgp default show-nexthop-hostname` is enabled. - If _all_ option is specified, _ip_ keyword is ignored, show bgp all and + If ``all`` option is specified, ``ip`` keyword is ignored, show bgp all and show ip bgp all commands display routes for all AFIs and SAFIs. - If _json_ option is specified, output is displayed in JSON format. + If ``json`` option is specified, output is displayed in JSON format. Some other commands provide additional options for filtering the output. @@ -3225,18 +3275,18 @@ structure is extended with :clicmd:`show bgp [afi] [safi]`. from neighbor or filtered routes received from neighbor based on the option specified. - If _wide_ option is specified, then the prefix table's width is increased + If ``wide`` option is specified, then the prefix table's width is increased to fully display the prefix and the nexthop. This is especially handy dealing with IPv6 prefixes and if :clicmd:`[no] bgp default show-nexthop-hostname` is enabled. - If _all_ option is specified, _ip_ keyword is ignored and, + If ``all`` option is specified, ``ip`` keyword is ignored and, routes displayed for all AFIs and SAFIs. - if afi is specified, with _all_ option, routes will be displayed for + if afi is specified, with ``all`` option, routes will be displayed for each SAFI in the selcted AFI - If _json_ option is specified, output is displayed in JSON format. + If ``json`` option is specified, output is displayed in JSON format. .. _bgp-display-routes-by-community: @@ -3270,18 +3320,18 @@ attribute. match the specified community list. When `exact-match` is specified, it displays only routes that have an exact match. - If _wide_ option is specified, then the prefix table's width is increased + If ``wide`` option is specified, then the prefix table's width is increased to fully display the prefix and the nexthop. This is especially handy dealing with IPv6 prefixes and if :clicmd:`[no] bgp default show-nexthop-hostname` is enabled. - If _all_ option is specified, _ip_ keyword is ignored and, + If ``all`` option is specified, ``ip`` keyword is ignored and, routes displayed for all AFIs and SAFIs. - if afi is specified, with _all_ option, routes will be displayed for + if afi is specified, with ``all`` option, routes will be displayed for each SAFI in the selcted AFI - If _json_ option is specified, output is displayed in JSON format. + If ``json`` option is specified, output is displayed in JSON format. .. _bgp-display-routes-by-lcommunity: @@ -3412,6 +3462,49 @@ starting the daemon and the configuration gets saved, the option will persist unless removed from the configuration with the negating command prior to the configuration write operation. +.. _bgp-suppress-fib: + +Suppressing routes not installed in FIB +======================================= + +The FRR implementation of BGP advertises prefixes learnt from a peer to other +peers even if the routes do not get installed in the FIB. There can be +scenarios where the hardware tables in some of the routers (along the path from +the source to destination) is full which will result in all routes not getting +installed in the FIB. If these routes are advertised to the downstream routers +then traffic will start flowing and will be dropped at the intermediate router. + +The solution is to provide a configurable option to check for the FIB install +status of the prefixes and advertise to peers if the prefixes are successfully +installed in the FIB. The advertisement of the prefixes are suppressed if it is +not installed in FIB. + +The following conditions apply will apply when checking for route installation +status in FIB: + +1. The advertisement or suppression of routes based on FIB install status + applies only for newly learnt routes from peer (routes which are not in + BGP local RIB). +2. If the route received from peer already exists in BGP local RIB and route + attributes have changed (best path changed), the old path is deleted and + new path is installed in FIB. The FIB install status will not have any + effect. Therefore only when the route is received first time the checks + apply. +3. The feature will not apply for routes learnt through other means like + redistribution to bgp from other protocols. This is applicable only to + peer learnt routes. +4. If a route is installed in FIB and then gets deleted from the dataplane, + then routes will not be withdrawn from peers. This will be considered as + dataplane issue. +5. The feature will slightly increase the time required to advertise the routes + to peers since the route install status needs to be received from the FIB +6. If routes are received by the peer before the configuration is applied, then + the bgp sessions need to be reset for the configuration to take effect. +7. If the route which is already installed in dataplane is removed for some + reason, sending withdraw message to peers is not currently supported. + +.. index:: [no] bgp suppress-fib-pending +.. clicmd:: [no] bgp suppress-fib-pending .. _routing-policy: diff --git a/doc/user/ospf6d.rst b/doc/user/ospf6d.rst index 6295ba9293..dd53d8f8b4 100644 --- a/doc/user/ospf6d.rst +++ b/doc/user/ospf6d.rst @@ -179,10 +179,11 @@ Showing OSPF6 information To see OSPF interface configuration like costs. -.. index:: show ipv6 ospf6 neighbor -.. clicmd:: show ipv6 ospf6 neighbor +.. index:: show ipv6 ospf6 neighbor [json] +.. clicmd:: show ipv6 ospf6 neighbor [json] - Shows state and chosen (Backup) DR of neighbor. + Shows state and chosen (Backup) DR of neighbor. JSON output can be + obtained by appending 'json' at the end. .. index:: show ipv6 ospf6 request-list A.B.C.D .. clicmd:: show ipv6 ospf6 request-list A.B.C.D diff --git a/doc/user/vrrp.rst b/doc/user/vrrp.rst index 8ab050e9a0..cb70da3f3b 100644 --- a/doc/user/vrrp.rst +++ b/doc/user/vrrp.rst @@ -503,6 +503,7 @@ The following configuration is then generated for you: vrrp 5 ip 10.0.2.16 vrrp 5 ipv6 2001:db8::370:7334 + VRRP is automatically activated. Global defaults, if set, are applied. You can then edit this configuration with **vtysh** as needed, and commit it by @@ -516,6 +517,7 @@ My virtual routers are not seeing each others' advertisements ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Check: + - Is your kernel at least 5.1? - Did you set the macvlan devices to ``bridge`` mode? - If using IPv4 virtual addresses, does the parent of the macvlan devices have diff --git a/doc/user/zebra.rst b/doc/user/zebra.rst index 624e3cfe1a..5c7f4ac773 100644 --- a/doc/user/zebra.rst +++ b/doc/user/zebra.rst @@ -72,6 +72,19 @@ Besides the common invocation options (:ref:`common-invocation-options`), the option and we will use Route Replace Semantics instead of delete than add. +.. option:: --asic-offload [notify_on_offload|notify_on_ack] + + The linux kernel has the ability to use asic-offload ( see switchdev + development ). When the operator knows that FRR will be working in + this way, allow them to specify this with FRR. At this point this + code only supports asynchronous notification of the offload state. + In other words the initial ACK received for linux kernel installation + does not give zebra any data about what the state of the offload + is. This option takes the optional paramegers notify_on_offload + or notify_on_ack. This signals to zebra to notify upper level + protocols about route installation/update on ack received from + the linux kernel or from offload notification. + .. _interface-commands: Configuration Addresses behaviour |