diff options
Diffstat (limited to 'doc/developer')
27 files changed, 328 insertions, 202 deletions
diff --git a/doc/developer/_static/overrides.css b/doc/developer/_static/overrides.css index 1e0de66c55..0d871c961a 100644 --- a/doc/developer/_static/overrides.css +++ b/doc/developer/_static/overrides.css @@ -2,3 +2,7 @@ div.body { max-width: none; } + +pre { + background-color: #e2e2e2; +} diff --git a/doc/developer/building-frr-on-alpine.rst b/doc/developer/building-frr-on-alpine.rst index f0f2aee138..089032b03c 100644 --- a/doc/developer/building-frr-on-alpine.rst +++ b/doc/developer/building-frr-on-alpine.rst @@ -52,13 +52,32 @@ And to run the image: :: - docker run -it --rm frr:latest /bin/sh + docker run -it --rm --name frr frr:latest -Currently, we only package the raw daemons and example files, so, you'll -need to run the daemons by hand (or, better, orchestrate in the Dockerfile). +In the default configuration, none of the frr daemons will be running. +To configure the daemons, exec into the container and edit the configuration +files or mount a volume with configuration files into the container on +startup. To configure by hand: -We can also build directly from docker-compose, with a docker-compose.yml file -like this one: +:: + + docker exec -it frr /bin/sh + vi /etc/frr/daemons + vi /etc/frr/daemons.conf + cp /etc/frr/zebra.conf.sample /etc/frr/zebra.conf + vi /etc/frr/zebra.conf + /etc/init.d/frr start + +Or, to configure the daemons using /etc/frr from a host volume, put the +config files in, say, ./docker/etc and bind mount that into the +container: + +:: + + docker run -it --rm -v `pwd`/docker/etc:/etc/frr frr:latest + +We can also build the base image directly from docker-compose, with a +docker-compose.yml file like this one: :: diff --git a/doc/developer/building-frr-on-centos6.rst b/doc/developer/building-frr-on-centos6.rst index 1c53ea6ba3..d50376548f 100644 --- a/doc/developer/building-frr-on-centos6.rst +++ b/doc/developer/building-frr-on-centos6.rst @@ -125,7 +125,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -135,7 +135,7 @@ Add frr groups and user -c "FRR FRRouting suite" -d /var/run/frr frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example.) @@ -176,7 +176,7 @@ an example.) sudo make SPHINXBUILD=sphinx-build2.7 install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -198,7 +198,7 @@ Create empty FRR configuration files sudo chmod 640 /etc/frr/*.conf Install daemon config file -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -206,13 +206,13 @@ Install daemon config file sudo chown frr:frr /etc/frr/daemons Edit /etc/frr/daemons as needed to select the required daemons -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Look for the section with ``watchfrr_enable=...`` and ``zebra=...`` etc. Enable the daemons as required by changing the value to ``yes`` Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Edit ``/etc/sysctl.conf`` and set the following values (ignore the other settings) @@ -233,7 +233,7 @@ Load the modifed sysctl's on the system: sudo sysctl -p /etc/sysctl.d/90-routing-sysctl.conf Add init.d startup files -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -241,14 +241,14 @@ Add init.d startup files sudo chkconfig --add frr Enable frr daemon at startup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: sudo chkconfig frr on Start FRR manually (or reboot) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: diff --git a/doc/developer/building-frr-on-centos7.rst b/doc/developer/building-frr-on-centos7.rst index 9807543e17..31cd4dcc49 100644 --- a/doc/developer/building-frr-on-centos7.rst +++ b/doc/developer/building-frr-on-centos7.rst @@ -31,7 +31,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -41,7 +41,7 @@ Add frr groups and user -c "FRR FRRouting suite" -d /var/run/frr frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example.) @@ -83,7 +83,7 @@ an example.) sudo make install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -106,7 +106,7 @@ Create empty FRR configuration files sudo chmod 640 /etc/frr/*.conf Install daemon config file -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -114,13 +114,13 @@ Install daemon config file sudo chown frr:frr /etc/frr/daemons Edit /etc/frr/daemons as needed to select the required daemons -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Look for the section with ``watchfrr_enable=...`` and ``zebra=...`` etc. Enable the daemons as required by changing the value to ``yes`` Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Create a new file ``/etc/sysctl.d/90-routing-sysctl.conf`` with the following content: @@ -140,7 +140,7 @@ Load the modifed sysctl's on the system: sudo sysctl -p /etc/sysctl.d/90-routing-sysctl.conf Install frr Service and redhat init files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -148,21 +148,21 @@ Install frr Service and redhat init files sudo install -p -m 755 redhat/frr.init /usr/lib/frr/frr Register the systemd files -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ :: sudo systemctl preset frr.service Enable required frr at startup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: sudo systemctl enable frr Reboot or start FRR manually -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: diff --git a/doc/developer/building-frr-on-debian8.rst b/doc/developer/building-frr-on-debian8.rst index 36ed0c4e66..d1e65a472d 100644 --- a/doc/developer/building-frr-on-debian8.rst +++ b/doc/developer/building-frr-on-debian8.rst @@ -32,7 +32,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -43,7 +43,7 @@ Add frr groups and user sudo usermod -a -G frrvty frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example.) @@ -80,7 +80,7 @@ an example.) sudo make install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -99,7 +99,7 @@ Create empty FRR configuration files sudo install -m 640 -o frr -g frrvty /dev/null /etc/frr/vtysh.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Edit ``/etc/sysctl.conf`` and uncomment the following values (ignore the other settings) @@ -118,7 +118,7 @@ other settings) system Troubleshooting -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ **Local state directory** diff --git a/doc/developer/building-frr-on-debian9.rst b/doc/developer/building-frr-on-debian9.rst index a1aa63236c..7dad9a7bd4 100644 --- a/doc/developer/building-frr-on-debian9.rst +++ b/doc/developer/building-frr-on-debian9.rst @@ -19,7 +19,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -30,7 +30,7 @@ Add frr groups and user sudo usermod -a -G frrvty frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example.) @@ -68,7 +68,7 @@ an example.) sudo make install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -88,7 +88,7 @@ Create empty FRR configuration files sudo install -m 640 -o frr -g frrvty /dev/null /etc/frr/vtysh.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Edit ``/etc/sysctl.conf`` and uncomment the following values (ignore the other settings) @@ -110,7 +110,7 @@ Troubleshooting --------------- Shared library error -~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^ If you try and start any of the frrouting daemons you may see the below error due to the frrouting shared library directory not being found: diff --git a/doc/developer/building-frr-on-fedora24.rst b/doc/developer/building-frr-on-fedora24.rst index ed81d3f59c..208c580b63 100644 --- a/doc/developer/building-frr-on-fedora24.rst +++ b/doc/developer/building-frr-on-fedora24.rst @@ -24,7 +24,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -34,7 +34,7 @@ Add frr groups and user -c "FRR FRRouting suite" -d /var/run/frr frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example.) @@ -75,7 +75,7 @@ an example.) sudo make install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -99,7 +99,7 @@ Create empty FRR configuration files sudo chmod 640 /etc/frr/*.conf Install daemon config file -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -107,13 +107,13 @@ Install daemon config file sudo chown frr:frr /etc/frr/daemons Edit /etc/frr/daemons as needed to select the required daemons -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Look for the section with ``watchfrr_enable=...`` and ``zebra=...`` etc. Enable the daemons as required by changing the value to ``yes`` Enable IP & IPv6 forwarding (and MPLS) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Create a new file ``/etc/sysctl.d/90-routing-sysctl.conf`` with the following content: (Please make sure to list all interfaces with @@ -155,7 +155,7 @@ And load the kernel modules on the running system: sudo modprobe mpls-router mpls-iptunnel Install frr Service and redhat init files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -163,14 +163,14 @@ Install frr Service and redhat init files sudo install -p -m 755 redhat/frr.init /usr/lib/frr/frr Enable required frr at startup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: sudo systemctl enable frr Reboot or start FRR manually -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: diff --git a/doc/developer/building-frr-on-freebsd10.rst b/doc/developer/building-frr-on-freebsd10.rst index ccbe8c55c3..5d14db5fa7 100644 --- a/doc/developer/building-frr-on-freebsd10.rst +++ b/doc/developer/building-frr-on-freebsd10.rst @@ -34,7 +34,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr group and user -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ :: @@ -76,7 +76,7 @@ an example) sudo gmake install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -95,7 +95,7 @@ Create empty FRR configuration files sudo chmod 640 /usr/local/etc/frr/*.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Add the following lines to the end of ``/etc/sysctl.conf``: diff --git a/doc/developer/building-frr-on-freebsd11.rst b/doc/developer/building-frr-on-freebsd11.rst index 214fdbf9c8..87fb30226d 100644 --- a/doc/developer/building-frr-on-freebsd11.rst +++ b/doc/developer/building-frr-on-freebsd11.rst @@ -34,7 +34,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr group and user -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ :: @@ -76,7 +76,7 @@ an example) sudo gmake install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -95,7 +95,7 @@ Create empty FRR configuration files sudo chmod 640 /usr/local/etc/frr/*.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Add the following lines to the end of ``/etc/sysctl.conf``: diff --git a/doc/developer/building-frr-on-freebsd9.rst b/doc/developer/building-frr-on-freebsd9.rst index 909b3a8d64..02279debea 100644 --- a/doc/developer/building-frr-on-freebsd9.rst +++ b/doc/developer/building-frr-on-freebsd9.rst @@ -47,7 +47,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr group and user -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ :: @@ -89,7 +89,7 @@ an example) sudo gmake install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -108,7 +108,7 @@ Create empty FRR configuration files sudo chmod 640 /usr/local/etc/frr/*.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Add the following lines to the end of ``/etc/sysctl.conf``: diff --git a/doc/developer/building-frr-on-lede-openwrt.rst b/doc/developer/building-frr-on-lede-openwrt.rst index b9ee9c51e1..d14754b37f 100644 --- a/doc/developer/building-frr-on-lede-openwrt.rst +++ b/doc/developer/building-frr-on-lede-openwrt.rst @@ -98,11 +98,11 @@ DAEMONS= or don't install unneded packages For example: zebra bgpd ldpd isisd nhrpd ospfd ospf6d pimd ripd ripngd Enable the serivce -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ - service frr enable Start the service -~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^ - service frr start diff --git a/doc/developer/building-frr-on-netbsd6.rst b/doc/developer/building-frr-on-netbsd6.rst index ce5c58045f..ca0845d0d0 100644 --- a/doc/developer/building-frr-on-netbsd6.rst +++ b/doc/developer/building-frr-on-netbsd6.rst @@ -44,7 +44,7 @@ Get FRR, compile it and install it (from Git) --------------------------------------------- Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -54,7 +54,7 @@ Add frr groups and user -d /nonexistent -s /sbin/nologin frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example) @@ -89,7 +89,7 @@ an example) sudo gmake install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -109,7 +109,7 @@ Create empty FRR configuration files sudo chmod 640 /usr/pkg/etc/frr/*.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Add the following lines to the end of ``/etc/sysctl.conf``: @@ -123,7 +123,7 @@ Add the following lines to the end of ``/etc/sysctl.conf``: system Install rc.d init files -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -131,7 +131,7 @@ Install rc.d init files chmod 555 /etc/rc.d/*.sh Enable FRR processes -~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^ (Enable the required processes only) diff --git a/doc/developer/building-frr-on-netbsd7.rst b/doc/developer/building-frr-on-netbsd7.rst index eaaf87fd19..86242ef965 100644 --- a/doc/developer/building-frr-on-netbsd7.rst +++ b/doc/developer/building-frr-on-netbsd7.rst @@ -35,7 +35,7 @@ Get FRR, compile it and install it (from Git) --------------------------------------------- Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -45,7 +45,7 @@ Add frr groups and user -d /nonexistent -s /sbin/nologin frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example) @@ -80,7 +80,7 @@ an example) sudo gmake install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -99,7 +99,7 @@ Create empty FRR configuration files sudo chmod 640 /usr/pkg/etc/frr/*.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Add the following lines to the end of ``/etc/sysctl.conf``: @@ -113,7 +113,7 @@ Add the following lines to the end of ``/etc/sysctl.conf``: system Install rc.d init files -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -121,7 +121,7 @@ Install rc.d init files chmod 555 /etc/rc.d/*.sh Enable FRR processes -~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^ (Enable the required processes only) diff --git a/doc/developer/building-frr-on-omnios.rst b/doc/developer/building-frr-on-omnios.rst index 0eb2b9fec8..03f3845de8 100644 --- a/doc/developer/building-frr-on-omnios.rst +++ b/doc/developer/building-frr-on-omnios.rst @@ -9,7 +9,7 @@ OmniOS restrictions: use without MPLS Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -93,7 +93,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr group and user -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ :: @@ -138,7 +138,7 @@ an example) sudo gmake install Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: diff --git a/doc/developer/building-frr-on-openbsd6.rst b/doc/developer/building-frr-on-openbsd6.rst index 895048886e..1f3aec8d92 100644 --- a/doc/developer/building-frr-on-openbsd6.rst +++ b/doc/developer/building-frr-on-openbsd6.rst @@ -30,7 +30,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr group and user -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ :: @@ -40,7 +40,7 @@ Add frr group and user -d /nonexistent -s /sbin/nologin _frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example) @@ -75,7 +75,7 @@ an example) doas gmake install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -100,7 +100,7 @@ Create empty FRR configuration files doas chmod 640 /etc/frr/*.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Add the following lines to the end of ``/etc/rc.conf``: @@ -113,7 +113,7 @@ Add the following lines to the end of ``/etc/rc.conf``: **Reboot** to apply the config to the system Enable MPLS Forwarding -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ To enable MPLS forwarding on a given interface, use the following command: @@ -132,7 +132,7 @@ Example: inet 10.0.1.1 255.255.255.0 mpls Install rc.d init files -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ (create them in /etc/rc.d - no example are included at this time with FRR source) @@ -152,7 +152,7 @@ Example (for zebra - store as ``/etc/rc.d/frr_zebra.sh``) rc_cmd $1 Enable FRR processes -~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^ (Enable the required processes only) diff --git a/doc/developer/building-frr-on-ubuntu1204.rst b/doc/developer/building-frr-on-ubuntu1204.rst index 68e476fec2..bba49c1ce7 100644 --- a/doc/developer/building-frr-on-ubuntu1204.rst +++ b/doc/developer/building-frr-on-ubuntu1204.rst @@ -70,7 +70,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -81,7 +81,7 @@ Add frr groups and user sudo usermod -a -G frrvty frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example.) @@ -116,7 +116,7 @@ an example.) sudo make install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -135,7 +135,7 @@ Create empty FRR configuration files sudo install -m 640 -o frr -g frrvty /dev/null /etc/frr/vtysh.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Edit ``/etc/sysctl.conf`` and uncomment the following values (ignore the other settings) @@ -154,7 +154,7 @@ other settings) system Install the init.d service -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -164,7 +164,7 @@ Install the init.d service sudo install -m 644 -o frr -g frr tools/etc/frr/vtysh.conf /etc/frr/vtysh.conf Enable daemons -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ | Edit ``/etc/frr/daemons`` and change the value from "no" to "yes" for those daemons you want to start by systemd. @@ -181,7 +181,7 @@ Enable daemons isisd=yes Start the init.d service -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ - /etc/init.d/frr start - use ``/etc/init.d/frr status`` to check its status. diff --git a/doc/developer/building-frr-on-ubuntu1404.rst b/doc/developer/building-frr-on-ubuntu1404.rst index 10944cb8e1..c86f1124a7 100644 --- a/doc/developer/building-frr-on-ubuntu1404.rst +++ b/doc/developer/building-frr-on-ubuntu1404.rst @@ -24,7 +24,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -35,7 +35,7 @@ Add frr groups and user sudo usermod -a -G frrvty frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example.) @@ -71,7 +71,7 @@ an example.) sudo make install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -90,7 +90,7 @@ Create empty FRR configuration files sudo install -m 640 -o frr -g frrvty /dev/null /etc/frr/vtysh.conf Enable IP & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Edit ``/etc/sysctl.conf`` and uncomment the following values (ignore the other settings) @@ -106,7 +106,10 @@ other settings) net.ipv6.conf.all.forwarding=1 **Reboot** or use ``sysctl -p`` to apply the same config to the running -system ### Install the init.d service +system + +Install the init.d service +^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -116,7 +119,7 @@ system ### Install the init.d service sudo install -m 644 -o frr -g frr tools/etc/frr/vtysh.conf /etc/frr/vtysh.conf Enable daemons -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ | Edit ``/etc/frr/daemons`` and change the value from "no" to "yes" for those daemons you want to start by systemd. @@ -133,7 +136,7 @@ Enable daemons isisd=yes Start the init.d service -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ - /etc/init.d/frr start - use ``/etc/init.d/frr status`` to check its status. diff --git a/doc/developer/building-frr-on-ubuntu1604.rst b/doc/developer/building-frr-on-ubuntu1604.rst index 9c296f8edf..1b371893e2 100644 --- a/doc/developer/building-frr-on-ubuntu1604.rst +++ b/doc/developer/building-frr-on-ubuntu1604.rst @@ -25,7 +25,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -36,7 +36,7 @@ Add frr groups and user sudo usermod -a -G frrvty frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example.) @@ -72,7 +72,7 @@ an example.) sudo make install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -91,7 +91,7 @@ Create empty FRR configuration files sudo install -m 640 -o frr -g frrvty /dev/null /etc/frr/vtysh.conf Enable IPv4 & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Edit ``/etc/sysctl.conf`` and uncomment the following values (ignore the other settings) @@ -107,7 +107,7 @@ other settings) net.ipv6.conf.all.forwarding=1 Enable MPLS Forwarding (with Linux Kernel >= 4.5) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Edit ``/etc/sysctl.conf`` and the following lines. Make sure to add a line equal to ``net.mpls.conf.eth0.input`` or each interface used with @@ -122,7 +122,7 @@ MPLS net.mpls.platform_labels=100000 Add MPLS kernel modules -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ Add the following lines to ``/etc/modules-load.d/modules.conf``: @@ -136,7 +136,7 @@ Add the following lines to ``/etc/modules-load.d/modules.conf``: system Install the systemd service (if rebooted from last step, change directory back to frr directory) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -148,7 +148,7 @@ Install the systemd service (if rebooted from last step, change directory back t sudo install -m 644 -o frr -g frr tools/etc/frr/vtysh.conf /etc/frr/vtysh.conf Enable daemons -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ | Edit ``/etc/frr/daemons`` and change the value from "no" to "yes" for those daemons you want to start by systemd. @@ -165,12 +165,12 @@ Enable daemons isisd=yes Enable the systemd service -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ - systemctl enable frr Start the systemd service -~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^ - systemctl start frr - use ``systemctl status frr`` to check its status. diff --git a/doc/developer/building-frr-on-ubuntu1804.rst b/doc/developer/building-frr-on-ubuntu1804.rst index 6c79ed87d6..17edb7ef4f 100644 --- a/doc/developer/building-frr-on-ubuntu1804.rst +++ b/doc/developer/building-frr-on-ubuntu1804.rst @@ -20,7 +20,7 @@ Get FRR, compile it and install it (from Git) using any packages** Add frr groups and user -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -31,7 +31,7 @@ Add frr groups and user sudo usermod -a -G frrvty frr Download Source, configure and compile it -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (You may prefer different options on configure statement. These are just an example.) @@ -67,7 +67,7 @@ an example.) sudo make install Create empty FRR configuration files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -86,7 +86,7 @@ Create empty FRR configuration files sudo install -m 640 -o frr -g frrvty /dev/null /etc/frr/vtysh.conf Enable IPv4 & IPv6 forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Edit ``/etc/sysctl.conf`` and uncomment the following values (ignore the other settings) @@ -102,7 +102,7 @@ other settings) net.ipv6.conf.all.forwarding=1 Enable MPLS Forwarding (with Linux Kernel >= 4.5) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Edit ``/etc/sysctl.conf`` and the following lines. Make sure to add a line equal to ``net.mpls.conf.eth0.input`` or each interface used with @@ -117,7 +117,7 @@ MPLS net.mpls.platform_labels=100000 Add MPLS kernel modules -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ Add the following lines to ``/etc/modules-load.d/modules.conf``: @@ -131,7 +131,7 @@ Add the following lines to ``/etc/modules-load.d/modules.conf``: system Install the systemd service (if rebooted from last step, change directory back to frr directory) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -143,7 +143,7 @@ Install the systemd service (if rebooted from last step, change directory back t sudo install -m 644 -o frr -g frr tools/etc/frr/vtysh.conf /etc/frr/vtysh.conf Enable daemons -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ | Edit ``/etc/frr/daemons`` and change the value from "no" to "yes" for those daemons you want to start by systemd. @@ -160,12 +160,12 @@ Enable daemons isisd=yes Enable the systemd service -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ - systemctl enable frr Start the systemd service -~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^ - systemctl start frr - use ``systemctl status frr`` to check its status. diff --git a/doc/developer/building.rst b/doc/developer/building.rst index c7a53734d9..92fd1bb63a 100644 --- a/doc/developer/building.rst +++ b/doc/developer/building.rst @@ -1,5 +1,6 @@ +************ Building FRR -========================= +************ .. toctree:: :maxdepth: 2 diff --git a/doc/developer/conf.py b/doc/developer/conf.py index 9ae1991817..a3968b60ff 100644 --- a/doc/developer/conf.py +++ b/doc/developer/conf.py @@ -15,6 +15,8 @@ import sys import os import re +import pygments +from sphinx.highlighting import lexers # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -51,7 +53,7 @@ master_doc = 'index' # General information about the project. project = u'FRR' copyright = u'2017, FRR' -author = u'FRR' +author = u'FRR authors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -67,34 +69,40 @@ release = u'?.?-?' # Extract values from codebase for substitution into docs. # ----------------------------------------------------------------------------- -# Various installation prefixes. Reasonable defaults are set where possible. -# Values are overridden by logic below. +# Various installation prefixes. Values are extracted from config.status. +# Reasonable defaults are set in case that file does not exist. replace_vars = { - 'AUTHORS': 'Kunihiro Ishiguro, et al.', + 'AUTHORS': author, 'COPYRIGHT_YEAR': '1999-2005', - 'COPYRIGHT_STR': None, + 'COPYRIGHT_STR': 'Copyright (c) 1999-2005', 'PACKAGE_NAME': project.lower(), 'PACKAGE_TARNAME': project.lower(), - 'PACKAGE_STRING': None, + 'PACKAGE_STRING': project.lower() + ' latest', 'PACKAGE_URL': 'https://frrouting.org/', - 'PACKAGE_VERSION': None, - 'INSTALL_PREFIX_ETC': None, - 'INSTALL_PREFIX_SBIN': None, - 'INSTALL_PREFIX_STATE': None, - 'INSTALL_PREFIX_MODULES': None, - 'INSTALL_USER': None, - 'INSTALL_GROUP': None, - 'INSTALL_VTY_GROUP': None, + 'PACKAGE_VERSION': 'latest', + 'INSTALL_PREFIX_ETC': '/etc/frr', + 'INSTALL_PREFIX_SBIN': '/usr/lib/frr', + 'INSTALL_PREFIX_STATE': '/var/run/frr', + 'INSTALL_PREFIX_MODULES': '/usr/lib/frr/modules', + 'INSTALL_USER': 'frr', + 'INSTALL_GROUP': 'frr', + 'INSTALL_VTY_GROUP': 'frrvty', + 'GROUP': 'frr', + 'USER': 'frr', } # extract version information, installation location, other stuff we need to # use when building final documents val = re.compile('^S\["([^"]+)"\]="(.*)"$') -with open('../../config.status', 'r') as cfgstatus: - for ln in cfgstatus.readlines(): - m = val.match(ln) - if not m or m.group(1) not in replace_vars.keys(): continue - replace_vars[m.group(1)] = m.group(2) +try: + with open('../../config.status', 'r') as cfgstatus: + for ln in cfgstatus.readlines(): + m = val.match(ln) + if not m or m.group(1) not in replace_vars.keys(): continue + replace_vars[m.group(1)] = m.group(2) +except IOError: + # if config.status doesn't exist, just ignore it + pass # manually fill out some of these we can't get from config.status replace_vars['COPYRIGHT_STR'] = "Copyright (c)" @@ -341,3 +349,13 @@ def setup(app): app.add_object_type('clicmd', 'clicmd') # css overrides for HTML theme app.add_stylesheet('overrides.css') + # load Pygments lexer for FRR config syntax + # + # NB: in Pygments 2.2+ this can be done with `load_lexer_from_file`, but we + # do it manually since not all of our supported build platforms have 2.2 + # yet. + # + # frrlexer = pygments.lexers.load_lexer_from_file('../extra/frrlexer.py', lexername="FRRLexer") + custom_namespace = {} + exec(open('../extra/frrlexer.py', 'rb').read(), custom_namespace) + lexers['frr'] = custom_namespace['FRRLexer']() diff --git a/doc/developer/hooks.rst b/doc/developer/hooks.rst index 0afa297aa7..4140a0d171 100644 --- a/doc/developer/hooks.rst +++ b/doc/developer/hooks.rst @@ -12,26 +12,26 @@ the appropriate function signature (parameters) for the hook. Example: .. code-block:: c - :caption: mydaemon.h + :caption: mydaemon.h - #include "hook.h" - DECLARE_HOOK(some_update_event, (struct eventinfo *info), (info)) + #include "hook.h" + DECLARE_HOOK(some_update_event, (struct eventinfo *info), (info)) .. code-block:: c - :caption: mydaemon.c + :caption: mydaemon.c - #include "mydaemon.h" - DEFINE_HOOK(some_update_event, (struct eventinfo *info), (info)) - ... - hook_call(some_update_event, info); + #include "mydaemon.h" + DEFINE_HOOK(some_update_event, (struct eventinfo *info), (info)) + ... + hook_call(some_update_event, info); .. code-block:: c - :caption: mymodule.c + :caption: mymodule.c - #include "mydaemon.h" - static int event_handler(struct eventinfo *info); - ... - hook_register(some_update_event, event_handler); + #include "mydaemon.h" + static int event_handler(struct eventinfo *info); + ... + hook_register(some_update_event, event_handler); Do not use parameter names starting with "hook", these can collide with names used by the hook code itself. diff --git a/doc/developer/library.rst b/doc/developer/library.rst index 791aedb624..c5ce1f5982 100644 --- a/doc/developer/library.rst +++ b/doc/developer/library.rst @@ -1,5 +1,6 @@ -libfrr library facilities -========================= +*************************** +Library Facilities (libfrr) +*************************** .. toctree:: :maxdepth: 2 diff --git a/doc/developer/memtypes.rst b/doc/developer/memtypes.rst index d40ebe31cd..d43bc2555e 100644 --- a/doc/developer/memtypes.rst +++ b/doc/developer/memtypes.rst @@ -6,37 +6,37 @@ Memtypes FRR includes wrappers arround ``malloc()`` and ``free()`` that count the number of objects currently allocated, for each of a defined ``MTYPE``. -To this extent, there are `memory groups` and `memory types`. Each memory +To this extent, there are *memory groups* and *memory types*. Each memory type must belong to a memory group, this is used just to provide some basic structure. Example: .. code-block:: c - :caption: mydaemon.h + :caption: mydaemon.h - DECLARE_MGROUP(MYDAEMON) - DECLARE_MTYPE(MYNEIGHBOR) + DECLARE_MGROUP(MYDAEMON) + DECLARE_MTYPE(MYNEIGHBOR) .. code-block:: c - :caption: mydaemon.c - - DEFINE_MGROUP( MYDAEMON, "My daemon's memory") - DEFINE_MTYPE( MYDAEMON, MYNEIGHBOR, "Neighbor entry") - DEFINE_MTYPE_STATIC(MYDAEMON, MYNEIGHBORNAME, "Neighbor name") - - struct neigh *neighbor_new(const char *name) - { - struct neigh *n = XMALLOC(MYNEIGHBOR, sizeof(*n)); - n->name = XSTRDUP(MYNEIGHBORNAME, name); - return n; - } - - void neighbor_free(struct neigh *n) - { - XFREE(MYNEIGHBORNAME, n->name); - XFREE(MYNEIGHBOR, n); - } + :caption: mydaemon.c + + DEFINE_MGROUP( MYDAEMON, "My daemon's memory") + DEFINE_MTYPE( MYDAEMON, MYNEIGHBOR, "Neighbor entry") + DEFINE_MTYPE_STATIC(MYDAEMON, MYNEIGHBORNAME, "Neighbor name") + + struct neigh *neighbor_new(const char *name) + { + struct neigh *n = XMALLOC(MYNEIGHBOR, sizeof(*n)); + n->name = XSTRDUP(MYNEIGHBORNAME, name); + return n; + } + + void neighbor_free(struct neigh *n) + { + XFREE(MYNEIGHBORNAME, n->name); + XFREE(MYNEIGHBOR, n); + } Definition diff --git a/doc/developer/next-hop-tracking.rst b/doc/developer/next-hop-tracking.rst index 25e2d1fe1a..8a6a4ccb33 100644 --- a/doc/developer/next-hop-tracking.rst +++ b/doc/developer/next-hop-tracking.rst @@ -100,7 +100,7 @@ Design ------ Modules -~~~~~~~ +^^^^^^^ The core design introduces an "nht" (next hop tracking) module in BGP and "rnh" (recursive nexthop) module in Zebra. The "nht" module @@ -178,7 +178,7 @@ The next hop notification control flow is the following: zclient message format -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ ZEBRA_NEXTHOP_REGISTER and ZEBRA_NEXTHOP_UNREGISTER messages are encoded in the following way: @@ -233,7 +233,7 @@ encoded in the following way: BGP data structure -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ Legend: :: @@ -260,7 +260,7 @@ Legend: Zebra data structure -~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^ RNH table:: @@ -279,7 +279,7 @@ RNH table:: }; User interface changes -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ :: @@ -338,7 +338,7 @@ User interface changes + no shut all links to r4 Future work -~~~~~~~~~~~ +^^^^^^^^^^^ - route-policy for next hop validation (e.g. ignore default route) - damping for rapid next hop changes diff --git a/doc/developer/ospf-sr.rst b/doc/developer/ospf-sr.rst index 3f8b549df3..4a673b155b 100644 --- a/doc/developer/ospf-sr.rst +++ b/doc/developer/ospf-sr.rst @@ -29,7 +29,7 @@ Implementation details ---------------------- Concepts -~~~~~~~~ +^^^^^^^^ Segment Routing used 3 differents OPAQUE LSA in OSPF to carry the various information: @@ -47,7 +47,7 @@ Segment Routing functions (see below) when an Extended Link / Prefix or Router Information LSA s are received. Overview -~~~~~~~~ +^^^^^^^^ Following files where modified or added: @@ -113,7 +113,7 @@ The figure below shows the relation between the various files: Figure 1: Overview of Segment Routing interaction Module interactions -~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^ To process incoming LSA, the code is based on the capability to call `hook()` functions when LSA are inserted or delete to / from the LSDB and the @@ -186,7 +186,7 @@ Configuration ------------- Linux Kernel -~~~~~~~~~~~~ +^^^^^^^^^^^^ In order to use OSPF Segment Routing, you must setup MPLS data plane. Up to know, only Linux Kernel version >= 4.5 is supported. @@ -231,7 +231,7 @@ especially the `lo` one. For that purpose, disable RP filtering with: sysctl -w net.ipv4.conf.lo.rp_filter=0 OSPFd -~~~~~ +^^^^^ Here it is a simple example of configuration to enable Segment Routing. Note that `opaque capability` and `router information` must be set to activate diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index 291a277c6b..f025c47bb4 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -479,6 +479,16 @@ checkpatch.sh When convenient it is preferred that these be cleaned up inline, but this is not required. + In general, a developer should heed the information reported by checkpatch. + However, some flexibility is needed for cases where human judgement yields + better clarity than the script. Accordingly, it may be appropriate to + ignore some checkpatch.sh warnings per discussion among the submitter(s) + and reviewer(s) of a change. Misreporting of errors by the script is + possible. When this occurs, the exception should be handled either by + patching checkpatch to correct the false error report, or by documenting the + exception in this document under :ref:`style-exceptions`. If the incorrect + report is likely to appear again, a checkpatch update is preferred. + If the script finds one or more WARNINGs it will exit with 1. If it finds one or more ERRORs it will exit with 2. @@ -488,6 +498,12 @@ responsibility for properly formatting your code ultimately lies on the shoulders of the submitter. As such, it is recommended to double-check the results of these tools to avoid delays in merging your submission. +In some cases, these tools modify or flag the format in ways that go beyond or +even conflict [#tool_style_conflicts]_ with the canonical documented Linux +kernel style. In these cases, the Linux kernel style takes priority; +non-canonical issues flagged by the tools are not compulsory but rather are +opportunities for discussion among the submitter(s) and reviewer(s) of a change. + **Whitespace changes in untouched parts of the code are not acceptable in patches that change actual code.** To change/fix formatting issues, please create a separate patch that only does formatting changes and @@ -533,6 +549,8 @@ necessary replacements. | u_long | unsigned long | +-----------+--------------------------+ +.. _style-exceptions: + Exceptions ^^^^^^^^^^ @@ -571,6 +589,23 @@ BSD coding style applies to: - ``ldpd/`` + +Specific Exceptions +^^^^^^^^^^^^^^^^^^^ + +Most of the time checkpatch errors should be corrected. Occasionally as a group +maintainers will decide to ignore certain stylistic issues. Usually this is +because correcting the issue is not possible without large unrelated code +changes. When an exception is made, if it is unlikely to show up again and +doesn't warrant an update to checkpatch, it is documented here. + ++------------------------------------------+---------------------------------------------------------------+ +| Issue | Ignore Reason | ++==========================================+===============================================================+ +| DEFPY_HIDDEN, DEFPY_ATTR: complex macros | DEF* macros cannot be wrapped in parentheses without updating | +| should be wrapped in parentheses | all usages of the macro, which would be highly disruptive. | ++------------------------------------------+---------------------------------------------------------------+ + Compile-time conditional code ----------------------------- @@ -633,7 +668,7 @@ AddressSanitizer instrumentation and run through a series of tests to look for any results. Testing your own code with this tool before submission is encouraged. You can enable it by passing:: - + --enable-address-sanitizer to ``configure``. @@ -643,7 +678,7 @@ ThreadSanitizer detecting data races. If you are working on or around multithreaded code, extensive testing with this instrumtation enabled is *highly* recommended. You can enable it by passing:: - + --enable-thread-sanitizer to ``configure``. @@ -652,7 +687,7 @@ MemorySanitizer Similar to AddressSanitizer, this tool provides runtime instrumentation for detecting use of uninitialized heap memory. Testing your own code with this tool before submission is encouraged. You can enable it by passing:: - + --enable-memory-sanitizer to ``configure``. @@ -740,27 +775,33 @@ FRR uses Sphinx+RST as its documentation system. The document you are currently reading was generated by Sphinx from RST source in :file:`doc/developer/workflow.rst`. The documentation is structured as follows: -+-----------------------+--------------------------------------------------------------+ -| Directory | Contents | -+=======================+==============================================================+ -| :file:`doc/user` | User documentation; configuration guides; protocol overviews | -+-----------------------+--------------------------------------------------------------+ -| :file:`doc/developer` | Developer's documentation; API specs; datastructures; | -| | architecture overviews; project management procedure | -+-----------------------+--------------------------------------------------------------+ -| :file:`doc/manpages` | Source for manpages | -+-----------------------+--------------------------------------------------------------+ -| :file:`doc/figures` | Images and diagrams | -+-----------------------+--------------------------------------------------------------+ - -Each of these directories, with the exception of :file:`doc/figures`, contains -a Sphinx-generated Makefile and configuration script :file:`conf.py` used to -set various document parameters. The makefile can be used for a variety of -targets; invoke `make help` in any of these directories for a listing of -available output formats. For convenience, there is a top-level -:file:`Makefile.am` that has targets for PDF and HTML documentation for both -developer and user documentation, respectively. That makefile is also -responsible for building manual pages packed with distribution builds. ++-----------------------+-------------------------------------------+ +| Directory | Contents | ++=======================+===========================================+ +| :file:`doc/user` | User documentation; configuration guides; | +| | protocol overviews | ++-----------------------+-------------------------------------------+ +| :file:`doc/developer` | Developer's documentation; API specs; | +| | datastructures; architecture overviews; | +| | project management procedure | ++-----------------------+-------------------------------------------+ +| :file:`doc/manpages` | Source for manpages | ++-----------------------+-------------------------------------------+ +| :file:`doc/figures` | Images and diagrams | ++-----------------------+-------------------------------------------+ +| :file:`doc/extra` | Miscellaneous Sphinx extensions, scripts, | +| | customizations, etc. | ++-----------------------+-------------------------------------------+ + +Each of these directories, with the exception of :file:`doc/figures` and +:file:`doc/extra`, contains a Sphinx-generated Makefile and configuration +script :file:`conf.py` used to set various document parameters. The makefile +can be used for a variety of targets; invoke `make help` in any of these +directories for a listing of available output formats. For convenience, there +is a top-level :file:`Makefile.am` that has targets for PDF and HTML +documentation for both developer and user documentation, respectively. That +makefile is also responsible for building manual pages packed with distribution +builds. Indent and styling should follow existing conventions: @@ -855,6 +896,15 @@ your implementation of a new BGP draft should go in the BGP chapter instead of being its own chapter. If you are adding a new protocol daemon, please create a new chapter. +FRR Specific Markup +------------------- + +FRR has some customizations applied to the Sphinx markup that go a long way +towards making documentation easier to use, write and maintain. + +CLI Commands +^^^^^^^^^^^^ + When documenting CLI please use a combination of the ``.. index::`` and ``.. clicmd::`` directives. For example, the command :clicmd:`show pony` would be documented as follows: @@ -888,5 +938,35 @@ When documented this way, CLI commands can be cross referenced with the This is very helpful for users who want to quickly remind themselves what a particular command does. +Configuration Snippets +^^^^^^^^^^^^^^^^^^^^^^ + +When putting blocks of example configuration please use the +``.. code-block::`` directive and specify ``frr`` as the highlighting language, +as in the following example. This will tell Sphinx to use a custom Pygments +lexer to highlight FRR configuration syntax. + +.. code-block:: rest + + .. code-block:: frr + + ! + ! Example configuration file. + ! + log file /tmp/log.log + service integrated-vtysh-config + ! + ip route 1.2.3.0/24 reject + ipv6 route de:ea:db:ee:ff::/64 reject + ! + + .. _GitHub: https://github.com/frrouting/frr .. _GitHub issues: https://github.com/frrouting/frr/issues + +.. rubric:: Footnotes + +.. [#tool_style_conflicts] For example, lines over 80 characters are allowed + for text strings to make it possible to search the code for them: please + see `Linux kernel style (breaking long lines and strings) <https://www.kernel.org/doc/html/v4.10/process/coding-style.html#breaking-long-lines-and-strings>`_ + and `Issue #1794 <https://github.com/FRRouting/frr/issues/1794>`_. |