2 single: How to install FRR
11 This section covers the basics of building, installing and setting up FRR.
17 The project publishes packages for Red Hat, Centos, Debian and Ubuntu on the
18 `GitHub releases <https://github.com/FRRouting/frr/releases>`_. page. External
19 contributors offer packages for many other platforms including \*BSD, Alpine,
20 Gentoo, Docker, and others. There is currently no documentation on how to use
21 those but we hope to add it soon.
26 In addition to traditional packages the project also builds and publishes
27 universal Snap images, available at https://snapcraft.io/frr.
32 Building FRR from source is the best way to ensure you have the latest features
33 and bug fixes. Details for each supported platform, including dependency
34 package listings, permissions, and other gotchas, are in the `developer's
36 <http://docs.frrouting.org/projects/dev-guide/en/latest/building.html>`_. This
37 section provides a brief overview on the process.
43 FRR's source is available on the project
44 `GitHub page <https://github.com/FRRouting/frr>`_.
48 git clone https://github.com/FRRouting/frr.git
50 When building from Git there are several branches to choose from. The
51 ``master`` branch is the primary development branch. It should be considered
52 unstable. Each release has its own branch named ``stable/X.X``, where ``X.X``
53 is the release version.
55 In addition, release tarballs are published on the GitHub releases page
56 `here <https://github.com/FRRouting/frr/releases>`_.
60 single: Configuration options
61 single: Options for configuring
63 single: Distribution configuration
64 single: Options to `./configure`
66 .. _build-configuration:
71 FRR has an excellent configure script which automatically detects most host
72 configurations. There are several additional configure options to customize the
73 build to include or exclude specific features and dependencies.
75 First, update the build system. Change into your FRR source directory and issue:
81 This will install any missing build scripts and update the Autotools
82 configuration. Once this is done you can move on to choosing your configuration
83 options from the list below.
85 .. _frr-configuration:
87 .. program:: configure
89 .. option:: --enable-tcmalloc
91 Enable the alternate malloc library. In some cases this is faster and more efficient,
92 in some cases it is not.
94 .. option:: --disable-doc
96 Do not build any documentation, including this one.
98 .. option:: --enable-doc-html
100 From the documentation build html docs as well in addition to the normal output.
102 .. option:: --disable-zebra
104 Do not build zebra daemon. This generally only be useful in a scenario where
105 you are building bgp as a standalone server.
107 .. option:: --disable-ripd
111 .. option:: --disable-ripngd
115 .. option:: --disable-ospfd
119 .. option:: --disable-ospf6d
123 .. option:: --disable-bgpd
127 .. option:: --disable-ldpd
131 .. option:: --disable-nhrpd
135 .. option:: --disable-eigrpd
139 .. option:: --disable-babeld
143 .. option:: --disable-watchfrr
145 Do not build watchfrr. Watchfrr is used to integrate daemons into startup/shutdown
146 software available on your machine. This is needed for systemd integration, if you
147 disable watchfrr you cannot have any systemd integration.
149 .. option:: --enable-werror
151 Build with all warnings converted to errors as a compile option. This
152 is recommended for developers only.
154 .. option:: --disable-pimd
156 Turn off building of pimd. On some BSD platforms pimd will not build properly due
157 to lack of kernel support.
159 .. option:: --disable-vrrpd
161 Turn off building of vrrpd. Linux is required for vrrpd support;
162 other platforms are not supported.
164 .. option:: --disable-pbrd
166 Turn off building of pbrd. This daemon currently requires linux in order to function
169 .. option:: --enable-sharpd
171 Turn on building of sharpd. This daemon facilitates testing of FRR and can also
172 be used as a quick and easy route generator.
174 .. option:: --disable-staticd
176 Do not build staticd. This daemon is necessary if you want static routes.
178 .. option:: --disable-bfdd
182 .. option:: --disable-bgp-announce
184 Make *bgpd* which does not make bgp announcements at all. This
185 feature is good for using *bgpd* as a BGP announcement listener.
187 .. option:: --disable-bgp-vnc
189 Turn off bgpd's ability to use VNC.
191 .. option:: --disable-bgp-bmp
193 Turn off BGP BMP support
195 .. option:: --enable-datacenter
197 This option is deprecated as it is superseded by the `-F` (profile) command
198 line option which allows adjusting the setting at startup rather than
201 Enable system defaults to work as if in a Data Center. See defaults.h
202 for what is changed by this configure option.
204 .. option:: --enable-snmp
206 Enable SNMP support. By default, SNMP support is disabled.
208 .. option:: --disable-ospfapi
210 Disable support for OSPF-API, an API to interface directly with ospfd.
211 OSPF-API is enabled if --enable-opaque-lsa is set.
213 .. option:: --disable-ospfclient
215 Disable installation of the python ospfclient and building of the example
218 .. option:: --disable-isisd
222 .. option:: --disable-fabricd
224 Do not build fabricd.
226 .. option:: --enable-isis-topology
228 Enable IS-IS topology generator.
230 .. option:: --enable-realms
232 Enable the support of Linux Realms. Convert tag values from 1-255 into a
233 realm value when inserting into the Linux kernel. Then routing policy can be
234 assigned to the realm. See the tc man page. This option is currently not
235 compatible with the usage of nexthop groups in the linux kernel itself.
237 .. option:: --disable-irdp
239 Disable IRDP server support. This is enabled by default if we have
240 both `struct in_pktinfo` and `struct icmphdr` available to us.
242 .. option:: --disable-rtadv
244 Disable support IPV6 router advertisement in zebra.
246 .. option:: --enable-gcc-rdynamic
248 Pass the ``-rdynamic`` option to the linker driver. This is in most cases
249 necessary for getting usable backtraces. This option defaults to on if the
250 compiler is detected as gcc, but giving an explicit enable/disable is
253 .. option:: --disable-backtrace
255 Controls backtrace support for the crash handlers. This is autodetected by
256 default. Using the switch will enforce the requested behaviour, failing with
257 an error if support is requested but not available. On BSD systems, this
258 needs libexecinfo, while on glibc support for this is part of libc itself.
260 .. option:: --enable-dev-build
262 Turn on some options for compiling FRR within a development environment in
263 mind. Specifically turn on -g3 -O0 for compiling options and add inclusion
266 .. option:: --disable-snmp
268 Build without SNMP support.
270 .. option:: --disable-vtysh
274 .. option:: --enable-fpm
276 Build with FPM module support.
278 .. option:: --with-service-timeout=X
280 Set timeout value for FRR service. The time of restarting or reloading FRR
281 service should not exceed this value. This number can be from 0-999.
282 Additionally if this parameter is not passed or setting X = 0, FRR will take
283 default value: 2 minutes.
285 .. option:: --enable-numeric-version
287 Alpine Linux does not allow non-numeric characters in the version string.
288 With this option, we provide a way to strip out these characters for APK dev
291 .. option:: --disable-version-build-config
293 Remove the "configuerd with" field that has all of the build configuration
294 arguments when reporting the version string in `show version` command.
296 .. option:: --with-pkg-extra-version=VER
298 Add extra version field, for packagers/distributions
300 .. option:: --with-pkg-git-version
302 Add git information to MOTD and build version string
304 .. option:: --enable-multipath=X
306 Compile FRR with up to X way ECMP supported. This number can be from 0-999.
307 For backwards compatibility with older configure options when setting X = 0,
308 we will build FRR with 64 way ECMP. This is needed because there are
309 hardcoded arrays that FRR builds towards, so we need to know how big to
310 make these arrays at build time. Additionally if this parameter is
311 not passed in FRR will default to 16 ECMP.
313 .. option:: --enable-shell-access
315 Turn on the ability of FRR to access some shell options( telnet/ssh/bash/etc. )
316 from vtysh itself. This option is considered extremely unsecure and should only
317 be considered for usage if you really really know what you are doing.
319 .. option:: --enable-gcov
321 Code coverage reports from gcov require adjustments to the C and LD flags.
322 With this option, gcov instrumentation is added to the build and coverage
323 reports are created during execution. The check-coverage make target is
324 also created to ease report uploading to codecov.io. The upload requires
325 the COMMIT (git hash) and TOKEN (codecov upload token) environment variables
328 .. option:: --enable-config-rollbacks
330 Build with configuration rollback support. Requires SQLite3.
332 .. option:: --enable-confd=<dir>
334 Build the ConfD northbound plugin. Look for the libconfd libs and headers
337 .. option:: --enable-sysrepo
339 Build the Sysrepo northbound plugin.
341 .. option:: --enable-grpc
343 Enable the gRPC northbound plugin.
345 .. option:: --enable-zeromq
347 Enable the ZeroMQ handler.
349 .. option:: --with-libpam
351 Use libpam for PAM support in vtysh.
353 .. option:: --enable-time-check XXX
355 This option is deprecated as it was replaced by the
356 :clicmd:`service cputime-stats` CLI command, which may be adjusted at
357 runtime rather than being a compile-time setting. See there for further
360 .. option:: --disable-cpu-time
362 This option is deprecated as it was replaced by the
363 :clicmd:`service cputime-warning NNN` CLI command, which may be adjusted at
364 runtime rather than being a compile-time setting. See there for further
367 .. option:: --enable-pcreposix
369 Turn on the usage of PCRE Posix libs for regex functionality.
371 .. option:: --enable-pcre2posix
373 Turn on the usage of PCRE2 Posix libs for regex functionality.
375 PCRE2 versions <= 10.31 work a bit differently. We suggest using at least
378 .. option:: --enable-rpath
380 Set hardcoded rpaths in the executable [default=yes].
382 .. option:: --enable-scripting
384 Enable Lua scripting [default=no].
386 You may specify any combination of the above options to the configure
387 script. By default, the executables are placed in :file:`/usr/local/sbin`
388 and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/`
389 installation prefix and other directories may be changed using the following
390 options to the configuration script.
392 .. option:: --prefix <prefix>
394 Install architecture-independent files in `prefix` [/usr/local].
396 .. option:: --sysconfdir <dir>
398 Look for configuration files in `dir` [`prefix`/etc]. Note that sample
399 configuration files will be installed here.
401 .. option:: --localstatedir <dir>
403 Configure zebra to use `dir` for local state files, such as pid files and
406 .. option:: --with-scriptdir <dir>
408 Look for Lua scripts in ``dir`` [``prefix``/etc/frr/scripts].
410 .. option:: --with-yangmodelsdir <dir>
412 Look for YANG modules in `dir` [`prefix`/share/yang]. Note that the FRR
413 YANG modules will be installed here.
415 .. option:: --with-vici-socket <path>
417 Set StrongSWAN vici interface socket path [/var/run/charon.vici].
421 The former ``--enable-systemd`` option does not exist anymore. Support for
422 systemd is now always available through built-in functions, without
423 depending on libsystemd.
425 Python dependency, documentation and tests
426 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
428 FRR's documentation and basic unit tests heavily use code written in Python.
429 Additionally, FRR ships Python extensions written in C which are used during
432 To this extent, FRR needs the following:
434 * an installation of CPython, preferably version 3.2 or newer (2.7 works but
435 is end of life and will stop working at some point.)
436 * development files (mostly headers) for that version of CPython
437 * an installation of `sphinx` for that version of CPython, to build the
439 * an installation of `pytest` for that version of CPython, to run the unit
442 The `sphinx` and `pytest` dependencies can be avoided by not building
443 documentation / not running ``make check``, but the CPython dependency is a
444 hard dependency of the FRR build process (for the `clippy` tool.)
447 single: FRR Least-Privileges
448 single: FRR Privileges
450 .. _least-privilege-support:
452 Least-Privilege Support
453 """""""""""""""""""""""
455 Additionally, you may configure zebra to drop its elevated privileges
456 shortly after startup and switch to another user. The configure script will
457 automatically try to configure this support. There are three configure
458 options to control the behaviour of FRR daemons.
460 .. option:: --enable-user <user>
462 Switch to user `user shortly after startup, and run as user `user` in normal
465 .. option:: --enable-group <user>
467 Switch real and effective group to `group` shortly after startup.
469 .. option:: --enable-vty-group <group>
471 Create Unix Vty sockets (for use with vtysh) with group ownership set to
472 `group`. This allows one to create a separate group which is restricted to
473 accessing only the vty sockets, hence allowing one to delegate this group to
474 individual users, or to run vtysh setgid to this group.
476 The default user and group which will be configured is 'frr' if no user or
477 group is specified. Note that this user or group requires write access to the
478 local state directory (see :option:`--localstatedir`) and requires at least
479 read access, and write access if you wish to allow daemons to write out their
480 configuration, to the configuration directory (see :option:`--sysconfdir`).
482 On systems which have the 'libcap' capabilities manipulation library (currently
483 only Linux), FRR will retain only minimal capabilities required and will only
484 raise these capabilities for brief periods. On systems without libcap, FRR will
485 run as the user specified and only raise its UID to 0 for brief periods.
489 pair: building; Linux
490 pair: configuration; Linux
495 There are several options available only to GNU/Linux systems. If you use
496 GNU/Linux, make sure that the current kernel configuration is what you want.
497 FRR will run with any kernel configuration but some recommendations do exist.
499 :makevar:`CONFIG_NETLINK`
500 Kernel/User Netlink socket. This enables an advanced interface between
501 the Linux kernel and *zebra* (:ref:`kernel-interface`).
503 :makevar:`CONFIG_RTNETLINK`
504 This makes it possible to receive Netlink routing messages. If you specify
505 this option, *zebra* can detect routing information updates directly from
506 the kernel (:ref:`kernel-interface`).
508 :makevar:`CONFIG_IP_MULTICAST`
509 This option enables IP multicast and should be specified when you use *ripd*
510 (:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
513 Linux sysctl settings and kernel modules
514 ````````````````````````````````````````
516 There are several kernel parameters that impact overall operation of FRR when
517 using Linux as a router. Generally these parameters should be set in a
518 sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on
519 Ubuntu based systems and a new file
520 :file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems.
521 Additional kernel modules are also needed to support MPLS forwarding.
523 :makevar:`IPv4 and IPv6 forwarding`
524 The following are set to enable IP forwarding in the kernel:
526 .. code-block:: shell
528 net.ipv4.conf.all.forwarding=1
529 net.ipv6.conf.all.forwarding=1
531 :makevar:`MPLS forwarding`
532 Basic MPLS support was introduced in the kernel in version 4.1 and
533 additional capability was introduced in 4.3 and 4.5.
534 For some general information on Linux MPLS support, see
535 https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf.
536 The following modules should be loaded to support MPLS forwarding,
537 and are generally added to a configuration file such as
538 :file:`/etc/modules-load.d/modules.conf`:
540 .. code-block:: shell
542 # Load MPLS Kernel Modules
546 The following is an example to enable MPLS forwarding in the
547 kernel, typically by editing :file:`/etc/sysctl.conf`:
549 .. code-block:: shell
551 # Enable MPLS Label processing on all interfaces
552 net.mpls.conf.eth0.input=1
553 net.mpls.conf.eth1.input=1
554 net.mpls.conf.eth2.input=1
555 net.mpls.platform_labels=100000
557 Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for
558 each interface *'<if>'* used with MPLS and to set labels to an
561 :makevar:`VRF forwarding`
562 General information on Linux VRF support can be found in
563 https://www.kernel.org/doc/Documentation/networking/vrf.txt.
565 Kernel support for VRFs was introduced in 4.3, but there are known issues
566 in versions up to 4.15 (for IPv4) and 5.0 (for IPv6). The FRR CI system
567 doesn't perform VRF tests on older kernel versions, and VRFs may not work
568 on them. If you experience issues with VRF support, you should upgrade your
571 .. seealso:: :ref:`zebra-vrf`
576 Once you have chosen your configure options, run the configure script and pass
577 the options you chose:
579 .. code-block:: shell
583 --localstatedir=/var/run/frr \
584 --sbindir=/usr/lib/frr \
585 --sysconfdir=/etc/frr \
590 After configuring the software, you are ready to build and install it in your
593 .. code-block:: shell
595 make && sudo make install
597 If everything finishes successfully, FRR should be installed. You should now
598 skip to the section on :ref:`basic-setup`.