diff options
Diffstat (limited to 'doc/developer')
| -rw-r--r-- | doc/developer/building-frr-for-ubuntu2004.rst | 162 | ||||
| -rw-r--r-- | doc/developer/building.rst | 1 | ||||
| -rw-r--r-- | doc/developer/lists.rst | 37 | ||||
| -rw-r--r-- | doc/developer/subdir.am | 1 | ||||
| -rw-r--r-- | doc/developer/workflow.rst | 9 |
5 files changed, 191 insertions, 19 deletions
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..9d1b5b60ad 100644 --- a/doc/developer/building.rst +++ b/doc/developer/building.rst @@ -26,4 +26,5 @@ Building FRR building-frr-for-ubuntu1404 building-frr-for-ubuntu1604 building-frr-for-ubuntu1804 + building-frr-for-ubuntu2004 building-frr-for-archlinux 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/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/workflow.rst b/doc/developer/workflow.rst index 6885a41e0f..49fa4fe832 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -1021,6 +1021,15 @@ JSON Output All JSON keys are to be camelCased, with no spaces. +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: |