doc/user/installation.rst

   1 .. _installation:
   2
   3 Installation
   4 ============
   5
   6 .. index:: How to install FRR
   7 .. index:: Installation
   8 .. index:: Installing FRR
   9 .. index:: Building the system
  10 .. index:: Making FRR
  11
  12 This section covers the basics of building, installing and setting up FRR.
  13
  14 From Packages
  15 -------------
  16
  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.
  22
  23 From Snapcraft
  24 --------------
  25
  26 In addition to traditional packages the project also builds and publishes
  27 universal Snap images, available at https://snapcraft.io/frr.
  28
  29 From Source
  30 -----------
  31
  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.
  36
  37 Getting the Source
  38 ^^^^^^^^^^^^^^^^^^
  39
  40 FRR's source is available on the project
  41 `GitHub page <https://github.com/FRRouting/frr>`_.
  42
  43 .. code-block:: shell
  44
  45    git clone https://github.com/FRRouting/frr.git
  46
  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.
  51
  52 In addition, release tarballs are published on the GitHub releases page
  53 `here <https://github.com/FRRouting/frr/releases>`_.
  54
  55 Configuration
  56 ^^^^^^^^^^^^^
  57
  58 .. index:: Configuration options
  59 .. index:: Options for configuring
  60 .. index:: Build options
  61 .. index:: Distribution configuration
  62 .. index:: Options to `./configure`
  63
  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.
  67
  68 First, update the build system. Change into your FRR source directory and issue:
  69
  70 .. code-block:: shell
  71
  72    ./bootstrap.sh
  73
  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.
  77
  78 .. _frr-configuration:
  79
  80 .. program:: configure
  81
  82 .. option:: --enable-tcmalloc
  83
  84    Enable the alternate malloc library.  In some cases this is faster and more efficient,
  85    in some cases it is not.
  86
  87 .. option:: --disable-doc
  88
  89    Do not build any documentation, including this one.
  90
  91 .. option:: --enable-doc-html
  92
  93    From the documentation build html docs as well in addition to the normal output.
  94
  95 .. option:: --disable-zebra
  96
  97    Do not build zebra daemon.  This generally only be useful in a scenario where
  98    you are building bgp as a standalone server.
  99
 100 .. option:: --disable-ripd
 101
 102    Do not build ripd.
 103
 104 .. option:: --disable-ripngd
 105
 106    Do not build ripngd.
 107
 108 .. option:: --disable-ospfd
 109
 110    Do not build ospfd.
 111
 112 .. option:: --disable-ospf6d
 113
 114    Do not build ospf6d.
 115
 116 .. option:: --disable-bgpd
 117
 118    Do not build bgpd.
 119
 120 .. option:: --disable-ldpd
 121
 122    Do not build ldpd.
 123
 124 .. option:: --disable-nhrpd
 125
 126    Do not build nhrpd.
 127
 128 .. option:: --disable-eigrpd
 129
 130    Do not build eigrpd.
 131
 132 .. option:: --disable-babeld
 133
 134    Do not build babeld.
 135
 136 .. option:: --disable-watchfrr
 137
 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.
 141
 142 .. option:: --enable-systemd
 143
 144    Build watchfrr with systemd integration, this will allow FRR to communicate with
 145    systemd to tell systemd if FRR has come up properly.
 146
 147 .. option:: --disable-pimd
 148
 149    Turn off building of pimd.  On some BSD platforms pimd will not build properly due
 150    to lack of kernel support.
 151
 152 .. option:: --disable-pbrd
 153
 154    Turn off building of pbrd.  This daemon currently requires linux in order to function
 155    properly.
 156
 157 .. option:: --enable-sharpd
 158
 159    Turn on building of sharpd.  This daemon facilitates testing of FRR and can also
 160    be used as a quick and easy route generator.
 161
 162 .. option:: --disable-staticd
 163
 164    Do not build staticd.  This daemon is necessary if you want static routes.
 165
 166 .. option:: --disable-bfdd
 167
 168    Do not build bfdd.
 169
 170 .. option:: --disable-bgp-announce
 171
 172    Make *bgpd* which does not make bgp announcements at all.  This
 173    feature is good for using *bgpd* as a BGP announcement listener.
 174
 175 .. option:: --disable-bgp-vnc
 176
 177    Turn off bgpd's ability to use VNC.
 178
 179 .. option:: --enable-datacenter
 180
 181    Enable system defaults to work as if in a Data Center. See defaults.h
 182    for what is changed by this configure option.
 183
 184 .. option:: --enable-snmp
 185
 186    Enable SNMP support.  By default, SNMP support is disabled.
 187
 188 .. option:: --disable-ospfapi
 189
 190    Disable support for OSPF-API, an API to interface directly with ospfd.
 191    OSPF-API is enabled if --enable-opaque-lsa is set.
 192
 193 .. option:: --disable-ospfclient
 194
 195    Disable building of the example OSPF-API client.
 196
 197 .. option:: --disable-ospf-ri
 198
 199    Disable support for OSPF Router Information (RFC4970 & RFC5088) this
 200    requires support for Opaque LSAs and Traffic Engineering.
 201
 202 .. option:: --disable-isisd
 203
 204    Do not build isisd.
 205
 206 .. option:: --disable-fabricd
 207
 208    Do not build fabricd.
 209
 210 .. option:: --enable-isis-topology
 211
 212    Enable IS-IS topology generator.
 213
 214 .. option:: --enable-isis-te
 215
 216    Enable Traffic Engineering Extension for ISIS (RFC5305)
 217
 218 .. option:: --enable-realms
 219
 220    Enable the support of Linux Realms. Convert tag values from 1-255 into a
 221    realm value when inserting into the Linux kernel. Then routing policy can be
 222    assigned to the realm. See the tc man page.
 223
 224 .. option:: --disable-rtadv
 225
 226    Disable support IPV6 router advertisement in zebra.
 227
 228 .. option:: --enable-gcc-rdynamic
 229
 230    Pass the ``-rdynamic`` option to the linker driver.  This is in most cases
 231    necessary for getting usable backtraces.  This option defaults to on if the
 232    compiler is detected as gcc, but giving an explicit enable/disable is
 233    suggested.
 234
 235 .. option:: --disable-backtrace
 236
 237    Controls backtrace support for the crash handlers. This is autodetected by
 238    default. Using the switch will enforce the requested behaviour, failing with
 239    an error if support is requested but not available.  On BSD systems, this
 240    needs libexecinfo, while on glibc support for this is part of libc itself.
 241
 242 .. option:: --enable-dev-build
 243
 244    Turn on some options for compiling FRR within a development environment in
 245    mind.  Specifically turn on -g3 -O0 for compiling options and add inclusion
 246    of grammar sandbox.
 247
 248 .. option:: --enable-fuzzing
 249
 250    Turn on some compile options to allow you to run fuzzing tools against the
 251    system. This flag is intended as a developer only tool and should not be
 252    used for normal operations.
 253
 254 .. option:: --disable-snmp
 255
 256    Build without SNMP support.
 257
 258 .. option:: --disable-vtysh
 259
 260    Build without VTYSH.
 261
 262 .. option:: --enable-fpm
 263
 264    Build with FPM module support.
 265
 266 .. option:: --enable-numeric-version
 267
 268    Alpine Linux does not allow non-numeric characters in the version string.
 269    With this option, we provide a way to strip out these characters for APK dev
 270    package builds.
 271
 272 .. option:: --enable-multipath=X
 273
 274    Compile FRR with up to X way ECMP supported.  This number can be from 0-999.
 275    For backwards compatibility with older configure options when setting X = 0,
 276    we will build FRR with 64 way ECMP.  This is needed because there are
 277    hardcoded arrays that FRR builds towards, so we need to know how big to
 278    make these arrays at build time.  Additionally if this parameter is
 279    not passed in FRR will default to 16 ECMP.
 280
 281 .. option:: --enable-shell-access
 282
 283    Turn on the ability of FRR to access some shell options( telnet/ssh/bash/etc. )
 284    from vtysh itself.  This option is considered extremely unsecure and should only
 285    be considered for usage if you really really know what you are doing.
 286
 287 .. option:: --enable-gcov
 288
 289    Code coverage reports from gcov require adjustments to the C and LD flags.
 290    With this option, gcov instrumentation is added to the build and coverage
 291    reports are created during execution.  The check-coverage make target is
 292    also created to ease report uploading to codecov.io.  The upload requires
 293    the COMMIT (git hash) and TOKEN (codecov upload token) environment variables
 294    be set.
 295
 296 .. option:: --enable-config-rollbacks
 297
 298    Build with configuration rollback support. Requires SQLite3.
 299
 300 .. option:: --enable-confd=<dir>
 301
 302    Build the ConfD northbound plugin. Look for the libconfd libs and headers
 303    in `dir`.
 304
 305 .. option:: --enable-sysrepo
 306
 307    Build the Sysrepo northbound plugin.
 308
 309 You may specify any combination of the above options to the configure
 310 script. By default, the executables are placed in :file:`/usr/local/sbin`
 311 and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/`
 312 installation prefix and other directories may be changed using the following
 313 options to the configuration script.
 314
 315 .. option:: --prefix <prefix>
 316
 317    Install architecture-independent files in `prefix` [/usr/local].
 318
 319 .. option:: --sysconfdir <dir>
 320
 321    Look for configuration files in `dir` [`prefix`/etc]. Note that sample
 322    configuration files will be installed here.
 323
 324 .. option:: --localstatedir <dir>
 325
 326    Configure zebra to use `dir` for local state files, such as pid files and
 327    unix sockets.
 328
 329 .. option:: --with-yangmodelsdir <dir>
 330
 331    Look for YANG modules in `dir` [`prefix`/share/yang]. Note that the FRR
 332    YANG modules will be installed here.
 333
 334 .. option:: --with-libyang-pluginsdir <dir>
 335
 336    Look for libyang plugins in `dir` [`prefix`/lib/frr/libyang_plugins].
 337    Note that the FRR libyang plugins will be installed here.
 338
 339    This option is meaningless with libyang 0.16.74 or newer and will be
 340    removed once support for older libyang versions is dropped.
 341
 342 When it's desired to run FRR without installing it in the system, it's possible
 343 to configure it as follows to look for YANG modules and libyang plugins in the
 344 compile directory:
 345 .. code-block:: shell
 346
 347    ./configure --with-libyang-pluginsdir="`pwd`/yang/libyang_plugins/.libs" \
 348                --with-yangmodelsdir="`pwd`/yang"
 349
 350 .. _least-privilege-support:
 351
 352 Least-Privilege Support
 353 """""""""""""""""""""""
 354
 355 .. index:: FRR Least-Privileges
 356 .. index:: FRR Privileges
 357
 358 Additionally, you may configure zebra to drop its elevated privileges
 359 shortly after startup and switch to another user. The configure script will
 360 automatically try to configure this support. There are three configure
 361 options to control the behaviour of FRR daemons.
 362
 363 .. option:: --enable-user <user>
 364
 365    Switch to user `user shortly after startup, and run as user `user` in normal
 366    operation.
 367
 368 .. option:: --enable-group <user>
 369
 370    Switch real and effective group to `group` shortly after startup.
 371
 372 .. option:: --enable-vty-group <group>
 373
 374    Create Unix Vty sockets (for use with vtysh) with group ownership set to
 375    `group`. This allows one to create a separate group which is restricted to
 376    accessing only the vty sockets, hence allowing one to delegate this group to
 377    individual users, or to run vtysh setgid to this group.
 378
 379 The default user and group which will be configured is 'frr' if no user or
 380 group is specified. Note that this user or group requires write access to the
 381 local state directory (see :option:`--localstatedir`) and requires at least
 382 read access, and write access if you wish to allow daemons to write out their
 383 configuration, to the configuration directory (see :option:`--sysconfdir`).
 384
 385 On systems which have the 'libcap' capabilities manipulation library (currently
 386 only Linux), FRR will retain only minimal capabilities required and will only
 387 raise these capabilities for brief periods. On systems without libcap, FRR will
 388 run as the user specified and only raise its UID to 0 for brief periods.
 389
 390 Linux Notes
 391 """""""""""
 392
 393 .. index:: Building on Linux boxes
 394 .. index:: Linux configurations
 395
 396 There are several options available only to GNU/Linux systems.  If you use
 397 GNU/Linux, make sure that the current kernel configuration is what you want.
 398 FRR will run with any kernel configuration but some recommendations do exist.
 399
 400 :makevar:`CONFIG_NETLINK`
 401    Kernel/User Netlink socket. This enables an advanced interface between
 402    the Linux kernel and *zebra* (:ref:`kernel-interface`).
 403
 404 :makevar:`CONFIG_RTNETLINK`
 405    This makes it possible to receive Netlink routing messages.  If you specify
 406    this option, *zebra* can detect routing information updates directly from
 407    the kernel (:ref:`kernel-interface`).
 408
 409 :makevar:`CONFIG_IP_MULTICAST`
 410    This option enables IP multicast and should be specified when you use *ripd*
 411    (:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
 412    multicast.
 413
 414 Linux sysctl settings and kernel modules
 415 ````````````````````````````````````````
 416
 417 There are several kernel parameters that impact overall operation of FRR when
 418 using Linux as a router. Generally these parameters should be set in a
 419 sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on
 420 Ubuntu based systems and a new file
 421 :file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems.
 422 Additional kernel modules are also needed to support MPLS forwarding.
 423
 424 :makevar:`IPv4 and IPv6 forwarding`
 425    The following are set to enable IP forwarding in the kernel:
 426
 427    .. code-block:: shell
 428
 429       net.ipv4.conf.all.forwarding=1
 430       net.ipv6.conf.all.forwarding=1
 431
 432 :makevar:`MPLS forwarding`
 433    Basic MPLS support was introduced in the kernel in version 4.1 and
 434    additional capability was introduced in 4.3 and 4.5.
 435    For some general information on Linux MPLS support, see
 436    https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf.
 437    The following modules should be loaded to support MPLS forwarding,
 438    and are generally added to a configuration file such as
 439    :file:`/etc/modules-load.d/modules.conf`:
 440
 441    .. code-block:: shell
 442
 443       # Load MPLS Kernel Modules
 444       mpls_router
 445       mpls_iptunnel
 446
 447    The following is an example to enable MPLS forwarding in the kernel:
 448
 449    .. code-block:: shell
 450
 451       # Enable MPLS Label processing on all interfaces
 452       net.mpls.conf.eth0.input=1
 453       net.mpls.conf.eth1.input=1
 454       net.mpls.conf.eth2.input=1
 455       net.mpls.platform_labels=100000
 456
 457    Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for
 458    each interface *'<if>'* used with MPLS and to set labels to an
 459    appropriate value.
 460
 461 :makevar:`VRF forwarding`
 462    General information on Linux VRF support can be found in
 463    https://www.kernel.org/doc/Documentation/networking/vrf.txt. Kernel
 464    support for VRFs was introduced in 4.3 and improved upon through
 465    4.13, which is the version most used in FRR testing (as of June
 466    2018).  Additional background on using Linux VRFs and kernel specific
 467    features can be found in
 468    http://schd.ws/hosted_files/ossna2017/fe/vrf-tutorial-oss.pdf.
 469
 470    The following impacts how BGP TCP sockets are managed across VRFs:
 471
 472    .. code-block:: shell
 473
 474       net.ipv4.tcp_l3mdev_accept=0
 475
 476    With this setting a BGP TCP socket is opened per VRF.  This setting
 477    ensures that other TCP services, such as SSH, provided for non-VRF
 478    purposes are blocked from VRF associated Linux interfaces.
 479
 480    .. code-block:: shell
 481
 482       net.ipv4.tcp_l3mdev_accept=1
 483
 484    With this setting a single BGP TCP socket is shared across the
 485    system.  This setting exposes any TCP service running on the system,
 486    e.g., SSH, to all VRFs.  Generally this setting is not used in
 487    environments where VRFs are used to support multiple administrative
 488    groups.
 489
 490    **Important note** as of June 2018, Kernel versions 4.14-4.18 have a
 491    known bug where VRF-specific TCP sockets are not properly handled. When
 492    running these kernel versions, if unable to establish any VRF BGP
 493    adjacencies, either downgrade to 4.13 or set
 494    'net.ipv4.tcp_l3mdev_accept=1'. The fix for this issue is planned to be
 495    included in future kernel versions. So upgrading your kernel may also
 496    address this issue.
 497
 498
 499 Building
 500 ^^^^^^^^
 501
 502 Once you have chosen your configure options, run the configure script and pass
 503 the options you chose:
 504
 505 .. code-block:: shell
 506
 507    ./configure \
 508        --prefix=/usr \
 509        --enable-exampledir=/usr/share/doc/frr/examples/ \
 510        --localstatedir=/var/run/frr \
 511        --sbindir=/usr/lib/frr \
 512        --sysconfdir=/etc/frr \
 513        --enable-pimd \
 514        --enable-watchfrr \
 515        ...
 516
 517 After configuring the software, you are ready to build and install it in your
 518 system.
 519
 520 .. code-block:: shell
 521
 522    make && sudo make install
 523
 524 If everything finishes successfully, FRR should be installed. You should now
 525 skip to the section on :ref:`basic-setup`.