6 .. index:: How to install FRR
7 .. index:: Installation
8 .. index:: Installing FRR
9 .. index:: Building the system
12 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
35 documentation. This section provides a brief overview on the process.
40 FRR's source is available on the project
41 `GitHub page <https://github.com/FRRouting/frr>`_.
45 git clone https://github.com/FRRouting/frr.git
47 When building from Git there are several branches to choose from. The
48 ``master`` branch is the primary development branch. It should be considered
49 unstable. Each release has its own branch named ``stable/X.X``, where ``X.X``
50 is the release version.
52 In addition, release tarballs are published on the GitHub releases page
53 `here <https://github.com/FRRouting/frr/releases>`_.
58 .. index:: Configuration options
59 .. index:: Options for configuring
60 .. index:: Build options
61 .. index:: Distribution configuration
62 .. index:: Options to `./configure`
64 FRR has an excellent configure script which automatically detects most host
65 configurations. There are several additional configure options to customize the
66 build to include or exclude specific features and dependencies.
68 First, update the build system. Change into your FRR source directory and issue:
74 This will install any missing build scripts and update the Autotools
75 configuration. Once this is done you can move on to choosing your configuration
76 options from the list below.
78 .. _frr-configuration:
80 .. program:: configure
82 .. option:: --enable-tcmalloc
84 Enable the alternate malloc library. In some cases this is faster and more efficient,
85 in some cases it is not.
87 .. option:: --disable-doc
89 Do not build any documentation, including this one.
91 .. option:: --enable-doc-html
93 From the documentation build html docs as well in addition to the normal output.
95 .. option:: --disable-zebra
97 Do not build zebra daemon. This generally only be useful in a scenario where
98 you are building bgp as a standalone server.
100 .. option:: --disable-ripd
104 .. option:: --disable-ripngd
108 .. option:: --disable-ospfd
112 .. option:: --disable-ospf6d
116 .. option:: --disable-bgpd
120 .. option:: --disable-ldpd
124 .. option:: --disable-nhrpd
128 .. option:: --disable-eigrpd
132 .. option:: --disable-babeld
136 .. option:: --disable-watchfrr
138 Do not build watchfrr. Watchfrr is used to integrate daemons into startup/shutdown
139 software available on your machine. This is needed for systemd integration, if you
140 disable watchfrr you cannot have any systemd integration.
142 .. option:: --enable-systemd
144 Build watchfrr with systemd integration, this will allow FRR to communicate with
145 systemd to tell systemd if FRR has come up properly.
147 .. option:: --enable-werror
149 Build with all warnings converted to errors as a compile option. This
150 is recommended for developers only.
152 .. option:: --disable-pimd
154 Turn off building of pimd. On some BSD platforms pimd will not build properly due
155 to lack of kernel support.
157 .. option:: --disable-vrrpd
159 Turn off building of vrrpd. Linux is required for vrrpd support;
160 other platforms are not supported.
162 .. option:: --disable-pbrd
164 Turn off building of pbrd. This daemon currently requires linux in order to function
167 .. option:: --enable-sharpd
169 Turn on building of sharpd. This daemon facilitates testing of FRR and can also
170 be used as a quick and easy route generator.
172 .. option:: --disable-staticd
174 Do not build staticd. This daemon is necessary if you want static routes.
176 .. option:: --disable-bfdd
180 .. option:: --disable-bgp-announce
182 Make *bgpd* which does not make bgp announcements at all. This
183 feature is good for using *bgpd* as a BGP announcement listener.
185 .. option:: --disable-bgp-vnc
187 Turn off bgpd's ability to use VNC.
189 .. option:: --disable-bgp-bmp
191 Turn off BGP BMP support
193 .. option:: --enable-datacenter
195 Enable system defaults to work as if in a Data Center. See defaults.h
196 for what is changed by this configure option.
198 .. option:: --enable-snmp
200 Enable SNMP support. By default, SNMP support is disabled.
202 .. option:: --disable-ospfapi
204 Disable support for OSPF-API, an API to interface directly with ospfd.
205 OSPF-API is enabled if --enable-opaque-lsa is set.
207 .. option:: --disable-ospfclient
209 Disable building of the example OSPF-API client.
211 .. option:: --disable-isisd
215 .. option:: --disable-fabricd
217 Do not build fabricd.
219 .. option:: --enable-isis-topology
221 Enable IS-IS topology generator.
223 .. option:: --enable-realms
225 Enable the support of Linux Realms. Convert tag values from 1-255 into a
226 realm value when inserting into the Linux kernel. Then routing policy can be
227 assigned to the realm. See the tc man page.
229 .. option:: --disable-irdp
231 Disable IRDP server support. This is enabled by default if we have
232 both `struct in_pktinfo` and `struct icmphdr` available to us.
234 .. option:: --disable-rtadv
236 Disable support IPV6 router advertisement in zebra.
238 .. option:: --enable-gcc-rdynamic
240 Pass the ``-rdynamic`` option to the linker driver. This is in most cases
241 necessary for getting usable backtraces. This option defaults to on if the
242 compiler is detected as gcc, but giving an explicit enable/disable is
245 .. option:: --disable-backtrace
247 Controls backtrace support for the crash handlers. This is autodetected by
248 default. Using the switch will enforce the requested behaviour, failing with
249 an error if support is requested but not available. On BSD systems, this
250 needs libexecinfo, while on glibc support for this is part of libc itself.
252 .. option:: --enable-dev-build
254 Turn on some options for compiling FRR within a development environment in
255 mind. Specifically turn on -g3 -O0 for compiling options and add inclusion
258 .. option:: --enable-fuzzing
260 Turn on some compile options to allow you to run fuzzing tools against the
261 system. This flag is intended as a developer only tool and should not be
262 used for normal operations.
264 .. option:: --disable-snmp
266 Build without SNMP support.
268 .. option:: --disable-vtysh
272 .. option:: --enable-fpm
274 Build with FPM module support.
276 .. option:: --enable-numeric-version
278 Alpine Linux does not allow non-numeric characters in the version string.
279 With this option, we provide a way to strip out these characters for APK dev
282 ..option:: --disable-version-build-config
284 Remove the "configuerd with" field that has all of the build configuration
285 arguments when reporting the version string in `show version` command.
287 ..option:: --with-pkg-extra-version=VER
288 Add extra version field, for packagers/distributions
290 ..option:: --with-pkg-git-version
292 Add git information to MOTD and build version string
294 .. option:: --enable-multipath=X
296 Compile FRR with up to X way ECMP supported. This number can be from 0-999.
297 For backwards compatibility with older configure options when setting X = 0,
298 we will build FRR with 64 way ECMP. This is needed because there are
299 hardcoded arrays that FRR builds towards, so we need to know how big to
300 make these arrays at build time. Additionally if this parameter is
301 not passed in FRR will default to 16 ECMP.
303 .. option:: --enable-shell-access
305 Turn on the ability of FRR to access some shell options( telnet/ssh/bash/etc. )
306 from vtysh itself. This option is considered extremely unsecure and should only
307 be considered for usage if you really really know what you are doing.
309 .. option:: --enable-gcov
311 Code coverage reports from gcov require adjustments to the C and LD flags.
312 With this option, gcov instrumentation is added to the build and coverage
313 reports are created during execution. The check-coverage make target is
314 also created to ease report uploading to codecov.io. The upload requires
315 the COMMIT (git hash) and TOKEN (codecov upload token) environment variables
318 .. option:: --enable-config-rollbacks
320 Build with configuration rollback support. Requires SQLite3.
322 .. option:: --enable-confd=<dir>
324 Build the ConfD northbound plugin. Look for the libconfd libs and headers
327 .. option:: --enable-sysrepo
329 Build the Sysrepo northbound plugin.
331 .. option:: --enable-grpc
333 Enable the gRPC northbound plugin.
335 .. option:: --enable-zeromq
337 Enable the ZeroMQ handler.
339 .. option:: --with-libpam
341 Use libpam for PAM support in vtysh.
343 .. option:: --enable-time-check XXX
345 When this is enabled with a XXX value in microseconds, any thread that
346 runs for over this value will cause a warning to be issued to the log.
347 If you do not specify any value or don't include this option then
348 the default time is 5 seconds. If --disable-time-check is specified
349 then no warning is issued for any thread run length.
351 .. option:: --disable-cpu-time
353 Disable cpu process accounting, this command also disables the `show thread cpu`
354 command. If this option is disabled, --enable-time-check is ignored. This
355 disabling of cpu time effectively means that the getrusage call is skipped.
356 Since this is a process switch into the kernel, systems with high FRR
357 load might see improvement in behavior. Be aware that `show thread cpu`
358 is considered a good data gathering tool from the perspective of developers.
360 .. option:: --enable-pcreposix
362 Turn on the usage of PCRE Posix libs for regex functionality.
364 You may specify any combination of the above options to the configure
365 script. By default, the executables are placed in :file:`/usr/local/sbin`
366 and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/`
367 installation prefix and other directories may be changed using the following
368 options to the configuration script.
370 .. option:: --prefix <prefix>
372 Install architecture-independent files in `prefix` [/usr/local].
374 .. option:: --sysconfdir <dir>
376 Look for configuration files in `dir` [`prefix`/etc]. Note that sample
377 configuration files will be installed here.
379 .. option:: --localstatedir <dir>
381 Configure zebra to use `dir` for local state files, such as pid files and
384 .. option:: --with-yangmodelsdir <dir>
386 Look for YANG modules in `dir` [`prefix`/share/yang]. Note that the FRR
387 YANG modules will be installed here.
389 Python dependency, documentation and tests
390 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
392 FRR's documentation and basic unit tests heavily use code written in Python.
393 Additionally, FRR ships Python extensions written in C which are used during
396 To this extent, FRR needs the following:
398 * an installation of CPython, preferably version 3.2 or newer (2.7 works but
399 is end of life and will stop working at some point.)
400 * development files (mostly headers) for that version of CPython
401 * an installation of `sphinx` for that version of CPython, to build the
403 * an installation of `pytest` for that version of CPython, to run the unit
406 The `sphinx` and `pytest` dependencies can be avoided by not building
407 documentation / not running ``make check``, but the CPython dependency is a
408 hard dependency of the FRR build process (for the `clippy` tool.)
410 .. _least-privilege-support:
412 Least-Privilege Support
413 """""""""""""""""""""""
415 .. index:: FRR Least-Privileges
416 .. index:: FRR Privileges
418 Additionally, you may configure zebra to drop its elevated privileges
419 shortly after startup and switch to another user. The configure script will
420 automatically try to configure this support. There are three configure
421 options to control the behaviour of FRR daemons.
423 .. option:: --enable-user <user>
425 Switch to user `user shortly after startup, and run as user `user` in normal
428 .. option:: --enable-group <user>
430 Switch real and effective group to `group` shortly after startup.
432 .. option:: --enable-vty-group <group>
434 Create Unix Vty sockets (for use with vtysh) with group ownership set to
435 `group`. This allows one to create a separate group which is restricted to
436 accessing only the vty sockets, hence allowing one to delegate this group to
437 individual users, or to run vtysh setgid to this group.
439 The default user and group which will be configured is 'frr' if no user or
440 group is specified. Note that this user or group requires write access to the
441 local state directory (see :option:`--localstatedir`) and requires at least
442 read access, and write access if you wish to allow daemons to write out their
443 configuration, to the configuration directory (see :option:`--sysconfdir`).
445 On systems which have the 'libcap' capabilities manipulation library (currently
446 only Linux), FRR will retain only minimal capabilities required and will only
447 raise these capabilities for brief periods. On systems without libcap, FRR will
448 run as the user specified and only raise its UID to 0 for brief periods.
453 .. index:: Building on Linux boxes
454 .. index:: Linux configurations
456 There are several options available only to GNU/Linux systems. If you use
457 GNU/Linux, make sure that the current kernel configuration is what you want.
458 FRR will run with any kernel configuration but some recommendations do exist.
460 :makevar:`CONFIG_NETLINK`
461 Kernel/User Netlink socket. This enables an advanced interface between
462 the Linux kernel and *zebra* (:ref:`kernel-interface`).
464 :makevar:`CONFIG_RTNETLINK`
465 This makes it possible to receive Netlink routing messages. If you specify
466 this option, *zebra* can detect routing information updates directly from
467 the kernel (:ref:`kernel-interface`).
469 :makevar:`CONFIG_IP_MULTICAST`
470 This option enables IP multicast and should be specified when you use *ripd*
471 (:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
474 Linux sysctl settings and kernel modules
475 ````````````````````````````````````````
477 There are several kernel parameters that impact overall operation of FRR when
478 using Linux as a router. Generally these parameters should be set in a
479 sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on
480 Ubuntu based systems and a new file
481 :file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems.
482 Additional kernel modules are also needed to support MPLS forwarding.
484 :makevar:`IPv4 and IPv6 forwarding`
485 The following are set to enable IP forwarding in the kernel:
487 .. code-block:: shell
489 net.ipv4.conf.all.forwarding=1
490 net.ipv6.conf.all.forwarding=1
492 :makevar:`MPLS forwarding`
493 Basic MPLS support was introduced in the kernel in version 4.1 and
494 additional capability was introduced in 4.3 and 4.5.
495 For some general information on Linux MPLS support, see
496 https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf.
497 The following modules should be loaded to support MPLS forwarding,
498 and are generally added to a configuration file such as
499 :file:`/etc/modules-load.d/modules.conf`:
501 .. code-block:: shell
503 # Load MPLS Kernel Modules
507 The following is an example to enable MPLS forwarding in the
508 kernel, typically by editing :file:`/etc/sysctl.conf`:
510 .. code-block:: shell
512 # Enable MPLS Label processing on all interfaces
513 net.mpls.conf.eth0.input=1
514 net.mpls.conf.eth1.input=1
515 net.mpls.conf.eth2.input=1
516 net.mpls.platform_labels=100000
518 Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for
519 each interface *'<if>'* used with MPLS and to set labels to an
522 :makevar:`VRF forwarding`
523 General information on Linux VRF support can be found in
524 https://www.kernel.org/doc/Documentation/networking/vrf.txt. Kernel
525 support for VRFs was introduced in 4.3 and improved upon through
526 4.13, which is the version most used in FRR testing (as of June
527 2018). Additional background on using Linux VRFs and kernel specific
528 features can be found in
529 http://schd.ws/hosted_files/ossna2017/fe/vrf-tutorial-oss.pdf.
531 The following impacts how BGP TCP sockets are managed across VRFs:
533 .. code-block:: shell
535 net.ipv4.tcp_l3mdev_accept=0
537 With this setting a BGP TCP socket is opened per VRF. This setting
538 ensures that other TCP services, such as SSH, provided for non-VRF
539 purposes are blocked from VRF associated Linux interfaces.
541 .. code-block:: shell
543 net.ipv4.tcp_l3mdev_accept=1
545 With this setting a single BGP TCP socket is shared across the
546 system. This setting exposes any TCP service running on the system,
547 e.g., SSH, to all VRFs. Generally this setting is not used in
548 environments where VRFs are used to support multiple administrative
551 **Important note** as of June 2018, Kernel versions 4.14-4.18 have a
552 known bug where VRF-specific TCP sockets are not properly handled. When
553 running these kernel versions, if unable to establish any VRF BGP
554 adjacencies, either downgrade to 4.13 or set
555 'net.ipv4.tcp_l3mdev_accept=1'. The fix for this issue is planned to be
556 included in future kernel versions. So upgrading your kernel may also
563 Once you have chosen your configure options, run the configure script and pass
564 the options you chose:
566 .. code-block:: shell
570 --enable-exampledir=/usr/share/doc/frr/examples/ \
571 --localstatedir=/var/run/frr \
572 --sbindir=/usr/lib/frr \
573 --sysconfdir=/etc/frr \
578 After configuring the software, you are ready to build and install it in your
581 .. code-block:: shell
583 make && sudo make install
585 If everything finishes successfully, FRR should be installed. You should now
586 skip to the section on :ref:`basic-setup`.