mirror of https://github.com/FRRouting/frr.git
600 lines
18 KiB
ReStructuredText
600 lines
18 KiB
ReStructuredText
.. index::
|
|
single: How to install FRR
|
|
single: Installing FRR
|
|
single: Building FRR
|
|
|
|
.. _installation:
|
|
|
|
Installation
|
|
============
|
|
|
|
This section covers the basics of building, installing and setting up FRR.
|
|
|
|
|
|
From Packages
|
|
-------------
|
|
|
|
The project publishes packages for Red Hat, Centos, Debian and Ubuntu on the
|
|
`GitHub releases <https://github.com/FRRouting/frr/releases>`_. page. External
|
|
contributors offer packages for many other platforms including \*BSD, Alpine,
|
|
Gentoo, Docker, and others. There is currently no documentation on how to use
|
|
those but we hope to add it soon.
|
|
|
|
From Snapcraft
|
|
--------------
|
|
|
|
In addition to traditional packages the project also builds and publishes
|
|
universal Snap images, available at https://snapcraft.io/frr.
|
|
|
|
From Source
|
|
-----------
|
|
|
|
Building FRR from source is the best way to ensure you have the latest features
|
|
and bug fixes. Details for each supported platform, including dependency
|
|
package listings, permissions, and other gotchas, are in the `developer's
|
|
documentation
|
|
<http://docs.frrouting.org/projects/dev-guide/en/latest/building.html>`_. This
|
|
section provides a brief overview on the process.
|
|
|
|
|
|
Getting the Source
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
FRR's source is available on the project
|
|
`GitHub page <https://github.com/FRRouting/frr>`_.
|
|
|
|
.. code-block:: shell
|
|
|
|
git clone https://github.com/FRRouting/frr.git
|
|
|
|
When building from Git there are several branches to choose from. The
|
|
``master`` branch is the primary development branch. It should be considered
|
|
unstable. Each release has its own branch named ``stable/X.X``, where ``X.X``
|
|
is the release version.
|
|
|
|
In addition, release tarballs are published on the GitHub releases page
|
|
`here <https://github.com/FRRouting/frr/releases>`_.
|
|
|
|
|
|
.. index::
|
|
single: Configuration options
|
|
single: Options for configuring
|
|
single: Build options
|
|
single: Distribution configuration
|
|
single: Options to `./configure`
|
|
|
|
.. _build-configuration:
|
|
|
|
Build Configuration
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
FRR has an excellent configure script which automatically detects most host
|
|
configurations. There are several additional configure options to customize the
|
|
build to include or exclude specific features and dependencies.
|
|
|
|
First, update the build system. Change into your FRR source directory and issue:
|
|
|
|
.. code-block:: shell
|
|
|
|
./bootstrap.sh
|
|
|
|
This will install any missing build scripts and update the Autotools
|
|
configuration. Once this is done you can move on to choosing your configuration
|
|
options from the list below.
|
|
|
|
.. _frr-configuration:
|
|
|
|
.. program:: configure
|
|
|
|
.. option:: --enable-tcmalloc
|
|
|
|
Enable the alternate malloc library. In some cases this is faster and more efficient,
|
|
in some cases it is not.
|
|
|
|
.. option:: --disable-doc
|
|
|
|
Do not build any documentation, including this one.
|
|
|
|
.. option:: --enable-doc-html
|
|
|
|
From the documentation build html docs as well in addition to the normal output.
|
|
|
|
.. option:: --disable-zebra
|
|
|
|
Do not build zebra daemon. This generally only be useful in a scenario where
|
|
you are building bgp as a standalone server.
|
|
|
|
.. option:: --disable-ripd
|
|
|
|
Do not build ripd.
|
|
|
|
.. option:: --disable-ripngd
|
|
|
|
Do not build ripngd.
|
|
|
|
.. option:: --disable-ospfd
|
|
|
|
Do not build ospfd.
|
|
|
|
.. option:: --disable-ospf6d
|
|
|
|
Do not build ospf6d.
|
|
|
|
.. option:: --disable-bgpd
|
|
|
|
Do not build bgpd.
|
|
|
|
.. option:: --disable-ldpd
|
|
|
|
Do not build ldpd.
|
|
|
|
.. option:: --disable-nhrpd
|
|
|
|
Do not build nhrpd.
|
|
|
|
.. option:: --disable-eigrpd
|
|
|
|
Do not build eigrpd.
|
|
|
|
.. option:: --disable-babeld
|
|
|
|
Do not build babeld.
|
|
|
|
.. option:: --disable-watchfrr
|
|
|
|
Do not build watchfrr. Watchfrr is used to integrate daemons into startup/shutdown
|
|
software available on your machine. This is needed for systemd integration, if you
|
|
disable watchfrr you cannot have any systemd integration.
|
|
|
|
.. option:: --enable-werror
|
|
|
|
Build with all warnings converted to errors as a compile option. This
|
|
is recommended for developers only.
|
|
|
|
.. option:: --disable-pimd
|
|
|
|
Turn off building of pimd. On some BSD platforms pimd will not build properly due
|
|
to lack of kernel support.
|
|
|
|
.. option:: --disable-vrrpd
|
|
|
|
Turn off building of vrrpd. Linux is required for vrrpd support;
|
|
other platforms are not supported.
|
|
|
|
.. option:: --disable-pbrd
|
|
|
|
Turn off building of pbrd. This daemon currently requires linux in order to function
|
|
properly.
|
|
|
|
.. option:: --enable-sharpd
|
|
|
|
Turn on building of sharpd. This daemon facilitates testing of FRR and can also
|
|
be used as a quick and easy route generator.
|
|
|
|
.. option:: --disable-staticd
|
|
|
|
Do not build staticd. This daemon is necessary if you want static routes.
|
|
|
|
.. option:: --disable-bfdd
|
|
|
|
Do not build bfdd.
|
|
|
|
.. option:: --disable-bgp-announce
|
|
|
|
Make *bgpd* which does not make bgp announcements at all. This
|
|
feature is good for using *bgpd* as a BGP announcement listener.
|
|
|
|
.. option:: --disable-bgp-vnc
|
|
|
|
Turn off bgpd's ability to use VNC.
|
|
|
|
.. option:: --disable-bgp-bmp
|
|
|
|
Turn off BGP BMP support
|
|
|
|
.. option:: --enable-datacenter
|
|
|
|
This option is deprecated as it is superseded by the `-F` (profile) command
|
|
line option which allows adjusting the setting at startup rather than
|
|
compile time.
|
|
|
|
Enable system defaults to work as if in a Data Center. See defaults.h
|
|
for what is changed by this configure option.
|
|
|
|
.. option:: --enable-snmp
|
|
|
|
Enable SNMP support. By default, SNMP support is disabled.
|
|
|
|
.. option:: --disable-ospfapi
|
|
|
|
Disable support for OSPF-API, an API to interface directly with ospfd.
|
|
OSPF-API is enabled if --enable-opaque-lsa is set.
|
|
|
|
.. option:: --disable-ospfclient
|
|
|
|
Disable installation of the python ospfclient and building of the example
|
|
OSPF-API client.
|
|
|
|
.. option:: --disable-isisd
|
|
|
|
Do not build isisd.
|
|
|
|
.. option:: --disable-fabricd
|
|
|
|
Do not build fabricd.
|
|
|
|
.. option:: --enable-isis-topology
|
|
|
|
Enable IS-IS topology generator.
|
|
|
|
.. option:: --enable-realms
|
|
|
|
Enable the support of Linux Realms. Convert tag values from 1-255 into a
|
|
realm value when inserting into the Linux kernel. Then routing policy can be
|
|
assigned to the realm. See the tc man page. This option is currently not
|
|
compatible with the usage of nexthop groups in the linux kernel itself.
|
|
|
|
.. option:: --disable-irdp
|
|
|
|
Disable IRDP server support. This is enabled by default if we have
|
|
both `struct in_pktinfo` and `struct icmphdr` available to us.
|
|
|
|
.. option:: --disable-rtadv
|
|
|
|
Disable support IPV6 router advertisement in zebra.
|
|
|
|
.. option:: --enable-gcc-rdynamic
|
|
|
|
Pass the ``-rdynamic`` option to the linker driver. This is in most cases
|
|
necessary for getting usable backtraces. This option defaults to on if the
|
|
compiler is detected as gcc, but giving an explicit enable/disable is
|
|
suggested.
|
|
|
|
.. option:: --disable-backtrace
|
|
|
|
Controls backtrace support for the crash handlers. This is autodetected by
|
|
default. Using the switch will enforce the requested behaviour, failing with
|
|
an error if support is requested but not available. On BSD systems, this
|
|
needs libexecinfo, while on glibc support for this is part of libc itself.
|
|
|
|
.. option:: --enable-dev-build
|
|
|
|
Turn on some options for compiling FRR within a development environment in
|
|
mind. Specifically turn on -g3 -O0 for compiling options and add inclusion
|
|
of grammar sandbox.
|
|
|
|
.. option:: --disable-snmp
|
|
|
|
Build without SNMP support.
|
|
|
|
.. option:: --disable-vtysh
|
|
|
|
Build without VTYSH.
|
|
|
|
.. option:: --enable-fpm
|
|
|
|
Build with FPM module support.
|
|
|
|
.. option:: --with-service-timeout=X
|
|
|
|
Set timeout value for FRR service. The time of restarting or reloading FRR
|
|
service should not exceed this value. This number can be from 0-999.
|
|
Additionally if this parameter is not passed or setting X = 0, FRR will take
|
|
default value: 2 minutes.
|
|
|
|
.. option:: --enable-numeric-version
|
|
|
|
Alpine Linux does not allow non-numeric characters in the version string.
|
|
With this option, we provide a way to strip out these characters for APK dev
|
|
package builds.
|
|
|
|
.. option:: --disable-version-build-config
|
|
|
|
Remove the "configuerd with" field that has all of the build configuration
|
|
arguments when reporting the version string in `show version` command.
|
|
|
|
.. option:: --with-pkg-extra-version=VER
|
|
|
|
Add extra version field, for packagers/distributions
|
|
|
|
.. option:: --with-pkg-git-version
|
|
|
|
Add git information to MOTD and build version string
|
|
|
|
.. option:: --enable-multipath=X
|
|
|
|
Compile FRR with up to X way ECMP supported. This number can be from 0-999.
|
|
For backwards compatibility with older configure options when setting X = 0,
|
|
we will build FRR with 64 way ECMP. This is needed because there are
|
|
hardcoded arrays that FRR builds towards, so we need to know how big to
|
|
make these arrays at build time. Additionally if this parameter is
|
|
not passed in FRR will default to 16 ECMP.
|
|
|
|
.. option:: --enable-shell-access
|
|
|
|
Turn on the ability of FRR to access some shell options( telnet/ssh/bash/etc. )
|
|
from vtysh itself. This option is considered extremely unsecure and should only
|
|
be considered for usage if you really really know what you are doing. This
|
|
option is deprecated and will be removed on Feb 1, 2024.
|
|
|
|
.. option:: --enable-gcov
|
|
|
|
Code coverage reports from gcov require adjustments to the C and LD flags.
|
|
With this option, gcov instrumentation is added to the build and coverage
|
|
reports are created during execution. The check-coverage make target is
|
|
also created to ease report uploading to codecov.io. The upload requires
|
|
the COMMIT (git hash) and TOKEN (codecov upload token) environment variables
|
|
be set.
|
|
|
|
.. option:: --enable-config-rollbacks
|
|
|
|
Build with configuration rollback support. Requires SQLite3.
|
|
|
|
.. option:: --enable-confd=<dir>
|
|
|
|
Build the ConfD northbound plugin. Look for the libconfd libs and headers
|
|
in `dir`.
|
|
|
|
.. option:: --enable-sysrepo
|
|
|
|
Build the Sysrepo northbound plugin.
|
|
|
|
.. option:: --enable-grpc
|
|
|
|
Enable the gRPC northbound plugin.
|
|
|
|
.. option:: --enable-zeromq
|
|
|
|
Enable the ZeroMQ handler.
|
|
|
|
.. option:: --with-libpam
|
|
|
|
Use libpam for PAM support in vtysh.
|
|
|
|
.. option:: --enable-time-check XXX
|
|
|
|
This option is deprecated as it was replaced by the
|
|
:clicmd:`service cputime-stats` CLI command, which may be adjusted at
|
|
runtime rather than being a compile-time setting. See there for further
|
|
detail.
|
|
|
|
.. option:: --disable-cpu-time
|
|
|
|
This option is deprecated as it was replaced by the
|
|
:clicmd:`service cputime-warning NNN` CLI command, which may be adjusted at
|
|
runtime rather than being a compile-time setting. See there for further
|
|
detail.
|
|
|
|
.. option:: --enable-pcreposix
|
|
|
|
Turn on the usage of PCRE Posix libs for regex functionality.
|
|
|
|
.. option:: --enable-pcre2posix
|
|
|
|
Turn on the usage of PCRE2 Posix libs for regex functionality.
|
|
|
|
PCRE2 versions <= 10.31 work a bit differently. We suggest using at least
|
|
>= 10.36.
|
|
|
|
.. option:: --enable-rpath
|
|
|
|
Set hardcoded rpaths in the executable [default=yes].
|
|
|
|
.. option:: --enable-scripting
|
|
|
|
Enable Lua scripting [default=no].
|
|
|
|
You may specify any combination of the above options to the configure
|
|
script. By default, the executables are placed in :file:`/usr/local/sbin`
|
|
and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/`
|
|
installation prefix and other directories may be changed using the following
|
|
options to the configuration script.
|
|
|
|
.. option:: --prefix <prefix>
|
|
|
|
Install architecture-independent files in `prefix` [/usr/local].
|
|
|
|
.. option:: --sysconfdir <dir>
|
|
|
|
Look for configuration files in `dir` [`prefix`/etc]. Note that sample
|
|
configuration files will be installed here.
|
|
|
|
.. option:: --localstatedir <dir>
|
|
|
|
Configure zebra to use `dir` for local state files, such as pid files and
|
|
unix sockets.
|
|
|
|
.. option:: --with-scriptdir <dir>
|
|
|
|
Look for Lua scripts in ``dir`` [``prefix``/etc/frr/scripts].
|
|
|
|
.. option:: --with-yangmodelsdir <dir>
|
|
|
|
Look for YANG modules in `dir` [`prefix`/share/yang]. Note that the FRR
|
|
YANG modules will be installed here.
|
|
|
|
.. option:: --with-vici-socket <path>
|
|
|
|
Set StrongSWAN vici interface socket path [/var/run/charon.vici].
|
|
|
|
.. note::
|
|
|
|
The former ``--enable-systemd`` option does not exist anymore. Support for
|
|
systemd is now always available through built-in functions, without
|
|
depending on libsystemd.
|
|
|
|
Python dependency, documentation and tests
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
FRR's documentation and basic unit tests heavily use code written in Python.
|
|
Additionally, FRR ships Python extensions written in C which are used during
|
|
its build process.
|
|
|
|
To this extent, FRR needs the following:
|
|
|
|
* an installation of CPython, preferably version 3.2 or newer (2.7 works but
|
|
is end of life and will stop working at some point.)
|
|
* development files (mostly headers) for that version of CPython
|
|
* an installation of `sphinx` for that version of CPython, to build the
|
|
documentation
|
|
* an installation of `pytest` for that version of CPython, to run the unit
|
|
tests
|
|
|
|
The `sphinx` and `pytest` dependencies can be avoided by not building
|
|
documentation / not running ``make check``, but the CPython dependency is a
|
|
hard dependency of the FRR build process (for the `clippy` tool.)
|
|
|
|
.. index::
|
|
single: FRR Least-Privileges
|
|
single: FRR Privileges
|
|
|
|
.. _least-privilege-support:
|
|
|
|
Least-Privilege Support
|
|
"""""""""""""""""""""""
|
|
|
|
Additionally, you may configure zebra to drop its elevated privileges
|
|
shortly after startup and switch to another user. The configure script will
|
|
automatically try to configure this support. There are three configure
|
|
options to control the behaviour of FRR daemons.
|
|
|
|
.. option:: --enable-user <user>
|
|
|
|
Switch to user `user shortly after startup, and run as user `user` in normal
|
|
operation.
|
|
|
|
.. option:: --enable-group <user>
|
|
|
|
Switch real and effective group to `group` shortly after startup.
|
|
|
|
.. option:: --enable-vty-group <group>
|
|
|
|
Create Unix Vty sockets (for use with vtysh) with group ownership set to
|
|
`group`. This allows one to create a separate group which is restricted to
|
|
accessing only the vty sockets, hence allowing one to delegate this group to
|
|
individual users, or to run vtysh setgid to this group.
|
|
|
|
The default user and group which will be configured is 'frr' if no user or
|
|
group is specified. Note that this user or group requires write access to the
|
|
local state directory (see :option:`--localstatedir`) and requires at least
|
|
read access, and write access if you wish to allow daemons to write out their
|
|
configuration, to the configuration directory (see :option:`--sysconfdir`).
|
|
|
|
On systems which have the 'libcap' capabilities manipulation library (currently
|
|
only Linux), FRR will retain only minimal capabilities required and will only
|
|
raise these capabilities for brief periods. On systems without libcap, FRR will
|
|
run as the user specified and only raise its UID to 0 for brief periods.
|
|
|
|
|
|
.. index::
|
|
pair: building; Linux
|
|
pair: configuration; Linux
|
|
|
|
Linux Notes
|
|
"""""""""""
|
|
|
|
There are several options available only to GNU/Linux systems. If you use
|
|
GNU/Linux, make sure that the current kernel configuration is what you want.
|
|
FRR will run with any kernel configuration but some recommendations do exist.
|
|
|
|
:makevar:`CONFIG_NETLINK`
|
|
Kernel/User Netlink socket. This enables an advanced interface between
|
|
the Linux kernel and *zebra* (:ref:`kernel-interface`).
|
|
|
|
:makevar:`CONFIG_RTNETLINK`
|
|
This makes it possible to receive Netlink routing messages. If you specify
|
|
this option, *zebra* can detect routing information updates directly from
|
|
the kernel (:ref:`kernel-interface`).
|
|
|
|
:makevar:`CONFIG_IP_MULTICAST`
|
|
This option enables IP multicast and should be specified when you use *ripd*
|
|
(:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
|
|
multicast.
|
|
|
|
Linux sysctl settings and kernel modules
|
|
````````````````````````````````````````
|
|
|
|
There are several kernel parameters that impact overall operation of FRR when
|
|
using Linux as a router. Generally these parameters should be set in a
|
|
sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on
|
|
Ubuntu based systems and a new file
|
|
:file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems.
|
|
Additional kernel modules are also needed to support MPLS forwarding.
|
|
|
|
:makevar:`IPv4 and IPv6 forwarding`
|
|
The following are set to enable IP forwarding in the kernel:
|
|
|
|
.. code-block:: shell
|
|
|
|
net.ipv4.conf.all.forwarding=1
|
|
net.ipv6.conf.all.forwarding=1
|
|
|
|
:makevar:`MPLS forwarding`
|
|
Basic MPLS support was introduced in the kernel in version 4.1 and
|
|
additional capability was introduced in 4.3 and 4.5.
|
|
For some general information on Linux MPLS support, see
|
|
https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf.
|
|
The following modules should be loaded to support MPLS forwarding,
|
|
and are generally added to a configuration file such as
|
|
:file:`/etc/modules-load.d/modules.conf`:
|
|
|
|
.. code-block:: shell
|
|
|
|
# Load MPLS Kernel Modules
|
|
mpls_router
|
|
mpls_iptunnel
|
|
|
|
The following is an example to enable MPLS forwarding in the
|
|
kernel, typically by editing :file:`/etc/sysctl.conf`:
|
|
|
|
.. code-block:: shell
|
|
|
|
# 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
|
|
|
|
Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for
|
|
each interface *'<if>'* used with MPLS and to set labels to an
|
|
appropriate value.
|
|
|
|
:makevar:`VRF forwarding`
|
|
General information on Linux VRF support can be found in
|
|
https://www.kernel.org/doc/Documentation/networking/vrf.txt.
|
|
|
|
Kernel support for VRFs was introduced in 4.3, but there are known issues
|
|
in versions up to 4.15 (for IPv4) and 5.0 (for IPv6). The FRR CI system
|
|
doesn't perform VRF tests on older kernel versions, and VRFs may not work
|
|
on them. If you experience issues with VRF support, you should upgrade your
|
|
kernel version.
|
|
|
|
.. seealso:: :ref:`zebra-vrf`
|
|
|
|
Building
|
|
^^^^^^^^
|
|
|
|
Once you have chosen your configure options, run the configure script and pass
|
|
the options you chose:
|
|
|
|
.. code-block:: shell
|
|
|
|
./configure \
|
|
--prefix=/usr \
|
|
--localstatedir=/var/run/frr \
|
|
--sbindir=/usr/lib/frr \
|
|
--sysconfdir=/etc/frr \
|
|
--enable-pimd \
|
|
--enable-watchfrr \
|
|
...
|
|
|
|
After configuring the software, you are ready to build and install it in your
|
|
system.
|
|
|
|
.. code-block:: shell
|
|
|
|
make && sudo make install
|
|
|
|
If everything finishes successfully, FRR should be installed. You should now
|
|
skip to the section on :ref:`basic-setup`.
|