]> git.proxmox.com Git - mirror_frr.git/blame - doc/user/installation.rst
Merge pull request #3157 from pguibert6WIND/doc_expanded
[mirror_frr.git] / doc / user / installation.rst
CommitLineData
0efdf0fe 1.. _installation:
42fc5d26 2
42fc5d26 3Installation
717b4866 4============
42fc5d26
QY
5
6.. index:: How to install FRR
42fc5d26 7.. index:: Installation
42fc5d26 8.. index:: Installing FRR
42fc5d26 9.. index:: Building the system
42fc5d26
QY
10.. index:: Making FRR
11
717b4866 12This section covers the basics of building, installing and setting up FRR.
44f2550e 13
717b4866
QY
14From Packages
15-------------
44f2550e 16
717b4866
QY
17The project publishes packages for Red Hat, Centos, Debian and Ubuntu on the
18`GitHub releases <https://github.com/FRRouting/frr/releases>`_. page. External
19contributors offer packages for many other platforms including \*BSD, Alpine,
20Gentoo, Docker, and others. There is currently no documentation on how to use
21those but we hope to add it soon.
42fc5d26 22
717b4866
QY
23From Snapcraft
24--------------
42fc5d26 25
717b4866
QY
26In addition to traditional packages the project also builds and publishes
27universal Snap images, available at https://snapcraft.io/frr.
44f2550e 28
717b4866
QY
29From Source
30-----------
42fc5d26 31
717b4866
QY
32Building FRR from source is the best way to ensure you have the latest features
33and bug fixes. Details for each supported platform, including dependency
34package listings, permissions, and other gotchas, are in the developer's
35documentation. This section provides a brief overview on the process.
42fc5d26 36
717b4866
QY
37Getting the Source
38^^^^^^^^^^^^^^^^^^
42fc5d26 39
717b4866
QY
40FRR's source is available on the project
41`GitHub page <https://github.com/FRRouting/frr>`_.
42fc5d26 42
717b4866 43.. code-block:: shell
42fc5d26 44
717b4866 45 git clone https://github.com/FRRouting/frr.git
42fc5d26 46
717b4866
QY
47When building from Git there are several branches to choose from. The
48``master`` branch is the primary development branch. It should be considered
49unstable. Each release has its own branch named ``stable/X.X``, where ``X.X``
50is the release version.
42fc5d26 51
717b4866
QY
52In addition, release tarballs are published on the GitHub releases page
53`here <https://github.com/FRRouting/frr/releases>`_.
42fc5d26 54
717b4866
QY
55Configuration
56^^^^^^^^^^^^^
42fc5d26 57
717b4866
QY
58.. index:: Configuration options
59.. index:: Options for configuring
60.. index:: Build options
42fc5d26 61.. index:: Distribution configuration
42fc5d26
QY
62.. index:: Options to `./configure`
63
717b4866
QY
64FRR has an excellent configure script which automatically detects most host
65configurations. There are several additional configure options to customize the
66build to include or exclude specific features and dependencies.
67
68First, update the build system. Change into your FRR source directory and issue:
69
70.. code-block:: shell
71
72 ./bootstrap.sh
73
74This will install any missing build scripts and update the Autotools
75configuration. Once this is done you can move on to choosing your configuration
76options from the list below.
77
78.. _frr-configuration:
42fc5d26 79
dc5564c7 80.. program:: configure
42fc5d26 81
dc5564c7 82.. option:: --disable-zebra
42fc5d26 83
dc5564c7 84 Do not build zebra daemon.
42fc5d26 85
dc5564c7 86.. option:: --disable-ripd
42fc5d26 87
dc5564c7 88 Do not build ripd.
42fc5d26 89
dc5564c7 90.. option:: --disable-ripngd
42fc5d26 91
dc5564c7 92 Do not build ripngd.
42fc5d26 93
dc5564c7 94.. option:: --disable-ospfd
42fc5d26 95
dc5564c7 96 Do not build ospfd.
42fc5d26 97
dc5564c7 98.. option:: --disable-ospf6d
42fc5d26 99
dc5564c7 100 Do not build ospf6d.
42fc5d26 101
dc5564c7 102.. option:: --disable-bgpd
42fc5d26 103
dc5564c7 104 Do not build bgpd.
42fc5d26 105
c44032c1
RZ
106.. option:: --disable-bfdd
107
108 Do not build bfdd.
109
dc5564c7 110.. option:: --disable-bgp-announce
42fc5d26 111
dc5564c7
QY
112 Make *bgpd* which does not make bgp announcements at all. This
113 feature is good for using *bgpd* as a BGP announcement listener.
42fc5d26 114
dc5564c7 115.. option:: --enable-datacenter
42fc5d26 116
dc5564c7
QY
117 Enable system defaults to work as if in a Data Center. See defaults.h
118 for what is changed by this configure option.
42fc5d26 119
dc5564c7 120.. option:: --enable-snmp
42fc5d26 121
dc5564c7 122 Enable SNMP support. By default, SNMP support is disabled.
42fc5d26 123
dc5564c7 124.. option:: --disable-ospfapi
42fc5d26 125
dc5564c7
QY
126 Disable support for OSPF-API, an API to interface directly with ospfd.
127 OSPF-API is enabled if --enable-opaque-lsa is set.
128
129.. option:: --disable-ospfclient
130
131 Disable building of the example OSPF-API client.
132
133.. option:: --disable-ospf-ri
134
135 Disable support for OSPF Router Information (RFC4970 & RFC5088) this
136 requires support for Opaque LSAs and Traffic Engineering.
137
138.. option:: --disable-isisd
139
140 Do not build isisd.
141
f3c7b99d
CF
142.. option:: --disable-fabricd
143
144 Do not build fabricd.
145
dc5564c7
QY
146.. option:: --enable-isis-topology
147
148 Enable IS-IS topology generator.
149
150.. option:: --enable-isis-te
151
152 Enable Traffic Engineering Extension for ISIS (RFC5305)
153
a5a48dbf
QY
154.. option:: --enable-realms
155
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.
159
dc5564c7
QY
160.. option:: --disable-rtadv
161
162 Disable support IPV6 router advertisement in zebra.
163
164.. option:: --enable-gcc-rdynamic
165
d1a242fd 166 Pass the ``-rdynamic`` option to the linker driver. This is in most cases
d1e7591e 167 necessary for getting usable backtraces. This option defaults to on if the
d1a242fd 168 compiler is detected as gcc, but giving an explicit enable/disable is
dc5564c7
QY
169 suggested.
170
171.. option:: --disable-backtrace
172
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.
177
178.. option:: --enable-dev-build
179
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
182 of grammar sandbox.
183
184.. option:: --enable-fuzzing
185
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.
189
190.. option:: --disable-snmp
191
192 Build without SNMP support.
42fc5d26 193
c1a54c05
QY
194.. option:: --disable-vtysh
195
196 Build without VTYSH.
42fc5d26 197
013f9762
QY
198.. option:: --enable-fpm
199
200 Build with FPM module support.
201
1f35b46a
QY
202.. option:: --enable-numeric-version
203
204 Alpine Linux does not allow non-numeric characters in the version string.
d1e7591e 205 With this option, we provide a way to strip out these characters for APK dev
1f35b46a
QY
206 package builds.
207
0d8df934
DS
208.. option:: --enable-multipath=X
209
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.
215
83284209
AJ
216.. option:: --enable-gcov
217
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
223 be set.
224
42fc5d26 225You may specify any combination of the above options to the configure
dc5564c7 226script. By default, the executables are placed in :file:`/usr/local/sbin`
42fc5d26 227and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/`
44f2550e 228installation prefix and other directories may be changed using the following
42fc5d26
QY
229options to the configuration script.
230
d1a242fd 231.. option:: --prefix <prefix>
42fc5d26 232
dc5564c7 233 Install architecture-independent files in `prefix` [/usr/local].
42fc5d26 234
d1a242fd 235.. option:: --sysconfdir <dir>
42fc5d26 236
dc5564c7
QY
237 Look for configuration files in `dir` [`prefix`/etc]. Note that sample
238 configuration files will be installed here.
44f2550e 239
d1a242fd 240.. option:: --localstatedir <dir>
42fc5d26 241
d1a242fd
QY
242 Configure zebra to use `dir` for local state files, such as pid files and
243 unix sockets.
42fc5d26 244
11ab5329 245.. _least-privilege-support:
42fc5d26 246
d1a242fd 247Least-Privilege Support
717b4866 248"""""""""""""""""""""""
42fc5d26
QY
249
250.. index:: FRR Least-Privileges
42fc5d26
QY
251.. index:: FRR Privileges
252
253Additionally, you may configure zebra to drop its elevated privileges
254shortly after startup and switch to another user. The configure script will
255automatically try to configure this support. There are three configure
256options to control the behaviour of FRR daemons.
257
d1a242fd 258.. option:: --enable-user <user>
42fc5d26 259
d1a242fd
QY
260 Switch to user `user shortly after startup, and run as user `user` in normal
261 operation.
42fc5d26 262
d1a242fd 263.. option:: --enable-group <user>
42fc5d26 264
d1a242fd 265 Switch real and effective group to `group` shortly after startup.
42fc5d26 266
d1a242fd 267.. option:: --enable-vty-group <group>
dc5564c7 268
d1e7591e
QY
269 Create Unix Vty sockets (for use with vtysh) with group ownership set to
270 `group`. This allows one to create a separate group which is restricted to
d1a242fd
QY
271 accessing only the vty sockets, hence allowing one to delegate this group to
272 individual users, or to run vtysh setgid to this group.
42fc5d26 273
07a17e6d
QY
274The default user and group which will be configured is 'frr' if no user or
275group is specified. Note that this user or group requires write access to the
276local state directory (see :option:`--localstatedir`) and requires at least
277read access, and write access if you wish to allow daemons to write out their
278configuration, to the configuration directory (see :option:`--sysconfdir`).
42fc5d26 279
dc5564c7
QY
280On systems which have the 'libcap' capabilities manipulation library (currently
281only Linux), FRR will retain only minimal capabilities required and will only
282raise these capabilities for brief periods. On systems without libcap, FRR will
283run as the user specified and only raise its UID to 0 for brief periods.
42fc5d26 284
42fc5d26 285Linux Notes
717b4866 286"""""""""""
42fc5d26
QY
287
288.. index:: Building on Linux boxes
42fc5d26
QY
289.. index:: Linux configurations
290
717b4866
QY
291There are several options available only to GNU/Linux systems. If you use
292GNU/Linux, make sure that the current kernel configuration is what you want.
293FRR will run with any kernel configuration but some recommendations do exist.
42fc5d26 294
717b4866
QY
295:makevar:`CONFIG_NETLINK`
296 Kernel/User Netlink socket. This is a enables an advanced interface between
297 the Linux kernel and *zebra* (:ref:`kernel-interface`).
42fc5d26 298
717b4866
QY
299:makevar:`CONFIG_RTNETLINK`
300 This makes it possible to receive Netlink routing messages. If you specify
301 this option, *zebra* can detect routing information updates directly from
302 the kernel (:ref:`kernel-interface`).
44f2550e 303
717b4866
QY
304:makevar:`CONFIG_IP_MULTICAST`
305 This option enables IP multicast and should be specified when you use *ripd*
306 (:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
307 multicast.
42fc5d26 308
3c29c38d
LB
309Linux sysctl settings and kernel modules
310````````````````````````````````````````
311
312There are several kernel parameters that impact overall operation of FRR when
313using Linux as a router. Generally these parameters should be set in a
314sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on
315Ubuntu based systems and a new file
316:file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems.
317Additional kernel modules are also needed to support MPLS forwarding.
318
319:makevar:`IPv4 and IPv6 forwarding`
320 The following are set to enable IP forwarding in the kernel:
321
322 .. code-block:: shell
323
324 net.ipv4.conf.all.forwarding=1
325 net.ipv6.conf.all.forwarding=1
326
327:makevar:`MPLS forwarding`
328 Basic MPLS kernel support was introduced 4.1, additional capability
329 was introduced in 4.3 and 4.5. For some general information on Linux
330 MPLS support see
331 https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf.
332 The following modules should be loaded to support MPLS forwarding,
333 and are generally added to a configuration file such as
334 :file:`/etc/modules-load.d/modules.conf`:
335
336 .. code-block:: shell
337
338 # Load MPLS Kernel Modules
339 mpls_router
340 mpls_iptunnel
341
342 The following is an example to enable MPLS forwarding in the kernel:
343
344 .. code-block:: shell
345
346 # Enable MPLS Label processing on all interfaces
347 net.mpls.conf.eth0.input=1
348 net.mpls.conf.eth1.input=1
349 net.mpls.conf.eth2.input=1
350 net.mpls.platform_labels=100000
351
352 Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for
353 each interface *'<if>'* used with MPLS and to set labels to an
354 appropriate value.
355
356:makevar:`VRF forwarding`
357 General information on Linux VRF support can be found in
358 https://www.kernel.org/doc/Documentation/networking/vrf.txt. Kernel
359 support for VRFs was introduced in 4.3 and improved upon through
360 4.13, which is the version most used in FRR testing (as of June
361 2018). Additional background on using Linux VRFs and kernel specific
362 features can be found in
363 http://schd.ws/hosted_files/ossna2017/fe/vrf-tutorial-oss.pdf.
364
365 The following impacts how BGP TCP sockets are managed across VRFs:
366
367 .. code-block:: shell
368
369 net.ipv4.tcp_l3mdev_accept=0
370
371 With this setting a BGP TCP socket is opened per VRF. This setting
372 ensures that other TCP services, such as SSH, provided for non-VRF
373 purposes are blocked from VRF associated Linux interfaces.
374
375 .. code-block:: shell
376
377 net.ipv4.tcp_l3mdev_accept=1
378
379 With this setting a single BGP TCP socket is shared across the
380 system. This setting exposes any TCP service running on the system,
381 e.g., SSH, to all VRFs. Generally this setting is not used in
382 environments where VRFs are used to support multiple administrative
383 groups.
384
385 **Important note** as of June 2018, Kernel versions 4.14-4.18 have a
386 known bug where VRF-specific TCP sockets are not properly handled. When
387 running these kernel versions, if unable to establish any VRF BGP
388 adjacencies, either downgrade to 4.13 or set
389 'net.ipv4.tcp_l3mdev_accept=1'. The fix for this issue is planned to be
390 included in future kernel versions so upgrading your kernel may also
391 address this issue.
392
393
717b4866
QY
394Building
395^^^^^^^^
42fc5d26 396
717b4866
QY
397Once you have chosen your configure options, run the configure script and pass
398the options you chose:
42fc5d26 399
717b4866 400.. code-block:: shell
42fc5d26 401
717b4866
QY
402 ./configure \
403 --prefix=/usr \
404 --enable-exampledir=/usr/share/doc/frr/examples/ \
405 --localstatedir=/var/run/frr \
406 --sbindir=/usr/lib/frr \
407 --sysconfdir=/etc/frr \
408 --enable-pimd \
409 --enable-watchfrr \
410 ...
44f2550e 411
717b4866
QY
412After configuring the software, you are ready to build and install it for your
413system.
42fc5d26 414
717b4866 415.. code-block:: shell
42fc5d26 416
717b4866 417 make && sudo make install
42fc5d26 418
717b4866
QY
419If everything finishes successfully, FRR should be installed. You should now
420skip to the section on :ref:`basic-setup`.