diff options
Diffstat (limited to 'doc/developer')
33 files changed, 582 insertions, 644 deletions
diff --git a/doc/developer/building-frr-for-centos6.rst b/doc/developer/building-frr-for-centos6.rst index c57573cb9f..f1ec2ad3ea 100644 --- a/doc/developer/building-frr-for-centos6.rst +++ b/doc/developer/building-frr-for-centos6.rst @@ -1,9 +1,10 @@ +.. _building-centos6: + CentOS 6 ======================================== -(As an alternative to this installation, you may prefer to create a FRR -rpm package yourself and install that package instead. See instructions -in redhat/README.rpm\_build.md on how to build a rpm package) +This document describes installation from source. If you want to build an RPM, +see :ref:`packaging-redhat`. Instructions are tested with ``CentOS 6.8`` on ``x86_64`` platform @@ -24,7 +25,7 @@ CentOS 6 restrictions: PIMd is needed - MPLS is not supported on ``CentOS 6``. MPLS requires Linux Kernel 4.5 or higher (LDP can be built, but may have limited use without MPLS) -- Zebra is unable to detect what bridge/vrf an interface is associcated +- Zebra is unable to detect what bridge/vrf an interface is associated with (IFLA\_INFO\_SLAVE\_KIND does not exist in the kernel headers, you can use a newer kernel + headers to get this functionality) - frr\_reload.py will not work, as this requires Python 2.7, and CentOS @@ -42,7 +43,7 @@ Add packages: .. code-block:: shell - sudo yum install git autoconf automake libtool make gawk \ + sudo yum install git autoconf automake libtool make \ readline-devel texinfo net-snmp-devel groff pkgconfig \ json-c-devel pam-devel flex epel-release c-ares-devel @@ -235,7 +236,7 @@ settings):: # Controls source route verification net.ipv4.conf.default.rp_filter = 0 -Load the modifed sysctl's on the system: +Load the modified sysctl's on the system: .. code-block:: shell diff --git a/doc/developer/building-frr-for-centos7.rst b/doc/developer/building-frr-for-centos7.rst index 8f82cd6c9a..ea3c44478c 100644 --- a/doc/developer/building-frr-for-centos7.rst +++ b/doc/developer/building-frr-for-centos7.rst @@ -1,9 +1,8 @@ CentOS 7 ======================================== -(As an alternative to this installation, you may prefer to create a FRR -rpm package yourself and install that package instead. See instructions -in redhat/README.rpm\_build.md on how to build a rpm package) +This document describes installation from source. If you want to build an RPM, +see :ref:`packaging-redhat`. CentOS 7 restrictions: ---------------------- @@ -19,7 +18,7 @@ Add packages: :: - sudo yum install git autoconf automake libtool make gawk \ + sudo yum install git autoconf automake libtool make \ readline-devel texinfo net-snmp-devel groff pkgconfig \ json-c-devel pam-devel bison flex pytest c-ares-devel \ python-devel systemd-devel python-sphinx @@ -127,7 +126,7 @@ following content: net.ipv4.conf.all.forwarding=1 net.ipv6.conf.all.forwarding=1 -Load the modifed sysctl's on the system: +Load the modified sysctl's on the system: :: diff --git a/doc/developer/building-frr-for-debian8.rst b/doc/developer/building-frr-for-debian8.rst index d0f4182bae..9c6e48a6f8 100644 --- a/doc/developer/building-frr-for-debian8.rst +++ b/doc/developer/building-frr-for-debian8.rst @@ -15,7 +15,7 @@ Add packages: :: - sudo apt-get install git autoconf automake libtool make gawk \ + sudo apt-get install git autoconf automake libtool make \ libreadline-dev texinfo libjson-c-dev pkg-config bison flex python-pip \ libc-ares-dev python3-dev python3-sphinx build-essential libsystemd-dev diff --git a/doc/developer/building-frr-for-fedora.rst b/doc/developer/building-frr-for-fedora.rst new file mode 100644 index 0000000000..204c185f56 --- /dev/null +++ b/doc/developer/building-frr-for-fedora.rst @@ -0,0 +1,122 @@ +Fedora 24+ +========== + +This document describes installation from source. If you want to build an RPM, +see :ref:`packaging-redhat`. + +These instructions have been tested on Fedora 24+. + +Installing Dependencies +----------------------- + +.. code-block:: console + + sudo dnf install git autoconf automake libtool make \ + readline-devel texinfo net-snmp-devel groff pkgconfig json-c-devel \ + pam-devel pytest bison flex c-ares-devel python3-devel python2-sphinx \ + perl-core patch + +.. include:: building-libyang.rst + +Building & Installing FRR +------------------------- + +Add FRR user and groups +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: console + + sudo groupadd -g 92 frr + sudo groupadd -r -g 85 frrvty + sudo useradd -u 92 -g 92 -M -r -G frrvty -s /sbin/nologin \ + -c "FRR FRRouting suite" -d /var/run/frr 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. + +Create a new file ``/etc/sysctl.d/90-routing-sysctl.conf`` with the following +content: + +:: + + # + # Enable packet forwarding + # + net.ipv4.conf.all.forwarding=1 + net.ipv6.conf.all.forwarding=1 + # + # 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 + +.. note:: + + MPLS must be invidividually enabled on each interface that requires it. See + the example in the config block above. + +Load the modifed sysctls on the system: + +.. code-block:: console + + sudo sysctl -p /etc/sysctl.d/90-routing-sysctl.conf + +Create a new file ``/etc/modules-load.d/mpls.conf`` with the following content: + +:: + + # 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 + +Install service files +^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: console + + sudo install -p -m 644 redhat/frr.service /usr/lib/systemd/system/frr.service + sudo install -p -m 755 redhat/frr.init /usr/lib/frr/frr + 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:: frr + + sudo systemctl start frr diff --git a/doc/developer/building-frr-for-fedora24.rst b/doc/developer/building-frr-for-fedora24.rst deleted file mode 100644 index 2edf9b3e44..0000000000 --- a/doc/developer/building-frr-for-fedora24.rst +++ /dev/null @@ -1,170 +0,0 @@ -Fedora 24 -========================================= - -(As an alternative to this installation, you may prefer to create a FRR -rpm package yourself and install that package instead. See instructions -in redhat/README.rpm\_build.md on how to build a rpm package) - -Install required packages -------------------------- - -Add packages: - -:: - - sudo dnf install git autoconf automake libtool make gawk \ - readline-devel texinfo net-snmp-devel groff pkgconfig \ - json-c-devel pam-devel pytest bison flex c-ares-devel \ - python3-devel python3-sphinx - -.. include:: building-libyang.rst - -Get FRR, compile it and install it (from Git) ---------------------------------------------- - -**This assumes you want to build and install FRR from source and not -using any packages** - -Add frr groups and user -^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - sudo groupadd -g 92 frr - sudo groupadd -r -g 85 frrvty - sudo useradd -u 92 -g 92 -M -r -G frrvty -s /sbin/nologin \ - -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.) - -:: - - git clone https://github.com/frrouting/frr.git frr - cd frr - ./bootstrap.sh - ./configure \ - --bindir=/usr/bin \ - --sbindir=/usr/lib/frr \ - --sysconfdir=/etc/frr \ - --libdir=/usr/lib/frr \ - --libexecdir=/usr/lib/frr \ - --localstatedir=/var/run/frr \ - --with-moduledir=/usr/lib/frr/modules \ - --enable-snmp=agentx \ - --enable-multipath=64 \ - --enable-user=frr \ - --enable-group=frr \ - --enable-vty-group=frrvty \ - --disable-exampledir \ - --enable-fpm \ - --with-pkg-git-version \ - --with-pkg-extra-version=-MyOwnFRRVersion - make - make check - sudo make install - -Create empty FRR configuration files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - sudo mkdir /var/log/frr - sudo mkdir /etc/frr - sudo touch /etc/frr/zebra.conf - sudo touch /etc/frr/bgpd.conf - sudo touch /etc/frr/ospfd.conf - sudo touch /etc/frr/ospf6d.conf - sudo touch /etc/frr/isisd.conf - sudo touch /etc/frr/ripd.conf - sudo touch /etc/frr/ripngd.conf - sudo touch /etc/frr/pimd.conf - sudo touch /etc/frr/ldpd.conf - sudo touch /etc/frr/nhrpd.conf - sudo touch /etc/frr/eigrpd.conf - sudo touch /etc/frr/babeld.conf - sudo chown -R frr:frr /etc/frr/ - sudo touch /etc/frr/vtysh.conf - sudo chown frr:frrvty /etc/frr/vtysh.conf - sudo chmod 640 /etc/frr/*.conf - -Install daemon config file -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - sudo install -p -m 644 redhat/daemons /etc/frr/ - 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 -required MPLS similar to ``net.mpls.conf.eth0.input=1``) - -:: - - # Sysctl for routing - # - # Routing: We need to forward packets - net.ipv4.conf.all.forwarding=1 - net.ipv6.conf.all.forwarding=1 - # - # 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 - -Load the modifed sysctl's on the system: - -:: - - sudo sysctl -p /etc/sysctl.d/90-routing-sysctl.conf - -Create a new file ``/etc/modules-load.d/mpls.conf`` with the following -content: - -:: - - # Load MPLS Kernel Modules - mpls-router - mpls-iptunnel - -And load the kernel modules on the running system: - -:: - - sudo modprobe mpls-router mpls-iptunnel - -Install frr Service and redhat init files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - sudo install -p -m 644 redhat/frr.service /usr/lib/systemd/system/frr.service - 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - sudo systemctl start frr diff --git a/doc/developer/building-frr-for-freebsd10.rst b/doc/developer/building-frr-for-freebsd10.rst index a6539309a2..86c44f4d90 100644 --- a/doc/developer/building-frr-for-freebsd10.rst +++ b/doc/developer/building-frr-for-freebsd10.rst @@ -11,12 +11,12 @@ FreeBSD 10 restrictions: Install required packages ------------------------- -Add packages: (Allow the install of the package managment tool if this +Add packages: (Allow the install of the package management tool if this is first package install and asked) :: - pkg install git autoconf automake libtool gmake gawk json-c pkgconf \ + pkg install git autoconf automake libtool gmake json-c pkgconf \ bison flex py27-pytest c-ares python3 py-sphinx Make sure there is no /usr/bin/flex preinstalled (and use the newly diff --git a/doc/developer/building-frr-for-freebsd11.rst b/doc/developer/building-frr-for-freebsd11.rst index 16d06e0a66..5e56c8cd7a 100644 --- a/doc/developer/building-frr-for-freebsd11.rst +++ b/doc/developer/building-frr-for-freebsd11.rst @@ -11,12 +11,12 @@ FreeBSD 11 restrictions: Install required packages ------------------------- -Add packages: (Allow the install of the package managment tool if this +Add packages: (Allow the install of the package management tool if this is first package install and asked) .. code-block:: shell - pkg install git autoconf automake libtool gmake gawk json-c pkgconf \ + pkg install git autoconf automake libtool gmake json-c pkgconf \ bison flex py27-pytest c-ares python3 py36-sphinx texinfo Make sure there is no /usr/bin/flex preinstalled (and use the newly diff --git a/doc/developer/building-frr-for-freebsd9.rst b/doc/developer/building-frr-for-freebsd9.rst index 36492fb886..59241d1d13 100644 --- a/doc/developer/building-frr-for-freebsd9.rst +++ b/doc/developer/building-frr-for-freebsd9.rst @@ -11,14 +11,14 @@ FreeBSD 9 restrictions: Install required packages ------------------------- -Add packages: (Allow the install of the package managment tool if this +Add packages: (Allow the install of the package management tool if this is first package install and asked) :: - pkg install -y git autoconf automake libtool gmake gawk \ + pkg install -y git autoconf automake libtool gmake \ pkgconf texinfo json-c bison flex py27-pytest c-ares \ - python3 py-sphinx + python3 py-sphinx libexecinfo Make sure there is no /usr/bin/flex preinstalled (and use the newly installed in /usr/local/bin): (FreeBSD frequently provides a older flex diff --git a/doc/developer/building-frr-for-netbsd6.rst b/doc/developer/building-frr-for-netbsd6.rst index a042077fd0..49091c49b4 100644 --- a/doc/developer/building-frr-for-netbsd6.rst +++ b/doc/developer/building-frr-for-netbsd6.rst @@ -22,7 +22,7 @@ Add packages: :: - sudo pkg_add git autoconf automake libtool gmake gawk openssl \ + sudo pkg_add git autoconf automake libtool gmake openssl \ pkg-config json-c python27 py27-test python35 py-sphinx Install SSL Root Certificates (for git https access): diff --git a/doc/developer/building-frr-for-netbsd7.rst b/doc/developer/building-frr-for-netbsd7.rst index b65891916c..64c462a5c8 100644 --- a/doc/developer/building-frr-for-netbsd7.rst +++ b/doc/developer/building-frr-for-netbsd7.rst @@ -13,7 +13,7 @@ Install required packages :: - sudo pkgin install git autoconf automake libtool gmake gawk openssl \ + sudo pkgin install git autoconf automake libtool gmake openssl \ pkg-config json-c python27 py27-test python35 py-sphinx Install SSL Root Certificates (for git https access): diff --git a/doc/developer/building-frr-for-omnios.rst b/doc/developer/building-frr-for-omnios.rst index 416c89c667..ffc7a078e5 100644 --- a/doc/developer/building-frr-for-omnios.rst +++ b/doc/developer/building-frr-for-omnios.rst @@ -37,7 +37,7 @@ Add packages: library/idnkit/header-idnkit \ system/header \ system/library/math/header-math \ - git libtool gawk pkg-config + git libtool pkg-config Add additional Solaris packages: diff --git a/doc/developer/building-frr-for-openbsd6.rst b/doc/developer/building-frr-for-openbsd6.rst index 0f8d4d0f25..f307cacdfc 100644 --- a/doc/developer/building-frr-for-openbsd6.rst +++ b/doc/developer/building-frr-for-openbsd6.rst @@ -15,7 +15,7 @@ Add packages: :: pkg_add git autoconf-2.69p2 automake-1.15.1 libtool bison - pkg_add gmake gawk dejagnu openssl json-c py-test py-sphinx + pkg_add gmake json-c py-test py-sphinx libexecinfo Select Python2.7 as default (required for pytest) diff --git a/doc/developer/building-frr-for-openwrt.rst b/doc/developer/building-frr-for-openwrt.rst index b9be1b5226..5d8f82f27e 100644 --- a/doc/developer/building-frr-for-openwrt.rst +++ b/doc/developer/building-frr-for-openwrt.rst @@ -9,7 +9,7 @@ For Debian based distributions, run: :: sudo apt-get install git build-essential libssl-dev libncurses5-dev \ - unzip gawk zlib1g-dev subversion mercurial + unzip zlib1g-dev subversion mercurial For other environments, instructions can be found in the `official documentation @@ -63,10 +63,10 @@ Usage ----- Edit ``/usr/sbin/frr.init`` and add/remove the daemons name in section -``DAEMONS=`` or don't install unneded packages For example: zebra bgpd ldpd +``DAEMONS=`` or don't install unneeded packages For example: zebra bgpd ldpd isisd nhrpd ospfd ospf6d pimd ripd ripngd -Enable the serivce +Enable the service ^^^^^^^^^^^^^^^^^^ - ``service frr enable`` diff --git a/doc/developer/building-frr-for-ubuntu1404.rst b/doc/developer/building-frr-for-ubuntu1404.rst index b1eaf57e8d..6e2765c1c8 100644 --- a/doc/developer/building-frr-for-ubuntu1404.rst +++ b/doc/developer/building-frr-for-ubuntu1404.rst @@ -1,35 +1,30 @@ -Ubuntu 14.04LTS -=============================================== +Ubuntu 14.04 LTS +================ -- MPLS is not supported on ``Ubuntu 14.04`` with default kernel. MPLS - requires Linux Kernel 4.5 or higher (LDP can be built, but may have - limited use without MPLS) For an updated Ubuntu Kernel, see - http://kernel.ubuntu.com/~kernel-ppa/mainline/ - -Install required packages -------------------------- +This document describes installation from source. If you want to build a +``deb``, see :ref:`packaging-debian`. -Add packages: +Installing Dependencies +----------------------- -:: +.. code-block:: console + apt-get update apt-get install \ - git autoconf automake libtool make gawk libreadline-dev texinfo \ - dejagnu pkg-config libpam0g-dev libjson-c-dev bison flex python-pytest \ - libc-ares-dev python3-dev python3-sphinx install-info build-essential + git autoconf automake libtool make libreadline-dev texinfo \ + pkg-config libpam0g-dev libjson-c-dev bison flex python-pytest \ + libc-ares-dev python3-dev python3-sphinx install-info build-essential \ + libsnmp-dev perl .. include:: building-libyang.rst -Get FRR, compile it and install it (from Git) ---------------------------------------------- - -**This assumes you want to build and install FRR from source and not -using any packages** +Building & Installing FRR +------------------------- -Add frr groups and user +Add FRR user and groups ^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: console sudo groupadd -r -g 92 frr sudo groupadd -r -g 85 frrvty @@ -37,102 +32,104 @@ Add frr groups and user --gecos "FRR suite" --shell /sbin/nologin frr sudo usermod -a -G frrvty frr -Download Source, configure and compile it -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Compile +^^^^^^^ -(You may prefer different options on configure statement. These are just -an example.) +.. include:: include-compile.rst -:: +Install FRR configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - git clone https://github.com/frrouting/frr.git frr - cd frr - ./bootstrap.sh - ./configure \ - --prefix=/usr \ - --enable-exampledir=/usr/share/doc/frr/examples/ \ - --localstatedir=/var/run/frr \ - --sbindir=/usr/lib/frr \ - --sysconfdir=/etc/frr \ - --enable-multipath=64 \ - --enable-user=frr \ - --enable-group=frr \ - --enable-vty-group=frrvty \ - --enable-configfile-mask=0640 \ - --enable-logfile-mask=0640 \ - --enable-fpm \ - --with-pkg-git-version \ - --with-pkg-extra-version=-MyOwnFRRVersion - make - make check - sudo make install - -Create empty 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): :: - sudo install -m 755 -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 frr /dev/null /etc/frr/zebra.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/bgpd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ospfd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ospf6d.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/isisd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ripd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ripngd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/pimd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ldpd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/nhrpd.conf - 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) + # 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 +""""""""""""""""""""""" + +.. warning:: + + MPLS is not supported on Ubuntu 14.04 with the default kernel. MPLS requires + kernel 4.5 or higher. LDPD can be built, but may have limited use without + MPLS. For an updated Ubuntu Kernel, see + http://kernel.ubuntu.com/~kernel-ppa/mainline/ + +Ubuntu 18.04 ships with kernel 4.15. MPLS modules are present by default. To +enable, add the following lines to :file:`/etc/modules-load.d/modules.conf`: :: - # Uncomment the next line to enable packet forwarding for IPv4 - net.ipv4.ip_forward=1 + # 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 + +Enable MPLS Forwarding +"""""""""""""""""""""" - # 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 +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. -**Reboot** or use ``sysctl -p`` to apply the same config to the running -system +:: + + # 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 the init.d service ^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: console - sudo install -m 755 tools/frr /etc/init.d/frr - sudo install -m 644 tools/etc/frr/daemons /etc/frr/daemons - sudo install -m 644 -o frr -g frr tools/etc/frr/vtysh.conf /etc/frr/vtysh.conf + sudo install -m 755 tools/frr /etc/init.d/frr Enable daemons ^^^^^^^^^^^^^^ -| Edit ``/etc/frr/daemons`` and change the value from "no" to "yes" for - those daemons you want to start by systemd. -| For example. - -:: - - zebra=yes - bgpd=yes - ospfd=yes - ospf6d=yes - ripd=yes - ripngd=yes - isisd=yes +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 the init.d service ^^^^^^^^^^^^^^^^^^^^^^^^ -- /etc/init.d/frr start -- use ``/etc/init.d/frr status`` to check its status. +.. code-block:: console + + /etc/init.d/frr start + +Use ``/etc/init.d/frr status`` to check its status. diff --git a/doc/developer/building-frr-for-ubuntu1604.rst b/doc/developer/building-frr-for-ubuntu1604.rst index 0762e07eb9..a9a0a2f733 100644 --- a/doc/developer/building-frr-for-ubuntu1604.rst +++ b/doc/developer/building-frr-for-ubuntu1604.rst @@ -1,172 +1,134 @@ -Ubuntu 16.04LTS -=============================================== +Ubuntu 16.04 LTS +================ -- MPLS is not supported on ``Ubuntu 16.04`` with default kernel. MPLS - requires Linux Kernel 4.5 or higher (LDP can be built, but may have - limited use without MPLS) For an updated Ubuntu Kernel, see - http://kernel.ubuntu.com/~kernel-ppa/mainline/ - -Install required packages -------------------------- +This document describes installation from source. If you want to build a +``deb``, see :ref:`packaging-debian`. -Add packages: +Installing Dependencies +----------------------- -:: +.. code-block:: console + apt-get update apt-get install \ - git autoconf automake libtool make gawk libreadline-dev texinfo dejagnu \ + git autoconf automake libtool make libreadline-dev texinfo \ pkg-config libpam0g-dev libjson-c-dev bison flex python-pytest \ - libc-ares-dev python3-dev libsystemd-dev python-ipaddress \ - python3-sphinx install-info build-essential libsystemd-dev + libc-ares-dev python3-dev libsystemd-dev python-ipaddress python3-sphinx \ + install-info build-essential libsystemd-dev libsnmp-dev perl .. include:: building-libyang.rst -Get FRR, compile it and install it (from Git) ---------------------------------------------- - -**This assumes you want to build and install FRR from source and not -using any packages** +Building & Installing FRR +------------------------- -Add frr groups and user +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 + 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 -Download Source, configure and compile it -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Compile +^^^^^^^ -(You may prefer different options on configure statement. These are just -an example.) +.. include:: include-compile.rst -:: +Install FRR configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - git clone https://github.com/frrouting/frr.git frr - cd frr - ./bootstrap.sh - ./configure \ - --prefix=/usr \ - --enable-exampledir=/usr/share/doc/frr/examples/ \ - --localstatedir=/var/run/frr \ - --sbindir=/usr/lib/frr \ - --sysconfdir=/etc/frr \ - --enable-multipath=64 \ - --enable-user=frr \ - --enable-group=frr \ - --enable-vty-group=frrvty \ - --enable-configfile-mask=0640 \ - --enable-logfile-mask=0640 \ - --enable-fpm \ - --enable-systemd=yes \ - --with-pkg-git-version \ - --with-pkg-extra-version=-MyOwnFRRVersion - make - make check - sudo make install - -Create empty 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 - sudo install -m 755 -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 frr /dev/null /etc/frr/zebra.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/bgpd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ospfd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ospf6d.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/isisd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ripd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ripngd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/pimd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ldpd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/nhrpd.conf - 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) +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 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 - # 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. -Enable MPLS Forwarding (with Linux Kernel >= 4.5) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Add MPLS kernel modules +""""""""""""""""""""""" + +.. warning:: + + MPLS is not supported on Ubuntu 16.04 with the default kernel. MPLS requires + kernel 4.5 or higher. LDPD can be built, but may have limited use without + MPLS. For an updated Ubuntu Kernel, see + http://kernel.ubuntu.com/~kernel-ppa/mainline/ -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 -MPLS +Ubuntu 18.04 ships with kernel 4.15. MPLS modules are present by default. To +enable, add the following lines to :file:`/etc/modules-load.d/modules.conf`: :: - # 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 + # Load MPLS Kernel Modules + mpls_router + mpls_iptunnel -Add MPLS kernel modules -^^^^^^^^^^^^^^^^^^^^^^^ -Add the following lines to ``/etc/modules-load.d/modules.conf``: +And load the kernel modules on the running system: -:: +.. code-block:: console - # Load MPLS Kernel Modules - mpls-router - mpls-iptunnel + sudo modprobe mpls-router mpls-iptunnel -**Reboot** or use ``sysctl -p`` to apply the same config to the running -system +Enable MPLS Forwarding +"""""""""""""""""""""" -Install the systemd service (if rebooted from last step, change directory back to frr directory) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. :: - sudo install -m 644 tools/frr.service /etc/systemd/system/frr.service - sudo install -m 644 tools/etc/frr/daemons /etc/frr/daemons - sudo install -m 644 tools/etc/frr/frr.conf /etc/frr/frr.conf - sudo install -m 644 -o frr -g frr tools/etc/frr/vtysh.conf /etc/frr/vtysh.conf + # 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 -Enable daemons -^^^^^^^^^^^^^^ +Install service files +^^^^^^^^^^^^^^^^^^^^^ -| Edit ``/etc/frr/daemons`` and change the value from "no" to "yes" for - those daemons you want to start by systemd. -| For example. +.. code-block:: console -:: + sudo install -m 644 tools/frr.service /etc/systemd/system/frr.service + sudo systemctl enable frr - zebra=yes - bgpd=yes - ospfd=yes - ospf6d=yes - ripd=yes - ripngd=yes - isisd=yes +Enable daemons +^^^^^^^^^^^^^^ -Enable the systemd service -^^^^^^^^^^^^^^^^^^^^^^^^^^ +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``. -- systemctl enable frr +Start FRR +^^^^^^^^^ -Start the systemd service -^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console -- systemctl start frr -- use ``systemctl status frr`` to check its status. + systemctl start frr diff --git a/doc/developer/building-frr-for-ubuntu1804.rst b/doc/developer/building-frr-for-ubuntu1804.rst index 089d5a216a..1320bda577 100644 --- a/doc/developer/building-frr-for-ubuntu1804.rst +++ b/doc/developer/building-frr-for-ubuntu1804.rst @@ -1,55 +1,44 @@ Ubuntu 18.04 LTS ================ -Install dependencies --------------------- +This document describes installation from source. If you want to build a +``deb``, see :ref:`packaging-debian`. -Required packages -^^^^^^^^^^^^^^^^^ +Installing Dependencies +----------------------- -:: +.. code-block:: console + sudo apt update sudo apt-get install \ - git autoconf automake libtool make gawk libreadline-dev texinfo \ + git autoconf automake libtool make libreadline-dev texinfo \ pkg-config libpam0g-dev libjson-c-dev bison flex python-pytest \ - libc-ares-dev python3-dev libsystemd-dev python-ipaddress \ - python3-sphinx install-info build-essential libsystemd-dev + libc-ares-dev python3-dev libsystemd-dev python-ipaddress python3-sphinx \ + install-info build-essential libsystemd-dev libsnmp-dev perl .. include:: building-libyang.rst -Optional packages -^^^^^^^^^^^^^^^^^ - -Dependencies for additional functionality can be installed as-desired. - Protobuf -~~~~~~~~ +^^^^^^^^ -:: +.. code-block:: console - sudo apt-get install \ - protobuf-c-compiler \ - libprotobuf-c-dev + sudo apt-get install protobuf-c-compiler libprotobuf-c-dev ZeroMQ -~~~~~~ - -:: +^^^^^^ - sudo apt-get install \ - libzmq5 \ - libzmq3-dev +.. code-block:: console -Get FRR, compile it and install it (from Git) ---------------------------------------------- + sudo apt-get install libzmq5 libzmq3-dev -**This assumes you want to build and install FRR from source and not -using any packages** +Building & Installing FRR +------------------------- -Add frr groups and user +Add FRR user and groups ^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: console sudo groupadd -r -g 92 frr sudo groupadd -r -g 85 frrvty @@ -57,104 +46,29 @@ Add frr groups and user --gecos "FRR suite" --shell /sbin/nologin frr sudo usermod -a -G frrvty frr -Download source -^^^^^^^^^^^^^^^ - -:: - - git clone https://github.com/frrouting/frr.git frr - -Configure -^^^^^^^^^ -Options below are provided as an example. - -.. seealso:: *Installation* section of user guide - -.. code-block:: shell - - cd frr - ./bootstrap.sh - ./configure \ - --prefix=/usr \ - --enable-exampledir=/usr/share/doc/frr/examples/ \ - --localstatedir=/var/run/frr \ - --sbindir=/usr/lib/frr \ - --sysconfdir=/etc/frr \ - --enable-multipath=64 \ - --enable-user=frr \ - --enable-group=frr \ - --enable-vty-group=frrvty \ - --enable-configfile-mask=0640 \ - --enable-logfile-mask=0640 \ - --enable-fpm \ - --enable-systemd=yes \ - --with-pkg-git-version \ - --with-pkg-extra-version=-MyOwnFRRVersion - -If optional packages were installed, the associated feature may now be -enabled. - -.. option:: --enable-protobuf - -Enable support for protobuf transport - -.. option:: --enable-zeromq - -Enable support for ZeroMQ transport - Compile ^^^^^^^ -:: - - make - make check - sudo make install - -Create empty FRR configuration files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. include:: include-compile.rst -Although not strictly necessary, it's good practice to create empty -configuration files _before_ starting FRR. This assures that the permissions -are correct. If the files are not already present, FRR will create them. +Install FRR configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -It's also important to consider _which_ files to create. FRR supports writing -configuration to a monolithic file, :file:`/etc/frr/frr.conf`. +.. code-block:: console -.. seealso:: *VTYSH* section of user guide - -The presence of :file:`/etc/frr/frr.conf` on startup implicitly configures FRR -to ignore daemon-specific configuration files. - -Daemon-specific configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - sudo install -m 755 -o frr -g frr -d /var/log/frr + 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 frr /dev/null /etc/frr/zebra.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/bgpd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ospfd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ospf6d.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/isisd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ripd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ripngd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/pimd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ldpd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/nhrpd.conf - -Monolithic configuration -~~~~~~~~~~~~~~~~~~~~~~~~ + 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 +^^^^^^^^^^^^^ - sudo install -m 755 -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 frr /dev/null /etc/frr/frr.conf - -Enable IPv4 & IPv6 forwarding -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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): @@ -169,8 +83,10 @@ other settings): # 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 18.04 ships with kernel 4.15. MPLS modules are present by default. To enable, add the following lines to :file:`/etc/modules-load.d/modules.conf`: @@ -181,10 +97,15 @@ enable, add the following lines to :file:`/etc/modules-load.d/modules.conf`: mpls_router mpls_iptunnel -Reboot or use ``sysctl -p`` to apply the same config to the running system. + +And load the kernel modules on the running system: + +.. code-block:: console + + sudo modprobe mpls-router mpls-iptunnel 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. @@ -197,48 +118,24 @@ equal to :file:`net.mpls.conf.eth0.input` for each interface used with MPLS. net.mpls.conf.eth2.input=1 net.mpls.platform_labels=100000 -Install the systemd service -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Install service files +^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: console sudo install -m 644 tools/frr.service /etc/systemd/system/frr.service - sudo install -m 644 tools/etc/frr/daemons /etc/frr/daemons - sudo install -m 644 tools/etc/frr/frr.conf /etc/frr/frr.conf - sudo install -m 644 -o frr -g frr tools/etc/frr/vtysh.conf /etc/frr/vtysh.conf + sudo systemctl enable frr Enable daemons ^^^^^^^^^^^^^^ -Edit ``/etc/frr/daemons`` and change the value from "no" to "yes" for those -daemons you want to start by systemd. For example: - -:: - - zebra=yes - bgpd=yes - ospfd=yes - ospf6d=yes - ripd=yes - ripngd=yes - isisd=yes - -Enable the systemd service -^^^^^^^^^^^^^^^^^^^^^^^^^^ +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``. -Enabling the systemd service causes FRR to be started upon boot. To enable it, -use the following command: - -.. code-block:: shell - - systemctl enable frr - -Start the systemd service -^^^^^^^^^^^^^^^^^^^^^^^^^ +Start FRR +^^^^^^^^^ .. code-block:: shell systemctl start frr - -After starting the service, you can use ``systemctl status frr`` to check its -status. diff --git a/doc/developer/building-libyang.rst b/doc/developer/building-libyang.rst index c45c294b75..41fe09e322 100644 --- a/doc/developer/building-libyang.rst +++ b/doc/developer/building-libyang.rst @@ -1,57 +1,55 @@ -The libyang library can be installed from third-party packages available `here -<https://ci1.netdef.org/browse/LIBYANG-YANGRELEASE/latestSuccessful/artifact>`_. +FRR depends on the relatively new ``libyang`` library to provide YANG/NETCONF +support. Unfortunately, most distributions do not yet offer a ``libyang`` +package from their repositories. Therefore we offer two options to install this +library. -Note: the libyang dev/devel packages need to be installed in addition -to the libyang core package in order to build FRR successfully. +**Option 1: Binary Install** + +The FRR project builds binary ``libyang`` packages, which we offer for download +`here <https://ci1.netdef.org/browse/LIBYANG-YANGRELEASE/latestSuccessful/artifact>`_. .. warning:: - libyang ABI version 0.16.74 or newer will be required to build FRR in the - near future since it significantly eases build and installation - considerations. "0.16-r3" is equal to 0.16.105 and will work, "0.16-r2" - is equal to 0.16.52 and will stop working. The CI artifacts will be - updated shortly. -For example, for CentOS 7.x: + ``libyang`` version 0.16.74 or newer is required to build FRR. + +.. note:: -.. code-block:: shell + The ``libyang`` development packages need to be installed in addition to the + libyang core package in order to build FRR successfully. Make sure to + download and install those from the link above alongside the binary + packages. - wget https://ci1.netdef.org/artifact/LIBYANG-YANGRELEASE/shared/build-1/CentOS-7-x86_64-Packages/libyang-0.16.46-0.x86_64.rpm - wget https://ci1.netdef.org/artifact/LIBYANG-YANGRELEASE/shared/build-1/CentOS-7-x86_64-Packages/libyang-devel-0.16.46-0.x86_64.rpm - sudo rpm -i libyang-0.16.46-0.x86_64.rpm libyang-devel-0.16.46-0.x86_64.rpm + Depending on your platform, you may also need to install the PCRE + development package. Typically this is ``libpcre-dev`` or ``pcre-devel``. -or Ubuntu 18.04: +.. note:: -.. code-block:: shell + For Debian-based systems, the official ``libyang`` package requires recent + versions of ``swig`` (3.0.12) and ``debhelper`` (11) which are only + available in Debian buster (10). However, ``libyang`` packages built on + Debian buster can be installed on both Debian jessie (8) and Debian stretch + (9), as well as various Ubuntu systems. The ``python3-yang`` package will + not work, but the other packages (``libyang-dev`` is the one needed for FRR) + will. - wget https://ci1.netdef.org/artifact/LIBYANG-YANGRELEASE/shared/build-1/Ubuntu-18.04-x86_64-Packages/libyang-dev_0.16.46_amd64.deb - wget https://ci1.netdef.org/artifact/LIBYANG-YANGRELEASE/shared/build-1/Ubuntu-18.04-x86_64-Packages/libyang_0.16.46_amd64.deb - sudo apt install libpcre3-dev - sudo dpkg -i libyang-dev_0.16.46_amd64.deb libyang_0.16.46_amd64.deb +**Option 2: Source Install** .. note:: - For Debian-based systems, the official libyang package requires recent - versions of swig (3.0.12) and debhelper (11) which are only available in - Debian buster (10). However, libyang packages built on Debian buster can - be installed on both Debian jessie (8) and Debian stretch (9), as well as - various Ubuntu systems. The python3-yang package will not work, but the - other packages (libyang-dev is the one needed for FRR) will. -Alternatively, libyang can be built and installed manually by following -the steps below: + Ensure that the `libyang build requirements + <https://github.com/CESNET/libyang/blob/master/README.md#build-requirements>`_ + are met before continuing. Usually this entails installing ``cmake`` and + ``libpcre-dev`` or ``pcre-devel``. -.. code-block:: shell +.. code-block:: console - git clone https://github.com/opensourcerouting/libyang + git clone https://github.com/CESNET/libyang.git cd libyang - git checkout -b tmp origin/tmp mkdir build; cd build - cmake -DENABLE_LYD_PRIV=ON .. + cmake -DENABLE_LYD_PRIV=ON -DCMAKE_INSTALL_PREFIX:PATH=/usr .. make sudo make install When building libyang on CentOS 6, it's also necessary to pass the ``-DENABLE_CACHE=OFF`` parameter to cmake. -Note: please check the `libyang build requirements -<https://github.com/CESNET/libyang/blob/master/README.md#build-requirements>`_ -first. diff --git a/doc/developer/building.rst b/doc/developer/building.rst index 96559b0abe..c13fb10ffc 100644 --- a/doc/developer/building.rst +++ b/doc/developer/building.rst @@ -12,7 +12,7 @@ Building FRR building-frr-for-centos7 building-frr-for-debian8 building-frr-for-debian9 - building-frr-for-fedora24 + building-frr-for-fedora building-frr-for-freebsd10 building-frr-for-freebsd11 building-frr-for-freebsd9 diff --git a/doc/developer/conf.py b/doc/developer/conf.py index af8673e5fa..9acfab739a 100644 --- a/doc/developer/conf.py +++ b/doc/developer/conf.py @@ -131,7 +131,7 @@ language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build', 'building-libyang.rst', 'topotests-snippets.rst'] +exclude_patterns = ['_build', 'building-libyang.rst', 'topotests-snippets.rst', 'include-compile.rst'] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/doc/developer/hooks.rst b/doc/developer/hooks.rst index 4140a0d171..10fe6b9c43 100644 --- a/doc/developer/hooks.rst +++ b/doc/developer/hooks.rst @@ -6,7 +6,7 @@ Hooks Libfrr provides type-safe subscribable hook points where other pieces of code can add one or more callback functions. "type-safe" in this case applies to the function pointers used for subscriptions. The -implementations checks (at compile-time) wheter a callback to be added has +implementations checks (at compile-time) whether a callback to be added has the appropriate function signature (parameters) for the hook. Example: diff --git a/doc/developer/include-compile.rst b/doc/developer/include-compile.rst new file mode 100644 index 0000000000..0ff0ae3ffe --- /dev/null +++ b/doc/developer/include-compile.rst @@ -0,0 +1,37 @@ +Clone the FRR git repo and use the included ``configure`` script to configure +FRR's build time options to your liking. The full option listing can be +obtained by running ``./configure -h``. The options shown below are examples. + +.. note:: + + If your platform uses ``systemd``, please make sure to add + ``--enable-systemd=yes`` to your configure options. + +.. code-block:: console + + git clone https://github.com/frrouting/frr.git frr + cd frr + ./bootstrap.sh + ./configure \ + --prefix=/usr \ + --includedir=\${prefix}/include \ + --enable-exampledir=\${prefix}/share/doc/frr/examples \ + --bindir=\${prefix}/bin \ + --sbindir=\${prefix}/lib/frr \ + --libdir=\${prefix}/lib/frr \ + --libexecdir=\${prefix}/lib/frr \ + --localstatedir=/var/run/frr \ + --sysconfdir=/etc/frr \ + --with-moduledir=\${prefix}/lib/frr/modules \ + --with-libyang-pluginsdir=\${prefix}/lib/frr/libyang_plugins \ + --enable-configfile-mask=0640 \ + --enable-logfile-mask=0640 \ + --enable-snmp=agentx \ + --enable-multipath=64 \ + --enable-user=frr \ + --enable-group=frr \ + --enable-vty-group=frrvty \ + --with-pkg-git-version \ + --with-pkg-extra-version=-MyOwnFRRVersion + make + sudo make install diff --git a/doc/developer/logging.rst b/doc/developer/logging.rst index 4338d900e6..1dc1885158 100644 --- a/doc/developer/logging.rst +++ b/doc/developer/logging.rst @@ -18,7 +18,7 @@ maybe by a syslog collector from all routers.) Therefore, anything that needs to get the user in the loop—and only these things—are warnings or errors. -Note that this doesn't neccessarily mean the user needs to fix something in +Note that this doesn't necessarily mean the user needs to fix something in the FRR instance. It also includes when we detect something else needs fixing, for example another router, the system we're running on, or the configuration. The common point is that the user should probably do diff --git a/doc/developer/memtypes.rst b/doc/developer/memtypes.rst index 43cbe002cf..153131bab9 100644 --- a/doc/developer/memtypes.rst +++ b/doc/developer/memtypes.rst @@ -3,7 +3,7 @@ Memtypes ======== -FRR includes wrappers arround ``malloc()`` and ``free()`` that count the number +FRR includes wrappers around ``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 diff --git a/doc/developer/ospf-api.rst b/doc/developer/ospf-api.rst index 90fc52efd0..f4f38a63e9 100644 --- a/doc/developer/ospf-api.rst +++ b/doc/developer/ospf-api.rst @@ -284,7 +284,7 @@ Each message begins with the following header: The message type field can take one of the following values: +-------------------------------+---------+ -| Messages to OSPF deamon | Value | +| Messages to OSPF daemon | Value | +===============================+=========+ | MSG\_REGISTER\_OPAQUETYPE | 1 | +-------------------------------+---------+ @@ -300,7 +300,7 @@ The message type field can take one of the following values: +-------------------------------+---------+ +-----------------------------+---------+ -| Messages from OSPF deamon | Value | +| Messages from OSPF daemon | Value | +=============================+=========+ | MSG\_REPLY | 10 | +-----------------------------+---------+ diff --git a/doc/developer/ospf-sr.rst b/doc/developer/ospf-sr.rst index 4a673b155b..23bc803d76 100644 --- a/doc/developer/ospf-sr.rst +++ b/doc/developer/ospf-sr.rst @@ -31,7 +31,7 @@ Implementation details Concepts ^^^^^^^^ -Segment Routing used 3 differents OPAQUE LSA in OSPF to carry the various +Segment Routing used 3 different OPAQUE LSA in OSPF to carry the various information: * **Router Information:** flood the Segment Routing capabilities of the node. @@ -40,7 +40,7 @@ information: * **Extended Link:** flood the Adjaceny and Lan Adjacency Segment Identifier * **Extended Prefix:** flood the Prefix Segment Identifier -The implementation follow previous TE and Router Information codes. It used the +The implementation follows previous TE and Router Information codes. It used the OPAQUE LSA functions defined in ospf_opaque.[c,h] as well as the OSPF API. This latter is mandatory for the implementation as it provides the Callback to Segment Routing functions (see below) when an Extended Link / Prefix or Router @@ -71,7 +71,7 @@ The figure below shows the relation between the various files: (4.0.0.0), Extended Prefix (7.0.0.X) and Link (8.0.0.X) by ospf_ri.c, respectively ospf_ext.c. * ospf_ri.c send back to ospf_sr.c received Router Information LSA and update - Self Router Information LSA with paramters provided by ospf_sr.c i.e. SRGB + Self Router Information LSA with parameters provided by ospf_sr.c i.e. SRGB and MSD. It use ospf_opaque.c functions to send/received these Opaque LSAs. * ospf_ext.c send back to ospf_sr.c received Extended Prefix and Link Opaque LSA and send self Extended Prefix and Link Opaque LSA through ospf_opaque.c @@ -129,8 +129,8 @@ Opaque LSA it is the `ospf_opaque_lsa_install_hook()`. For deletion, it is Note that incoming LSA which is already present in the LSDB will be inserted after the old instance of this LSA remove from the LSDB. Thus, after the first time, each incoming LSA will trigger a `delete` following by an `install`. This -is not very helpfull to handle real LSA deletion. In fact, LSA deletion is done -by Flushing LSA i.e. flood LSA after seting its age to MAX_AGE. Then, a garbage +is not very helpful to handle real LSA deletion. In fact, LSA deletion is done +by Flushing LSA i.e. flood LSA after setting its age to MAX_AGE. Then, a garbage function has the role to remove all LSA with `age == MAX_AGE` in the LSDB. So, to handle LSA Flush, the best is to look to the LSA age to determine if it is an installation or a future deletion i.e. the flushed LSA is first store in the @@ -144,7 +144,7 @@ introduced. When this command is activated, function `ospf_router_info_update_sr()` is called to indicate to Router Information process that Segment Routing TLVs must be flood. Same function is called to modify the Segment Routing Global Block (SRGB) and Maximum Stack Depth (MSD) -TLV. Only Shortest Path First (SPF) Algorithm is supported, so no possiblity +TLV. Only Shortest Path First (SPF) Algorithm is supported, so no possibility to modify this TLV is offer by the code. When Opaque LSA Tyep 4 i.e. Router Information are stored in LSDB, function @@ -159,8 +159,8 @@ Extended Link Prefix LSAs ^^^^^^^^^^^^^^^^^^^^^^^^^ Like for Router Information, Segment Routing is activate at the Extended -Link/Prefix level with new `segment-routing on` command. This trigger -automtically the flooding of Extended Link LSA for all ospf interface where +Link/Prefix level with new `segment-routing on` command. This triggers +automatically the flooding of Extended Link LSA for all ospf interfaces where adjacency is full. For Extended Prefix LSA, the new CLI command `segment-routing prefix ...` will trigger the flooding of Prefix SID TLV/SubTLVs. @@ -255,7 +255,7 @@ The first segment-routing statement enable it. The Second one set the SRGB, third line the MSD and finally, set the Prefix SID index for a given prefix. Note that only prefix of Loopback interface could be configured with a Prefix SID. It is possible to add `no-php-flag` at the end of the prefix command to -disbale Penultimate Hop Popping. This advertises peers that they MUST NOT pop +disable Penultimate Hop Popping. This advertises to peers that they MUST NOT pop the MPLS label prior to sending the packet. Known limitations diff --git a/doc/developer/packaging-debian.rst b/doc/developer/packaging-debian.rst index c660f98680..b57286d5a1 100644 --- a/doc/developer/packaging-debian.rst +++ b/doc/developer/packaging-debian.rst @@ -1,3 +1,5 @@ +.. _packaging-debian: + Packaging Debian ================ diff --git a/doc/developer/packaging-redhat.rst b/doc/developer/packaging-redhat.rst new file mode 100644 index 0000000000..f6b9931156 --- /dev/null +++ b/doc/developer/packaging-redhat.rst @@ -0,0 +1,85 @@ +.. _packaging-redhat: + +Packaging Red Hat +================= + +Tested on CentOS 6, CentOS 7 and Fedora 24. + +1. On CentOS 6, refer to :ref:`building-centos6` for details on installing + sufficiently up-to-date package versions to enable building FRR. + + Newer automake/autoconf/bison is only needed to build the RPM and is **not** + needed to install the binary RPM package. + +2. Install the build dependencies for your platform. Refer to the + platform-specific build documentation on how to do this. + +3. Install the following additional packages:: + + yum install rpm-build net-snmp-devel pam-devel libcap-devel + + If your platform uses systemd:: + + yum install systemd-devel + + If ``yum`` is not present on your system, use ``dnf`` instead. + +3. Checkout FRR:: + + git clone https://github.com/frrouting/frr.git frr + +4. Run Bootstrap and make distribution tar.gz:: + + cd frr + ./bootstrap.sh + ./configure --with-pkg-extra-version=-MyRPMVersion SPHINXBUILD=sphinx-build2.7 + make dist + + .. note:: + + The only ``configure`` option respected when building RPMs is + ``--with-pkg-extra-version``. + +5. Create RPM directory structure and populate with sources:: + + mkdir rpmbuild + mkdir rpmbuild/SOURCES + mkdir rpmbuild/SPECS + cp redhat/*.spec rpmbuild/SPECS/ + cp frr*.tar.gz rpmbuild/SOURCES/ + +6. Edit :file:`rpm/SPECS/frr.spec` with configuration as needed. + + Look at the beginning of the file and adjust the following parameters to + enable or disable features as required:: + + ############### FRRouting (FRR) configure options ################# + # with-feature options + %{!?with_pam: %global with_pam 0 } + %{!?with_ospfclient: %global with_ospfclient 1 } + %{!?with_ospfapi: %global with_ospfapi 1 } + %{!?with_irdp: %global with_irdp 1 } + %{!?with_rtadv: %global with_rtadv 1 } + %{!?with_ldpd: %global with_ldpd 1 } + %{!?with_nhrpd: %global with_nhrpd 1 } + %{!?with_eigrp: %global with_eigrpd 1 } + %{!?with_shared: %global with_shared 1 } + %{!?with_multipath: %global with_multipath 256 } + %{!?frr_user: %global frr_user frr } + %{!?vty_group: %global vty_group frrvty } + %{!?with_fpm: %global with_fpm 0 } + %{!?with_watchfrr: %global with_watchfrr 1 } + %{!?with_bgp_vnc: %global with_bgp_vnc 0 } + %{!?with_pimd: %global with_pimd 1 } + %{!?with_rpki: %global with_rpki 0 } + +7. Build the RPM:: + + rpmbuild --define "_topdir `pwd`/rpmbuild" -ba rpmbuild/SPECS/frr.spec + + If building with RPKI, then download and install the additional RPKI + packages from + https://ci1.netdef.org/browse/RPKI-RTRLIB/latestSuccessful/artifact + +If all works correctly, then you should end up with the RPMs under +:file:`rpmbuild/RPMS` and the source RPM under :file:`rpmbuild/SRPMS`. diff --git a/doc/developer/packaging.rst b/doc/developer/packaging.rst index 27e6e155fb..b174a9660c 100644 --- a/doc/developer/packaging.rst +++ b/doc/developer/packaging.rst @@ -7,3 +7,4 @@ Packaging maintainer-release-build packaging-debian + packaging-redhat diff --git a/doc/developer/subdir.am b/doc/developer/subdir.am index d769913674..7ae48881ab 100644 --- a/doc/developer/subdir.am +++ b/doc/developer/subdir.am @@ -5,13 +5,12 @@ dev_RSTFILES = \ doc/developer/bgp-typecodes.rst \ doc/developer/bgpd.rst \ - doc/developer/building-frr-for-openwrt.rst \ doc/developer/building-frr-for-alpine.rst \ doc/developer/building-frr-for-centos6.rst \ doc/developer/building-frr-for-centos7.rst \ doc/developer/building-frr-for-debian8.rst \ doc/developer/building-frr-for-debian9.rst \ - doc/developer/building-frr-for-fedora24.rst \ + doc/developer/building-frr-for-fedora.rst \ doc/developer/building-frr-for-freebsd10.rst \ doc/developer/building-frr-for-freebsd11.rst \ doc/developer/building-frr-for-freebsd9.rst \ @@ -19,6 +18,7 @@ dev_RSTFILES = \ doc/developer/building-frr-for-netbsd7.rst \ doc/developer/building-frr-for-omnios.rst \ doc/developer/building-frr-for-openbsd6.rst \ + doc/developer/building-frr-for-openwrt.rst \ doc/developer/building-frr-for-ubuntu1404.rst \ doc/developer/building-frr-for-ubuntu1604.rst \ doc/developer/building-frr-for-ubuntu1804.rst \ @@ -27,6 +27,7 @@ dev_RSTFILES = \ doc/developer/cli.rst \ doc/developer/conf.py \ doc/developer/hooks.rst \ + doc/developer/include-compile.rst \ doc/developer/index.rst \ doc/developer/library.rst \ doc/developer/logging.rst \ @@ -37,8 +38,9 @@ dev_RSTFILES = \ doc/developer/ospf-api.rst \ doc/developer/ospf-sr.rst \ doc/developer/ospf.rst \ - doc/developer/packaging.rst \ doc/developer/packaging-debian.rst \ + doc/developer/packaging-redhat.rst + doc/developer/packaging.rst \ doc/developer/testing.rst \ doc/developer/topotests-snippets.rst \ doc/developer/topotests.rst \ diff --git a/doc/developer/topotests-snippets.rst b/doc/developer/topotests-snippets.rst index 649229b433..fb3c928a77 100644 --- a/doc/developer/topotests-snippets.rst +++ b/doc/developer/topotests-snippets.rst @@ -48,17 +48,17 @@ A sample of this snippet in a test can be found `here Interacting with equipment ^^^^^^^^^^^^^^^^^^^^^^^^^^ -You might want to interact with the topology equipments during the tests and +You might want to interact with the topology equipment during the tests and there are different ways to do so. Notes: -1. When using the Topogen API, all the equipments code derive from ``Topogear`` +1. When using the Topogen API, all the equipment code derives from ``Topogear`` (`lib/topogen.py <lib/topogen.py>`__). If you feel brave you can look by - yourself how the abstractions that will be mentioned here works. + yourself how the abstractions that will be mentioned here work. 2. When not using the ``Topogen`` API there is only one way to interact with - the equipments, which is by calling the ``mininet`` API functions directly + the equipment, which is by calling the ``mininet`` API functions directly to spawn commands. Interacting with the Linux sandbox @@ -149,7 +149,7 @@ Translating vtysh JSON output into Python structures: .. note:: - ``vtysh_(multi)cmd`` is only available for router type of equipments. + ``vtysh_(multi)cmd`` is only available for router types of equipment. Invoking mininet CLI ^^^^^^^^^^^^^^^^^^^^ @@ -195,7 +195,7 @@ Loading JSON from a file: Comparing JSON output ^^^^^^^^^^^^^^^^^^^^^ -After obtaining JSON output formated with Python data structures, you may use +After obtaining JSON output formatted with Python data structures, you may use it to assert a minimalist schema: .. code:: py diff --git a/doc/developer/topotests.rst b/doc/developer/topotests.rst index aa06c8dffd..605b9c9a0c 100644 --- a/doc/developer/topotests.rst +++ b/doc/developer/topotests.rst @@ -151,7 +151,7 @@ Collect Memory Leak Information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FRR processes have the capabilities to report remaining memory allocations upon -exit. To enable the reporting of the memory, define an enviroment variable +exit. To enable the reporting of the memory, define an environment variable ``TOPOTESTS_CHECK_MEMLEAK`` with the file prefix, i.e.:: export TOPOTESTS_CHECK_MEMLEAK="/home/mydir/memleak_" @@ -410,7 +410,7 @@ Defining the Topology The first step to write a new test is to define the topology. This step can be done in many ways, but the recommended is to use Graphviz to generate a drawing of the topology. It allows us to see the topology graphically and to see the -names of equipments, links and addresses. +names of equipment, links and addresses. Here is an example of Graphviz dot file that generates the template topology :file:`tests/topotests/example-test/test_template.dot` (the inlined code might diff --git a/doc/developer/vtysh.rst b/doc/developer/vtysh.rst index 4a52eb0544..160676a7b1 100644 --- a/doc/developer/vtysh.rst +++ b/doc/developer/vtysh.rst @@ -43,7 +43,7 @@ simplifying the output. This is discussed in :ref:`vtysh-configuration`. Command Extraction ------------------ -When VTYSH is a built, a Perl script named :file:`extract.pl` searches the FRR +When VTYSH is built, a Perl script named :file:`extract.pl` searches the FRR codebase looking for ``DEFUN``'s. It extracts these ``DEFUN``'s, transforms them into ``DEFSH``'s and appends them to ``vtysh_cmd.c``. Each ``DEFSH`` contains the name of the command plus ``_vtysh``, as well as a flag that @@ -167,7 +167,7 @@ Protocol VTYSH communicates with FRR daemons by way of domain socket. Each daemon creates its own socket, typically in :file:`/var/run/frr/<daemon>.vty`. The protocol is very simple. In the VTYSH to daemon direction, messages are simply -NULL-terminated strings, whose content are CLI commands. Here is a typical +NUL-terminated strings, whose content are CLI commands. Here is a typical message from VTYSH to a daemon: :: @@ -178,7 +178,7 @@ message from VTYSH to a daemon: 00000010: 6c0a 00 l.. -The response format has some more data in it. First is a NULL-terminated string +The response format has some more data in it. First is a NUL-terminated string containing the plaintext response, which is just the output of the command that was sent in the request. This is displayed to the user. The plaintext response is followed by 3 null marker bytes, followed by a 1-byte status code that diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index 1bb0886fd5..b3b3a47cb0 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -99,9 +99,14 @@ Bugfix releases are made as needed at 1 month intervals until the next ``MAJOR.MINOR`` release branch is pulled. Depending on the severity of the bugs, bugfix releases may occur sooner. -Bugfixes are applied to the two most recent releases. Security fixes are -backported to all releases less than or equal to at least one year old. Security -fixes may also be backported to older releases depending on severity. +Bugfixes are applied to the two most recent releases. However, backporting of bug +fixes to older than the two most recent releases will not be prevented, if acked +under the classical development workflow applying for a pull request. + +Security fixes are backported to all releases less than or equal to at least one +year old. Security fixes may also be backported to older releases depending on +severity. + Long term support branches ( LTS ) ----------------------------------------- @@ -128,7 +133,7 @@ branch is required. The work can be shared by multiple people. In all cases, the must be at least one person that is in charge of the maintenance branch. The person on people responsible for a maintenance branch must be a FRR maintainer. Note that they may choose to abandon support for the maintenance branch at any time. If -noone takes over the responsibility of the LTS branch, then the support will be +no one takes over the responsibility of the LTS branch, then the support will be discontinued. The LTS branch duties are the following ones: @@ -371,7 +376,7 @@ system in which submissions from an individual representing one company should be merged by someone unaffiliated with that company. Guidelines for code review -"""""""""""""""""""""""""" +-------------------------- - As a rule of thumb, the depth of the review should be proportional to the scope and / or impact of the patch. |