diff options
Diffstat (limited to 'doc/developer')
| -rw-r--r-- | doc/developer/building-docker.rst | 101 | ||||
| -rw-r--r-- | doc/developer/building-frr-for-ubuntu2004.rst | 162 | ||||
| -rw-r--r-- | doc/developer/building.rst | 2 | ||||
| -rw-r--r-- | doc/developer/lists.rst | 37 | ||||
| -rw-r--r-- | doc/developer/lua.rst | 2 | ||||
| -rw-r--r-- | doc/developer/subdir.am | 1 | ||||
| -rw-r--r-- | doc/developer/topotests-jsontopo.rst | 6 | ||||
| -rw-r--r-- | doc/developer/topotests.rst | 6 | ||||
| -rw-r--r-- | doc/developer/workflow.rst | 54 | ||||
| -rw-r--r-- | doc/developer/zebra.rst | 12 |
10 files changed, 359 insertions, 24 deletions
diff --git a/doc/developer/building-docker.rst b/doc/developer/building-docker.rst new file mode 100644 index 0000000000..852a295fd0 --- /dev/null +++ b/doc/developer/building-docker.rst @@ -0,0 +1,101 @@ +Docker +====== + +This page covers how to build FRR Docker images. + +Images +"""""" +FRR has Docker build infrastructure to produce Docker images containing +source-built FRR on the following base platforms: + +* Alpine +* Centos 7 +* Centos 8 + +The following platform images may also be built, but these simply install a +binary package from an existing repository and do not perform source builds: + +* Debian 10 + +Some of these are available on `DockerHub +<https://hub.docker.com/repository/docker/frrouting/frr/tags?page=1>`_. + +There is no guarantee on what is and is not available from DockerHub at time of +writing. + +Scripts +""""""" + +Some platforms contain an included build script that may be run from the host. +This will set appropriate packaging environment variables and clean up +intermediate build images. + +These scripts serve another purpose. They allow building platform packages +without needing the platform. For example, the Centos 8 docker image can also +be leveraged to build Centos 8 RPMs that can then be used separately from +Docker. + +If you are only interested in the Docker images and don't want the cleanup +functionality of the scripts you can ignore them and perform a normal Docker +build. If you want to build multi-arch docker images this is required as the +scripts do not support using Buildkit for multi-arch builds. + +Building Alpine Image +--------------------- + +Script:: + + ./docker/alpine/build.sh + +No script:: + + docker build -f docker/alpine/Dockerfile . + +No script, multi-arch (ex. amd64, arm64, armv7):: + + docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -f docker/alpine/Dockerfile -t frr:latest . + + +Building Debian Image +--------------------- + +:: + + cd docker/debian + docker build . + +Multi-arch (ex. amd64, arm64, armv7):: + + cd docker/debian + docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t frr-debian:latest . + +Building Centos 7 Image +----------------------- + +Script:: + + ./docker/centos-7/build.sh + +No script:: + + docker build -f docker/centos-7/Dockerfile . + +No script, multi-arch (ex. amd64, arm64):: + + docker buildx build --platform linux/amd64,linux/arm64 -f docker/centos-7/Dockerfile -t frr-centos7:latest . + + +Building Centos 8 Image +----------------------- + +Script:: + + ./docker/centos-8/build.sh + +No script:: + + docker build -f docker/centos-8/Dockerfile . + +No script, multi-arch (ex. amd64, arm64):: + + docker buildx build --platform linux/amd64,linux/arm64 -f docker/centos-8/Dockerfile -t frr-centos8:latest . diff --git a/doc/developer/building-frr-for-ubuntu2004.rst b/doc/developer/building-frr-for-ubuntu2004.rst new file mode 100644 index 0000000000..92ebb3d803 --- /dev/null +++ b/doc/developer/building-frr-for-ubuntu2004.rst @@ -0,0 +1,162 @@ +Ubuntu 20.04 LTS +================ + +This document describes installation from source. If you want to build a +``deb``, see :ref:`packaging-debian`. + +Installing Dependencies +----------------------- + +.. code-block:: console + + sudo apt update + sudo apt-get install \ + git autoconf automake libtool make libreadline-dev texinfo \ + pkg-config libpam0g-dev libjson-c-dev bison flex python3-pytest \ + libc-ares-dev python3-dev libsystemd-dev python-ipaddress python3-sphinx \ + install-info build-essential libsystemd-dev libsnmp-dev perl \ + libcap-dev python2 + +Note that Ubuntu 20 no longer installs python 2.x, so it must be +installed explicitly. Ensure that your system has a symlink named +``/usr/bin/python`` pointing at ``/usr/bin/python3``. + +In addition, ``pip`` for python2 must be installed if you wish to run +the FRR topotests. That version of ``pip`` is not available from the +ubuntu apt repositories; in order to install it: + +.. code-block:: shell + + curl https://bootstrap.pypa.io/get-pip.py --output get-pip.py + sudo ./get-pip.py + + # And verify the installation + pip2 --version + +.. include:: building-libyang.rst + +Protobuf +^^^^^^^^ + +.. code-block:: console + + sudo apt-get install protobuf-c-compiler libprotobuf-c-dev + +ZeroMQ +^^^^^^ + +.. code-block:: console + + sudo apt-get install libzmq5 libzmq3-dev + +Building & Installing FRR +------------------------- + +Add FRR user and groups +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: console + + sudo groupadd -r -g 92 frr + sudo groupadd -r -g 85 frrvty + sudo adduser --system --ingroup frr --home /var/run/frr/ \ + --gecos "FRR suite" --shell /sbin/nologin frr + sudo usermod -a -G frrvty frr + +Compile +^^^^^^^ + +.. include:: include-compile.rst + +Install FRR configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: console + + sudo install -m 775 -o frr -g frr -d /var/log/frr + sudo install -m 775 -o frr -g frrvty -d /etc/frr + sudo install -m 640 -o frr -g frrvty tools/etc/frr/vtysh.conf /etc/frr/vtysh.conf + sudo install -m 640 -o frr -g frr tools/etc/frr/frr.conf /etc/frr/frr.conf + sudo install -m 640 -o frr -g frr tools/etc/frr/daemons.conf /etc/frr/daemons.conf + sudo install -m 640 -o frr -g frr tools/etc/frr/daemons /etc/frr/daemons + +Tweak sysctls +^^^^^^^^^^^^^ + +Some sysctls need to be changed in order to enable IPv4/IPv6 forwarding and +MPLS (if supported by your platform). If your platform does not support MPLS, +skip the MPLS related configuration in this section. + +Edit :file:`/etc/sysctl.conf` and uncomment the following values (ignore the +other settings): + +:: + + # Uncomment the next line to enable packet forwarding for IPv4 + net.ipv4.ip_forward=1 + + # Uncomment the next line to enable packet forwarding for IPv6 + # Enabling this option disables Stateless Address Autoconfiguration + # based on Router Advertisements for this host + net.ipv6.conf.all.forwarding=1 + +Reboot or use ``sysctl -p`` to apply the same config to the running system. + +Add MPLS kernel modules +""""""""""""""""""""""" + +Ubuntu 20.04 ships with kernel 5.4; MPLS modules are present by default. To +enable, add the following lines to :file:`/etc/modules-load.d/modules.conf`: + +:: + + # Load MPLS Kernel Modules + mpls_router + mpls_iptunnel + + +And load the kernel modules on the running system: + +.. code-block:: console + + sudo modprobe mpls-router mpls-iptunnel + +If the above command returns an error, you may need to install the appropriate +or latest linux-modules-extra-<kernel-version>-generic package. For example +``apt-get install linux-modules-extra-`uname -r`-generic`` + +Enable MPLS Forwarding +"""""""""""""""""""""" + +Edit :file:`/etc/sysctl.conf` and the following lines. Make sure to add a line +equal to :file:`net.mpls.conf.eth0.input` for each interface used with MPLS. + +:: + + # Enable MPLS Label processing on all interfaces + net.mpls.conf.eth0.input=1 + net.mpls.conf.eth1.input=1 + net.mpls.conf.eth2.input=1 + net.mpls.platform_labels=100000 + +Install service files +^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: console + + sudo install -m 644 tools/frr.service /etc/systemd/system/frr.service + sudo systemctl enable frr + +Enable daemons +^^^^^^^^^^^^^^ + +Open :file:`/etc/frr/daemons` with your text editor of choice. Look for the +section with ``watchfrr_enable=...`` and ``zebra=...`` etc. Enable the daemons +as required by changing the value to ``yes``. + +Start FRR +^^^^^^^^^ + +.. code-block:: shell + + systemctl start frr diff --git a/doc/developer/building.rst b/doc/developer/building.rst index ef55954ac2..fbe1f24d35 100644 --- a/doc/developer/building.rst +++ b/doc/developer/building.rst @@ -26,4 +26,6 @@ Building FRR building-frr-for-ubuntu1404 building-frr-for-ubuntu1604 building-frr-for-ubuntu1804 + building-frr-for-ubuntu2004 building-frr-for-archlinux + building-docker diff --git a/doc/developer/lists.rst b/doc/developer/lists.rst index 853c65ddf3..9355141aa4 100644 --- a/doc/developer/lists.rst +++ b/doc/developer/lists.rst @@ -105,7 +105,8 @@ Functions provided: +====================================+======+======+======+=========+============+ | _init, _fini | yes | yes | yes | yes | yes | +------------------------------------+------+------+------+---------+------------+ -| _first, _next, _next_safe | yes | yes | yes | yes | yes | +| _first, _next, _next_safe, | yes | yes | yes | yes | yes | +| _const_first, _const_next | | | | | | +------------------------------------+------+------+------+---------+------------+ | _add_head, _add_tail, _add_after | yes | -- | -- | -- | -- | +------------------------------------+------+------+------+---------+------------+ @@ -113,9 +114,10 @@ Functions provided: +------------------------------------+------+------+------+---------+------------+ | _del, _pop | yes | yes | yes | yes | yes | +------------------------------------+------+------+------+---------+------------+ -| _find | -- | -- | yes | yes | -- | +| _find, _const_find | -- | -- | yes | yes | -- | +------------------------------------+------+------+------+---------+------------+ -| _find_lt, _find_gteq | -- | -- | -- | yes | yes | +| _find_lt, _find_gteq, | -- | -- | -- | yes | yes | +| _const_find_lt, _const_find_gteq | | | | | | +------------------------------------+------+------+------+---------+------------+ | use with frr_each() macros | yes | yes | yes | yes | yes | +------------------------------------+------+------+------+---------+------------+ @@ -226,6 +228,10 @@ The following iteration macros work across all data structures: resume iteration after breaking out of the loop by keeping the ``from`` value persistent and reusing it for the next loop. +To iterate over ``const`` pointers, add ``_const`` to the name of the +datastructure (``Z`` above), e.g. ``frr_each (mylist, head, item)`` becomes +``frr_each (mylist_const, head, item)``. + Common API ---------- @@ -248,7 +254,7 @@ The following documentation assumes that a list has been defined using This function may ``assert()`` if the list is not empty. -.. c:function:: size_t Z_count(struct Z_head *) +.. c:function:: size_t Z_count(const struct Z_head *) Returns the number of items in a structure. All structures store a counter in their `Z_head` so that calling this function completes @@ -260,6 +266,7 @@ The following documentation assumes that a list has been defined using outdated by the time this function returns and can therefore only be used as an estimate. +.. c:function:: const itemtype *Z_const_first(const struct Z_head *) .. c:function:: itemtype *Z_first(struct Z_head *) Returns the first item in the structure, or ``NULL`` if the structure is @@ -288,6 +295,7 @@ The following documentation assumes that a list has been defined using affected by the "modification while iterating" problem. To remove all items from a hash table, use the loop demonstrated above. +.. c:function:: const itemtype *Z_next(const struct Z_head *, const itemtype *prev) .. c:function:: itemtype *Z_next(struct Z_head *, itemtype *prev) Return the item that follows after ``prev``, or ``NULL`` if ``prev`` is @@ -421,6 +429,7 @@ sorted lists can be searched for a value. For ``_NONUNIQ`` lists, this function always returns NULL since ``item`` can always be successfully added to the list. +.. c:function:: const itemtype *Z_find(const struct Z_head *, const itemtype *ref) .. c:function:: itemtype *Z_find(struct Z_head *, const itemtype *ref) Search the list for an item that compares equal to ``ref``. If no equal @@ -442,11 +451,13 @@ sorted lists can be searched for a value. containing non-unique items, more than one item may compare as equal to the item that is searched for. +.. c:function:: const itemtype *Z_find_gteq(const struct Z_head *, const itemtype *ref) .. c:function:: itemtype *Z_find_gteq(struct Z_head *, const itemtype *ref) Search the list for an item that compares greater or equal to ``ref``. See :c:func:`Z_find()` above. +.. c:function:: const itemtype *Z_find_lt(const struct Z_head *, const itemtype *ref) .. c:function:: itemtype *Z_find_lt(struct Z_head *, const itemtype *ref) Search the list for an item that compares less than @@ -616,21 +627,9 @@ Head removal (pop) and deallocation: FAQ --- -Why is the list head not ``const`` in the list APIs? - The semantics that a ``const`` list head would imply are not obvious. It - could mean any of the following: - - * the list just shouldn't be allocated/deallocated, but may be modified. - This doesn't actually work since the list head needs to be modified for - inserting or deleting items. - - * the list shouldn't be modified, but items can. This may make sense for - iterating, but it's not exactly consistent - an item might be on more - than one list, does it apply to all of them? If not, which one? - - * neither the list nor the items should be modified. This is consistent, - but hard to do without creating a ``const`` copy of every single list - function. Ease of use trumps this. +What are the semantics of ``const`` in the list APIs? + ``const`` pointers to list heads and/or items are interpreted to mean that + both the list itself as well as the data items are read-only. Why is there no "is this item on a/the list" test? It's slow for several of the data structures, and the work of adding it diff --git a/doc/developer/lua.rst b/doc/developer/lua.rst index 23eb35fc58..3315c31ad7 100644 --- a/doc/developer/lua.rst +++ b/doc/developer/lua.rst @@ -53,7 +53,7 @@ follow these steps: zlog_debug(string.format("afi: %d: %s %d ifdx: %d aspath: %s localpref: %d", prefix.family, prefix.route, nexthop.metric, nexthop.ifindex, nexthop.aspath, nexthop.localpref)) - + nexthop.metric = 33 nexthop.localpref = 13 return 3 diff --git a/doc/developer/subdir.am b/doc/developer/subdir.am index 538a290c34..6dab244a03 100644 --- a/doc/developer/subdir.am +++ b/doc/developer/subdir.am @@ -22,6 +22,7 @@ dev_RSTFILES = \ doc/developer/building-frr-for-ubuntu1404.rst \ doc/developer/building-frr-for-ubuntu1604.rst \ doc/developer/building-frr-for-ubuntu1804.rst \ + doc/developer/building-frr-for-ubuntu2004.rst \ doc/developer/building-libyang.rst \ doc/developer/building.rst \ doc/developer/cli.rst \ diff --git a/doc/developer/topotests-jsontopo.rst b/doc/developer/topotests-jsontopo.rst index bbae80f11d..1c77cd7be1 100644 --- a/doc/developer/topotests-jsontopo.rst +++ b/doc/developer/topotests-jsontopo.rst @@ -55,8 +55,14 @@ This is the recommended test writing routine: * Create topology from json * Create configuration from json * Write the tests +* Format the new code using `black <https://github.com/psf/black>`_ * Create a Pull Request +.. Note:: + + BGP tests MUST use generous convergence timeouts - you must ensure + that any test involving BGP uses a convergence timeout of at least + 130 seconds. File Hierarchy ^^^^^^^^^^^^^^ diff --git a/doc/developer/topotests.rst b/doc/developer/topotests.rst index 7e627781e0..b32f2bbf49 100644 --- a/doc/developer/topotests.rst +++ b/doc/developer/topotests.rst @@ -363,6 +363,12 @@ This is the recommended test writing routine: - Format the new code using `black <https://github.com/psf/black>`_ - Create a Pull Request +.. Note:: + + BGP tests MUST use generous convergence timeouts - you must ensure + that any test involving BGP uses a convergence timeout of at least + 130 seconds. + Topotest File Hierarchy """"""""""""""""""""""" diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index 6885a41e0f..f345464a35 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -191,6 +191,21 @@ review can be made and the branch merged into master. If a development branch is becomes un-maintained or not being actively worked on after three months then the Maintainers can decide to remove the branch. +Debian Branches +--------------- + +The Debian project contains "official" packages for FRR. While FRR +Maintainers may participate in creating these, it is entirely the Debian +project's decision what to ship and how to work on this. + +As a courtesy and for FRR's benefit, this packaging work is currently visible +in git branches named ``debian/*`` on the main FRR git repository. These +branches are for the exclusive use by people involved in Debian packaging work +for FRR. Direct commit access may be handed out and FRR git rules (review, +testing, etc.) do not apply. Do not push to these branches without talking +to the people noted under ``Maintainer:`` and ``Uploaders:`` in +``debian/control`` on the target branch -- even if you are a FRR Maintainer. + Changelog --------- The changelog will be the base for the release notes. A changelog entry for @@ -261,7 +276,7 @@ Pre-submission Checklist - In the case of a major new feature or other significant change, document plans for continued maintenance of the feature. In addition it is a requirement that automated testing must be written that exercises - the new feature within our existing CI infrastructure. Also the + the new feature within our existing CI infrastructure. Also the addition of automated testing to cover any pull request is encouraged. .. _signing-off: @@ -558,6 +573,30 @@ following requirements have achieved consensus: constant in these cases. (Rationale: changing a buffer to another size constant may leave the write operations on a now-incorrect size limit.) +- For stack allocated structs and arrays that should be zero initialized, + prefer initializer expressions over ``memset()`` wherever possible. This + helps prevent ``memset()`` calls being missed in branches, and eliminates the + error class of an incorrect ``size`` argument to ``memset()``. + + For example, instead of: + + .. code-block:: c + + struct foo mystruct; + ... + memset(&mystruct, 0x00, sizeof(struct foo)); + + Prefer: + + .. code-block:: c + + struct foo mystruct = {}; + +- Do not zero initialize stack allocated values that must be initialized with a + nonzero value in order to be used. This way the compiler and memory checking + tools can catch uninitialized value use that would otherwise be suppressed by + the (incorrect) zero initialization. + Other than these specific rules, coding practices from the Linux kernel as well as CERT or MISRA C guidelines may provide useful input on safe C code. However, these rules are not applied as-is; some of them expressly collide @@ -1019,7 +1058,18 @@ the development mailing list / public Slack instance. JSON Output ^^^^^^^^^^^ -All JSON keys are to be camelCased, with no spaces. +* All JSON keys are to be camelCased, with no spaces +* Commands which output JSON should produce ``{}`` if they have nothing to + display + +Use of const +^^^^^^^^^^^^ + +Please consider using ``const`` when possible: it's a useful hint to +callers about the limits to side-effects from your apis, and it makes +it possible to use your apis in paths that involve ``const`` +objects. If you encounter existing apis that *could* be ``const``, +consider including changes in your own pull-request. .. _documentation: diff --git a/doc/developer/zebra.rst b/doc/developer/zebra.rst index e2f887ef28..6a73803d01 100644 --- a/doc/developer/zebra.rst +++ b/doc/developer/zebra.rst @@ -250,7 +250,7 @@ Zebra Protocol Commands +------------------------------------+-------+ | ZEBRA_INTERFACE_DISABLE_RADV | 43 | +------------------------------------+-------+ -| ZEBRA_IPV3_NEXTHOP_LOOKUP_MRIB | 44 | +| ZEBRA_IPV4_NEXTHOP_LOOKUP_MRIB | 44 | +------------------------------------+-------+ | ZEBRA_INTERFACE_LINK_PARAMS | 45 | +------------------------------------+-------+ @@ -372,5 +372,13 @@ Zebra Protocol Commands +------------------------------------+-------+ | ZEBRA_MLAG_FORWARD_MSG | 104 | +------------------------------------+-------+ -| ZEBRA_CLIENT_CAPABILITIES | 105 | +| ZEBRA_ERROR | 105 | ++------------------------------------+-------+ +| ZEBRA_CLIENT_CAPABILITIES | 106 | ++------------------------------------+-------+ +| ZEBRA_OPAQUE_MESSAGE | 107 | ++------------------------------------+-------+ +| ZEBRA_OPAQUE_REGISTER | 108 | ++------------------------------------+-------+ +| ZEBRA_OPAQUE_UNREGISTER | 109 | +------------------------------------+-------+ |