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:: --disable-zebra
84 Do not build zebra daemon.
86 .. option:: --disable-ripd
90 .. option:: --disable-ripngd
94 .. option:: --disable-ospfd
98 .. option:: --disable-ospf6d
102 .. option:: --disable-bgpd
106 .. option:: --disable-bfdd
110 .. option:: --disable-bgp-announce
112 Make *bgpd* which does not make bgp announcements at all. This
113 feature is good for using *bgpd* as a BGP announcement listener.
115 .. option:: --enable-datacenter
117 Enable system defaults to work as if in a Data Center. See defaults.h
118 for what is changed by this configure option.
120 .. option:: --enable-snmp
122 Enable SNMP support. By default, SNMP support is disabled.
124 .. option:: --disable-ospfapi
126 Disable support for OSPF-API, an API to interface directly with ospfd.
127 OSPF-API is enabled if --enable-opaque-lsa is set.
129 .. option:: --disable-ospfclient
131 Disable building of the example OSPF-API client.
133 .. option:: --disable-ospf-ri
135 Disable support for OSPF Router Information (RFC4970 & RFC5088) this
136 requires support for Opaque LSAs and Traffic Engineering.
138 .. option:: --disable-isisd
142 .. option:: --disable-fabricd
144 Do not build fabricd.
146 .. option:: --enable-isis-topology
148 Enable IS-IS topology generator.
150 .. option:: --enable-isis-te
152 Enable Traffic Engineering Extension for ISIS (RFC5305)
154 .. option:: --enable-realms
156 Enable the support of Linux Realms. Convert tag values from 1-255 into a
157 realm value when inserting into the Linux kernel. Then routing policy can be
158 assigned to the realm. See the tc man page.
160 .. option:: --disable-rtadv
162 Disable support IPV6 router advertisement in zebra.
164 .. option:: --enable-gcc-rdynamic
166 Pass the ``-rdynamic`` option to the linker driver. This is in most cases
167 necessary for getting usable backtraces. This option defaults to on if the
168 compiler is detected as gcc, but giving an explicit enable/disable is
171 .. option:: --disable-backtrace
173 Controls backtrace support for the crash handlers. This is autodetected by
174 default. Using the switch will enforce the requested behaviour, failing with
175 an error if support is requested but not available. On BSD systems, this
176 needs libexecinfo, while on glibc support for this is part of libc itself.
178 .. option:: --enable-dev-build
180 Turn on some options for compiling FRR within a development environment in
181 mind. Specifically turn on -g3 -O0 for compiling options and add inclusion
184 .. option:: --enable-fuzzing
186 Turn on some compile options to allow you to run fuzzing tools against the
187 system. This flag is intended as a developer only tool and should not be
188 used for normal operations.
190 .. option:: --disable-snmp
192 Build without SNMP support.
194 .. option:: --disable-vtysh
198 .. option:: --enable-fpm
200 Build with FPM module support.
202 .. option:: --enable-numeric-version
204 Alpine Linux does not allow non-numeric characters in the version string.
205 With this option, we provide a way to strip out these characters for APK dev
208 .. option:: --enable-multipath=X
210 Compile FRR with up to X way ECMP supported. This number can be from 0-999.
211 For backwards compatability with older configure options when setting X = 0,
212 we will build FRR with 64 way ECMP. This is needed because there are
213 hardcoded arrays that FRR builds towards, so we need to know how big to
214 make these arrays at build time.
216 .. option:: --enable-gcov
218 Code coverage reports from gcov require adjustments to the C and LD flags.
219 With this option, gcov instrumentation is added to the build and coverage
220 reports are created during execution. The check-coverage make target is
221 also created to ease report uploading to codecov.io. The upload requires
222 the COMMIT (git hash) and TOKEN (codecov upload token) environment variables
225 .. option:: --enable-config-rollbacks
227 Build with configuration rollback support. Requires SQLite3.
229 .. option:: --enable-confd=<dir>
231 Build the ConfD northbound plugin. Look for the libconfd libs and headers
234 You may specify any combination of the above options to the configure
235 script. By default, the executables are placed in :file:`/usr/local/sbin`
236 and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/`
237 installation prefix and other directories may be changed using the following
238 options to the configuration script.
240 .. option:: --prefix <prefix>
242 Install architecture-independent files in `prefix` [/usr/local].
244 .. option:: --sysconfdir <dir>
246 Look for configuration files in `dir` [`prefix`/etc]. Note that sample
247 configuration files will be installed here.
249 .. option:: --localstatedir <dir>
251 Configure zebra to use `dir` for local state files, such as pid files and
254 .. _least-privilege-support:
256 Least-Privilege Support
257 """""""""""""""""""""""
259 .. index:: FRR Least-Privileges
260 .. index:: FRR Privileges
262 Additionally, you may configure zebra to drop its elevated privileges
263 shortly after startup and switch to another user. The configure script will
264 automatically try to configure this support. There are three configure
265 options to control the behaviour of FRR daemons.
267 .. option:: --enable-user <user>
269 Switch to user `user shortly after startup, and run as user `user` in normal
272 .. option:: --enable-group <user>
274 Switch real and effective group to `group` shortly after startup.
276 .. option:: --enable-vty-group <group>
278 Create Unix Vty sockets (for use with vtysh) with group ownership set to
279 `group`. This allows one to create a separate group which is restricted to
280 accessing only the vty sockets, hence allowing one to delegate this group to
281 individual users, or to run vtysh setgid to this group.
283 The default user and group which will be configured is 'frr' if no user or
284 group is specified. Note that this user or group requires write access to the
285 local state directory (see :option:`--localstatedir`) and requires at least
286 read access, and write access if you wish to allow daemons to write out their
287 configuration, to the configuration directory (see :option:`--sysconfdir`).
289 On systems which have the 'libcap' capabilities manipulation library (currently
290 only Linux), FRR will retain only minimal capabilities required and will only
291 raise these capabilities for brief periods. On systems without libcap, FRR will
292 run as the user specified and only raise its UID to 0 for brief periods.
297 .. index:: Building on Linux boxes
298 .. index:: Linux configurations
300 There are several options available only to GNU/Linux systems. If you use
301 GNU/Linux, make sure that the current kernel configuration is what you want.
302 FRR will run with any kernel configuration but some recommendations do exist.
304 :makevar:`CONFIG_NETLINK`
305 Kernel/User Netlink socket. This is a enables an advanced interface between
306 the Linux kernel and *zebra* (:ref:`kernel-interface`).
308 :makevar:`CONFIG_RTNETLINK`
309 This makes it possible to receive Netlink routing messages. If you specify
310 this option, *zebra* can detect routing information updates directly from
311 the kernel (:ref:`kernel-interface`).
313 :makevar:`CONFIG_IP_MULTICAST`
314 This option enables IP multicast and should be specified when you use *ripd*
315 (:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
318 Linux sysctl settings and kernel modules
319 ````````````````````````````````````````
321 There are several kernel parameters that impact overall operation of FRR when
322 using Linux as a router. Generally these parameters should be set in a
323 sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on
324 Ubuntu based systems and a new file
325 :file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems.
326 Additional kernel modules are also needed to support MPLS forwarding.
328 :makevar:`IPv4 and IPv6 forwarding`
329 The following are set to enable IP forwarding in the kernel:
331 .. code-block:: shell
333 net.ipv4.conf.all.forwarding=1
334 net.ipv6.conf.all.forwarding=1
336 :makevar:`MPLS forwarding`
337 Basic MPLS kernel support was introduced 4.1, additional capability
338 was introduced in 4.3 and 4.5. For some general information on Linux
340 https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf.
341 The following modules should be loaded to support MPLS forwarding,
342 and are generally added to a configuration file such as
343 :file:`/etc/modules-load.d/modules.conf`:
345 .. code-block:: shell
347 # Load MPLS Kernel Modules
351 The following is an example to enable MPLS forwarding in the kernel:
353 .. code-block:: shell
355 # Enable MPLS Label processing on all interfaces
356 net.mpls.conf.eth0.input=1
357 net.mpls.conf.eth1.input=1
358 net.mpls.conf.eth2.input=1
359 net.mpls.platform_labels=100000
361 Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for
362 each interface *'<if>'* used with MPLS and to set labels to an
365 :makevar:`VRF forwarding`
366 General information on Linux VRF support can be found in
367 https://www.kernel.org/doc/Documentation/networking/vrf.txt. Kernel
368 support for VRFs was introduced in 4.3 and improved upon through
369 4.13, which is the version most used in FRR testing (as of June
370 2018). Additional background on using Linux VRFs and kernel specific
371 features can be found in
372 http://schd.ws/hosted_files/ossna2017/fe/vrf-tutorial-oss.pdf.
374 The following impacts how BGP TCP sockets are managed across VRFs:
376 .. code-block:: shell
378 net.ipv4.tcp_l3mdev_accept=0
380 With this setting a BGP TCP socket is opened per VRF. This setting
381 ensures that other TCP services, such as SSH, provided for non-VRF
382 purposes are blocked from VRF associated Linux interfaces.
384 .. code-block:: shell
386 net.ipv4.tcp_l3mdev_accept=1
388 With this setting a single BGP TCP socket is shared across the
389 system. This setting exposes any TCP service running on the system,
390 e.g., SSH, to all VRFs. Generally this setting is not used in
391 environments where VRFs are used to support multiple administrative
394 **Important note** as of June 2018, Kernel versions 4.14-4.18 have a
395 known bug where VRF-specific TCP sockets are not properly handled. When
396 running these kernel versions, if unable to establish any VRF BGP
397 adjacencies, either downgrade to 4.13 or set
398 'net.ipv4.tcp_l3mdev_accept=1'. The fix for this issue is planned to be
399 included in future kernel versions so upgrading your kernel may also
406 Once you have chosen your configure options, run the configure script and pass
407 the options you chose:
409 .. code-block:: shell
413 --enable-exampledir=/usr/share/doc/frr/examples/ \
414 --localstatedir=/var/run/frr \
415 --sbindir=/usr/lib/frr \
416 --sysconfdir=/etc/frr \
421 After configuring the software, you are ready to build and install it for your
424 .. code-block:: shell
426 make && sudo make install
428 If everything finishes successfully, FRR should be installed. You should now
429 skip to the section on :ref:`basic-setup`.