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-bgp-announce
 107
 108    Make *bgpd* which does not make bgp announcements at all.  This
 109    feature is good for using *bgpd* as a BGP announcement listener.
 110
 111 .. option:: --enable-datacenter
 112
 113    Enable system defaults to work as if in a Data Center. See defaults.h
 114    for what is changed by this configure option.
 115
 116 .. option:: --enable-snmp
 117
 118    Enable SNMP support.  By default, SNMP support is disabled.
 119
 120 .. option:: --disable-ospfapi
 121
 122    Disable support for OSPF-API, an API to interface directly with ospfd.
 123    OSPF-API is enabled if --enable-opaque-lsa is set.
 124
 125 .. option:: --disable-ospfclient
 126
 127    Disable building of the example OSPF-API client.
 128
 129 .. option:: --disable-ospf-ri
 130
 131    Disable support for OSPF Router Information (RFC4970 & RFC5088) this
 132    requires support for Opaque LSAs and Traffic Engineering.
 133
 134 .. option:: --disable-isisd
 135
 136    Do not build isisd.
 137
 138 .. option:: --enable-isis-topology
 139
 140    Enable IS-IS topology generator.
 141
 142 .. option:: --enable-isis-te
 143
 144    Enable Traffic Engineering Extension for ISIS (RFC5305)
 145
 146 .. option:: --enable-realms
 147
 148    Enable the support of Linux Realms. Convert tag values from 1-255 into a
 149    realm value when inserting into the Linux kernel. Then routing policy can be
 150    assigned to the realm. See the tc man page.
 151
 152 .. option:: --disable-rtadv
 153
 154    Disable support IPV6 router advertisement in zebra.
 155
 156 .. option:: --enable-gcc-rdynamic
 157
 158    Pass the ``-rdynamic`` option to the linker driver.  This is in most cases
 159    necessary for getting usable backtraces.  This option defaults to on if the
 160    compiler is detected as gcc, but giving an explicit enable/disable is
 161    suggested.
 162
 163 .. option:: --disable-backtrace
 164
 165    Controls backtrace support for the crash handlers. This is autodetected by
 166    default. Using the switch will enforce the requested behaviour, failing with
 167    an error if support is requested but not available.  On BSD systems, this
 168    needs libexecinfo, while on glibc support for this is part of libc itself.
 169
 170 .. option:: --enable-dev-build
 171
 172    Turn on some options for compiling FRR within a development environment in
 173    mind.  Specifically turn on -g3 -O0 for compiling options and add inclusion
 174    of grammar sandbox.
 175
 176 .. option:: --enable-fuzzing
 177
 178    Turn on some compile options to allow you to run fuzzing tools against the
 179    system. This flag is intended as a developer only tool and should not be
 180    used for normal operations.
 181
 182 .. option:: --disable-snmp
 183
 184    Build without SNMP support.
 185
 186 .. option:: --disable-vtysh
 187
 188    Build without VTYSH.
 189
 190 .. option:: --enable-fpm
 191
 192    Build with FPM module support.
 193
 194 .. option:: --enable-numeric-version
 195
 196    Alpine Linux does not allow non-numeric characters in the version string.
 197    With this option, we provide a way to strip out these characters for APK dev
 198    package builds.
 199
 200 .. option:: --enable-multipath=X
 201
 202    Compile FRR with up to X way ECMP supported.  This number can be from 0-999.
 203    For backwards compatability with older configure options when setting X = 0,
 204    we will build FRR with 64 way ECMP.  This is needed because there are
 205    hardcoded arrays that FRR builds towards, so we need to know how big to
 206    make these arrays at build time.
 207
 208 You may specify any combination of the above options to the configure
 209 script. By default, the executables are placed in :file:`/usr/local/sbin`
 210 and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/`
 211 installation prefix and other directories may be changed using the following
 212 options to the configuration script.
 213
 214 .. option:: --prefix <prefix>
 215
 216    Install architecture-independent files in `prefix` [/usr/local].
 217
 218 .. option:: --sysconfdir <dir>
 219
 220    Look for configuration files in `dir` [`prefix`/etc]. Note that sample
 221    configuration files will be installed here.
 222
 223 .. option:: --localstatedir <dir>
 224
 225    Configure zebra to use `dir` for local state files, such as pid files and
 226    unix sockets.
 227
 228 .. _least-privilege-support:
 229
 230 Least-Privilege Support
 231 """""""""""""""""""""""
 232
 233 .. index:: FRR Least-Privileges
 234 .. index:: FRR Privileges
 235
 236 Additionally, you may configure zebra to drop its elevated privileges
 237 shortly after startup and switch to another user. The configure script will
 238 automatically try to configure this support. There are three configure
 239 options to control the behaviour of FRR daemons.
 240
 241 .. option:: --enable-user <user>
 242
 243    Switch to user `user shortly after startup, and run as user `user` in normal
 244    operation.
 245
 246 .. option:: --enable-group <user>
 247
 248    Switch real and effective group to `group` shortly after startup.
 249
 250 .. option:: --enable-vty-group <group>
 251
 252    Create Unix Vty sockets (for use with vtysh) with group ownership set to
 253    `group`. This allows one to create a separate group which is restricted to
 254    accessing only the vty sockets, hence allowing one to delegate this group to
 255    individual users, or to run vtysh setgid to this group.
 256
 257 The default user and group which will be configured is 'frr' if no user or
 258 group is specified. Note that this user or group requires write access to the
 259 local state directory (see :option:`--localstatedir`) and requires at least
 260 read access, and write access if you wish to allow daemons to write out their
 261 configuration, to the configuration directory (see :option:`--sysconfdir`).
 262
 263 On systems which have the 'libcap' capabilities manipulation library (currently
 264 only Linux), FRR will retain only minimal capabilities required and will only
 265 raise these capabilities for brief periods. On systems without libcap, FRR will
 266 run as the user specified and only raise its UID to 0 for brief periods.
 267
 268 Linux Notes
 269 """""""""""
 270
 271 .. index:: Building on Linux boxes
 272 .. index:: Linux configurations
 273
 274 There are several options available only to GNU/Linux systems.  If you use
 275 GNU/Linux, make sure that the current kernel configuration is what you want.
 276 FRR will run with any kernel configuration but some recommendations do exist.
 277
 278 :makevar:`CONFIG_NETLINK`
 279    Kernel/User Netlink socket. This is a enables an advanced interface between
 280    the Linux kernel and *zebra* (:ref:`kernel-interface`).
 281
 282 :makevar:`CONFIG_RTNETLINK`
 283    This makes it possible to receive Netlink routing messages.  If you specify
 284    this option, *zebra* can detect routing information updates directly from
 285    the kernel (:ref:`kernel-interface`).
 286
 287 :makevar:`CONFIG_IP_MULTICAST`
 288    This option enables IP multicast and should be specified when you use *ripd*
 289    (:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
 290    multicast.
 291
 292 Linux sysctl settings and kernel modules
 293 ````````````````````````````````````````
 294
 295 There are several kernel parameters that impact overall operation of FRR when
 296 using Linux as a router. Generally these parameters should be set in a
 297 sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on
 298 Ubuntu based systems and a new file
 299 :file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems.
 300 Additional kernel modules are also needed to support MPLS forwarding.
 301
 302 :makevar:`IPv4 and IPv6 forwarding`
 303    The following are set to enable IP forwarding in the kernel:
 304
 305    .. code-block:: shell
 306
 307       net.ipv4.conf.all.forwarding=1
 308       net.ipv6.conf.all.forwarding=1
 309
 310 :makevar:`MPLS forwarding`
 311    Basic MPLS kernel support was introduced 4.1, additional capability
 312    was introduced in 4.3 and 4.5. For some general information on Linux
 313    MPLS support see
 314    https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf.
 315    The following modules should be loaded to support MPLS forwarding,
 316    and are generally added to a configuration file such as
 317    :file:`/etc/modules-load.d/modules.conf`:
 318
 319    .. code-block:: shell
 320
 321       # Load MPLS Kernel Modules
 322       mpls_router
 323       mpls_iptunnel
 324
 325    The following is an example to enable MPLS forwarding in the kernel:
 326
 327    .. code-block:: shell
 328
 329       # Enable MPLS Label processing on all interfaces
 330       net.mpls.conf.eth0.input=1
 331       net.mpls.conf.eth1.input=1
 332       net.mpls.conf.eth2.input=1
 333       net.mpls.platform_labels=100000
 334
 335    Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for
 336    each interface *'<if>'* used with MPLS and to set labels to an
 337    appropriate value.
 338
 339 :makevar:`VRF forwarding`
 340    General information on Linux VRF support can be found in
 341    https://www.kernel.org/doc/Documentation/networking/vrf.txt. Kernel
 342    support for VRFs was introduced in 4.3 and improved upon through
 343    4.13, which is the version most used in FRR testing (as of June
 344    2018).  Additional background on using Linux VRFs and kernel specific
 345    features can be found in
 346    http://schd.ws/hosted_files/ossna2017/fe/vrf-tutorial-oss.pdf.
 347
 348    The following impacts how BGP TCP sockets are managed across VRFs:
 349
 350    .. code-block:: shell
 351
 352       net.ipv4.tcp_l3mdev_accept=0
 353
 354    With this setting a BGP TCP socket is opened per VRF.  This setting
 355    ensures that other TCP services, such as SSH, provided for non-VRF
 356    purposes are blocked from VRF associated Linux interfaces.
 357
 358    .. code-block:: shell
 359
 360       net.ipv4.tcp_l3mdev_accept=1
 361
 362    With this setting a single BGP TCP socket is shared across the
 363    system.  This setting exposes any TCP service running on the system,
 364    e.g., SSH, to all VRFs.  Generally this setting is not used in
 365    environments where VRFs are used to support multiple administrative
 366    groups.
 367
 368    **Important note** as of June 2018, Kernel versions 4.14-4.18 have a
 369    known bug where VRF-specific TCP sockets are not properly handled. When
 370    running these kernel versions, if unable to establish any VRF BGP
 371    adjacencies, either downgrade to 4.13 or set
 372    'net.ipv4.tcp_l3mdev_accept=1'. The fix for this issue is planned to be
 373    included in future kernel versions so upgrading your kernel may also
 374    address this issue.
 375
 376
 377 Building
 378 ^^^^^^^^
 379
 380 Once you have chosen your configure options, run the configure script and pass
 381 the options you chose:
 382
 383 .. code-block:: shell
 384
 385    ./configure \
 386        --prefix=/usr \
 387        --enable-exampledir=/usr/share/doc/frr/examples/ \
 388        --localstatedir=/var/run/frr \
 389        --sbindir=/usr/lib/frr \
 390        --sysconfdir=/etc/frr \
 391        --enable-pimd \
 392        --enable-watchfrr \
 393        ...
 394
 395 After configuring the software, you are ready to build and install it for your
 396 system.
 397
 398 .. code-block:: shell
 399
 400    make && sudo make install
 401
 402 If everything finishes successfully, FRR should be installed. You should now
 403 skip to the section on :ref:`basic-setup`.