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:: --disable-zebra
  83
  84    Do not build zebra daemon.
  85
  86 .. option:: --disable-ripd
  87
  88    Do not build ripd.
  89
  90 .. option:: --disable-ripngd
  91
  92    Do not build ripngd.
  93
  94 .. option:: --disable-ospfd
  95
  96    Do not build ospfd.
  97
  98 .. option:: --disable-ospf6d
  99
 100    Do not build ospf6d.
 101
 102 .. option:: --disable-bgpd
 103
 104    Do not build bgpd.
 105
 106 .. option:: --disable-bfdd
 107
 108    Do not build bfdd.
 109
 110 .. option:: --disable-bgp-announce
 111
 112    Make *bgpd* which does not make bgp announcements at all.  This
 113    feature is good for using *bgpd* as a BGP announcement listener.
 114
 115 .. option:: --enable-datacenter
 116
 117    Enable system defaults to work as if in a Data Center. See defaults.h
 118    for what is changed by this configure option.
 119
 120 .. option:: --enable-snmp
 121
 122    Enable SNMP support.  By default, SNMP support is disabled.
 123
 124 .. option:: --disable-ospfapi
 125
 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
 142 .. option:: --disable-fabricd
 143
 144    Do not build fabricd.
 145
 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
 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
 160 .. option:: --disable-rtadv
 161
 162    Disable support IPV6 router advertisement in zebra.
 163
 164 .. option:: --enable-gcc-rdynamic
 165
 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
 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.
 193
 194 .. option:: --disable-vtysh
 195
 196    Build without VTYSH.
 197
 198 .. option:: --enable-fpm
 199
 200    Build with FPM module support.
 201
 202 .. option:: --enable-numeric-version
 203
 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
 206    package builds.
 207
 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
 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
 225 .. option:: --enable-config-rollbacks
 226
 227    Build with configuration rollback support. Requires SQLite3.
 228
 229 .. option:: --enable-confd=<dir>
 230
 231    Build the ConfD northbound plugin. Look for the libconfd libs and headers
 232    in `dir`.
 233
 234 .. option:: --enable-sysrepo
 235
 236    Build the Sysrepo northbound plugin.
 237
 238 You may specify any combination of the above options to the configure
 239 script. By default, the executables are placed in :file:`/usr/local/sbin`
 240 and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/`
 241 installation prefix and other directories may be changed using the following
 242 options to the configuration script.
 243
 244 .. option:: --prefix <prefix>
 245
 246    Install architecture-independent files in `prefix` [/usr/local].
 247
 248 .. option:: --sysconfdir <dir>
 249
 250    Look for configuration files in `dir` [`prefix`/etc]. Note that sample
 251    configuration files will be installed here.
 252
 253 .. option:: --localstatedir <dir>
 254
 255    Configure zebra to use `dir` for local state files, such as pid files and
 256    unix sockets.
 257
 258 .. option:: --with-yangmodelsdir <dir>
 259
 260    Look for YANG modules in `dir` [`prefix`/share/yang]. Note that the FRR
 261    YANG modules will be installed here.
 262
 263 .. option:: --with-libyang-pluginsdir <dir>
 264
 265    Look for libyang plugins in `dir` [`prefix`/lib/frr/libyang_plugins].
 266    Note that the FRR libyang plugins will be installed here.
 267
 268 When it's desired to run FRR without installing it in the system, it's possible
 269 to configure it as follows to look for YANG modules and libyang plugins in the
 270 compile directory:
 271 .. code-block:: shell
 272
 273    ./configure --with-libyang-pluginsdir="`pwd`/yang/libyang_plugins/.libs" \
 274                --with-yangmodelsdir="`pwd`/yang"
 275
 276 .. _least-privilege-support:
 277
 278 Least-Privilege Support
 279 """""""""""""""""""""""
 280
 281 .. index:: FRR Least-Privileges
 282 .. index:: FRR Privileges
 283
 284 Additionally, you may configure zebra to drop its elevated privileges
 285 shortly after startup and switch to another user. The configure script will
 286 automatically try to configure this support. There are three configure
 287 options to control the behaviour of FRR daemons.
 288
 289 .. option:: --enable-user <user>
 290
 291    Switch to user `user shortly after startup, and run as user `user` in normal
 292    operation.
 293
 294 .. option:: --enable-group <user>
 295
 296    Switch real and effective group to `group` shortly after startup.
 297
 298 .. option:: --enable-vty-group <group>
 299
 300    Create Unix Vty sockets (for use with vtysh) with group ownership set to
 301    `group`. This allows one to create a separate group which is restricted to
 302    accessing only the vty sockets, hence allowing one to delegate this group to
 303    individual users, or to run vtysh setgid to this group.
 304
 305 The default user and group which will be configured is 'frr' if no user or
 306 group is specified. Note that this user or group requires write access to the
 307 local state directory (see :option:`--localstatedir`) and requires at least
 308 read access, and write access if you wish to allow daemons to write out their
 309 configuration, to the configuration directory (see :option:`--sysconfdir`).
 310
 311 On systems which have the 'libcap' capabilities manipulation library (currently
 312 only Linux), FRR will retain only minimal capabilities required and will only
 313 raise these capabilities for brief periods. On systems without libcap, FRR will
 314 run as the user specified and only raise its UID to 0 for brief periods.
 315
 316 Linux Notes
 317 """""""""""
 318
 319 .. index:: Building on Linux boxes
 320 .. index:: Linux configurations
 321
 322 There are several options available only to GNU/Linux systems.  If you use
 323 GNU/Linux, make sure that the current kernel configuration is what you want.
 324 FRR will run with any kernel configuration but some recommendations do exist.
 325
 326 :makevar:`CONFIG_NETLINK`
 327    Kernel/User Netlink socket. This is a enables an advanced interface between
 328    the Linux kernel and *zebra* (:ref:`kernel-interface`).
 329
 330 :makevar:`CONFIG_RTNETLINK`
 331    This makes it possible to receive Netlink routing messages.  If you specify
 332    this option, *zebra* can detect routing information updates directly from
 333    the kernel (:ref:`kernel-interface`).
 334
 335 :makevar:`CONFIG_IP_MULTICAST`
 336    This option enables IP multicast and should be specified when you use *ripd*
 337    (:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
 338    multicast.
 339
 340 Linux sysctl settings and kernel modules
 341 ````````````````````````````````````````
 342
 343 There are several kernel parameters that impact overall operation of FRR when
 344 using Linux as a router. Generally these parameters should be set in a
 345 sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on
 346 Ubuntu based systems and a new file
 347 :file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems.
 348 Additional kernel modules are also needed to support MPLS forwarding.
 349
 350 :makevar:`IPv4 and IPv6 forwarding`
 351    The following are set to enable IP forwarding in the kernel:
 352
 353    .. code-block:: shell
 354
 355       net.ipv4.conf.all.forwarding=1
 356       net.ipv6.conf.all.forwarding=1
 357
 358 :makevar:`MPLS forwarding`
 359    Basic MPLS kernel support was introduced 4.1, additional capability
 360    was introduced in 4.3 and 4.5. For some general information on Linux
 361    MPLS support see
 362    https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf.
 363    The following modules should be loaded to support MPLS forwarding,
 364    and are generally added to a configuration file such as
 365    :file:`/etc/modules-load.d/modules.conf`:
 366
 367    .. code-block:: shell
 368
 369       # Load MPLS Kernel Modules
 370       mpls_router
 371       mpls_iptunnel
 372
 373    The following is an example to enable MPLS forwarding in the kernel:
 374
 375    .. code-block:: shell
 376
 377       # Enable MPLS Label processing on all interfaces
 378       net.mpls.conf.eth0.input=1
 379       net.mpls.conf.eth1.input=1
 380       net.mpls.conf.eth2.input=1
 381       net.mpls.platform_labels=100000
 382
 383    Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for
 384    each interface *'<if>'* used with MPLS and to set labels to an
 385    appropriate value.
 386
 387 :makevar:`VRF forwarding`
 388    General information on Linux VRF support can be found in
 389    https://www.kernel.org/doc/Documentation/networking/vrf.txt. Kernel
 390    support for VRFs was introduced in 4.3 and improved upon through
 391    4.13, which is the version most used in FRR testing (as of June
 392    2018).  Additional background on using Linux VRFs and kernel specific
 393    features can be found in
 394    http://schd.ws/hosted_files/ossna2017/fe/vrf-tutorial-oss.pdf.
 395
 396    The following impacts how BGP TCP sockets are managed across VRFs:
 397
 398    .. code-block:: shell
 399
 400       net.ipv4.tcp_l3mdev_accept=0
 401
 402    With this setting a BGP TCP socket is opened per VRF.  This setting
 403    ensures that other TCP services, such as SSH, provided for non-VRF
 404    purposes are blocked from VRF associated Linux interfaces.
 405
 406    .. code-block:: shell
 407
 408       net.ipv4.tcp_l3mdev_accept=1
 409
 410    With this setting a single BGP TCP socket is shared across the
 411    system.  This setting exposes any TCP service running on the system,
 412    e.g., SSH, to all VRFs.  Generally this setting is not used in
 413    environments where VRFs are used to support multiple administrative
 414    groups.
 415
 416    **Important note** as of June 2018, Kernel versions 4.14-4.18 have a
 417    known bug where VRF-specific TCP sockets are not properly handled. When
 418    running these kernel versions, if unable to establish any VRF BGP
 419    adjacencies, either downgrade to 4.13 or set
 420    'net.ipv4.tcp_l3mdev_accept=1'. The fix for this issue is planned to be
 421    included in future kernel versions so upgrading your kernel may also
 422    address this issue.
 423
 424
 425 Building
 426 ^^^^^^^^
 427
 428 Once you have chosen your configure options, run the configure script and pass
 429 the options you chose:
 430
 431 .. code-block:: shell
 432
 433    ./configure \
 434        --prefix=/usr \
 435        --enable-exampledir=/usr/share/doc/frr/examples/ \
 436        --localstatedir=/var/run/frr \
 437        --sbindir=/usr/lib/frr \
 438        --sysconfdir=/etc/frr \
 439        --enable-pimd \
 440        --enable-watchfrr \
 441        ...
 442
 443 After configuring the software, you are ready to build and install it for your
 444 system.
 445
 446 .. code-block:: shell
 447
 448    make && sudo make install
 449
 450 If everything finishes successfully, FRR should be installed. You should now
 451 skip to the section on :ref:`basic-setup`.