]>
Commit | Line | Data |
---|---|---|
0efdf0fe | 1 | .. _installation: |
42fc5d26 | 2 | |
42fc5d26 | 3 | Installation |
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 | 12 | This section covers the basics of building, installing and setting up FRR. |
44f2550e | 13 | |
717b4866 QY |
14 | From Packages |
15 | ------------- | |
44f2550e | 16 | |
717b4866 QY |
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. | |
42fc5d26 | 22 | |
717b4866 QY |
23 | From Snapcraft |
24 | -------------- | |
42fc5d26 | 25 | |
717b4866 QY |
26 | In addition to traditional packages the project also builds and publishes |
27 | universal Snap images, available at https://snapcraft.io/frr. | |
44f2550e | 28 | |
717b4866 QY |
29 | From Source |
30 | ----------- | |
42fc5d26 | 31 | |
717b4866 QY |
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. | |
42fc5d26 | 36 | |
717b4866 QY |
37 | Getting the Source |
38 | ^^^^^^^^^^^^^^^^^^ | |
42fc5d26 | 39 | |
717b4866 QY |
40 | FRR'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 |
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. | |
42fc5d26 | 51 | |
717b4866 QY |
52 | In addition, release tarballs are published on the GitHub releases page |
53 | `here <https://github.com/FRRouting/frr/releases>`_. | |
42fc5d26 | 54 | |
717b4866 QY |
55 | Configuration |
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 |
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: | |
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 | 225 | You may specify any combination of the above options to the configure |
dc5564c7 | 226 | script. By default, the executables are placed in :file:`/usr/local/sbin` |
42fc5d26 | 227 | and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/` |
44f2550e | 228 | installation prefix and other directories may be changed using the following |
42fc5d26 QY |
229 | options 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 | 247 | Least-Privilege Support |
717b4866 | 248 | """"""""""""""""""""""" |
42fc5d26 QY |
249 | |
250 | .. index:: FRR Least-Privileges | |
42fc5d26 QY |
251 | .. index:: FRR Privileges |
252 | ||
253 | Additionally, you may configure zebra to drop its elevated privileges | |
254 | shortly after startup and switch to another user. The configure script will | |
255 | automatically try to configure this support. There are three configure | |
256 | options 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 |
274 | The default user and group which will be configured is 'frr' if no user or |
275 | group is specified. Note that this user or group requires write access to the | |
276 | local state directory (see :option:`--localstatedir`) and requires at least | |
277 | read access, and write access if you wish to allow daemons to write out their | |
278 | configuration, to the configuration directory (see :option:`--sysconfdir`). | |
42fc5d26 | 279 | |
dc5564c7 QY |
280 | On systems which have the 'libcap' capabilities manipulation library (currently |
281 | only Linux), FRR will retain only minimal capabilities required and will only | |
282 | raise these capabilities for brief periods. On systems without libcap, FRR will | |
283 | run as the user specified and only raise its UID to 0 for brief periods. | |
42fc5d26 | 284 | |
42fc5d26 | 285 | Linux Notes |
717b4866 | 286 | """"""""""" |
42fc5d26 QY |
287 | |
288 | .. index:: Building on Linux boxes | |
42fc5d26 QY |
289 | .. index:: Linux configurations |
290 | ||
717b4866 QY |
291 | There are several options available only to GNU/Linux systems. If you use |
292 | GNU/Linux, make sure that the current kernel configuration is what you want. | |
293 | FRR 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 |
309 | Linux sysctl settings and kernel modules |
310 | ```````````````````````````````````````` | |
311 | ||
312 | There are several kernel parameters that impact overall operation of FRR when | |
313 | using Linux as a router. Generally these parameters should be set in a | |
314 | sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on | |
315 | Ubuntu based systems and a new file | |
316 | :file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems. | |
317 | Additional 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 |
394 | Building |
395 | ^^^^^^^^ | |
42fc5d26 | 396 | |
717b4866 QY |
397 | Once you have chosen your configure options, run the configure script and pass |
398 | the 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 |
412 | After configuring the software, you are ready to build and install it for your |
413 | system. | |
42fc5d26 | 414 | |
717b4866 | 415 | .. code-block:: shell |
42fc5d26 | 416 | |
717b4866 | 417 | make && sudo make install |
42fc5d26 | 418 | |
717b4866 QY |
419 | If everything finishes successfully, FRR should be installed. You should now |
420 | skip to the section on :ref:`basic-setup`. |