]>
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 | |
dc5564c7 | 106 | .. option:: --disable-bgp-announce |
42fc5d26 | 107 | |
dc5564c7 QY |
108 | Make *bgpd* which does not make bgp announcements at all. This |
109 | feature is good for using *bgpd* as a BGP announcement listener. | |
42fc5d26 | 110 | |
dc5564c7 | 111 | .. option:: --enable-datacenter |
42fc5d26 | 112 | |
dc5564c7 QY |
113 | Enable system defaults to work as if in a Data Center. See defaults.h |
114 | for what is changed by this configure option. | |
42fc5d26 | 115 | |
dc5564c7 | 116 | .. option:: --enable-snmp |
42fc5d26 | 117 | |
dc5564c7 | 118 | Enable SNMP support. By default, SNMP support is disabled. |
42fc5d26 | 119 | |
dc5564c7 | 120 | .. option:: --disable-ospfapi |
42fc5d26 | 121 | |
dc5564c7 QY |
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 | ||
a5a48dbf QY |
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 | ||
dc5564c7 QY |
152 | .. option:: --disable-rtadv |
153 | ||
154 | Disable support IPV6 router advertisement in zebra. | |
155 | ||
156 | .. option:: --enable-gcc-rdynamic | |
157 | ||
d1a242fd | 158 | Pass the ``-rdynamic`` option to the linker driver. This is in most cases |
d1e7591e | 159 | necessary for getting usable backtraces. This option defaults to on if the |
d1a242fd | 160 | compiler is detected as gcc, but giving an explicit enable/disable is |
dc5564c7 QY |
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. | |
42fc5d26 | 185 | |
c1a54c05 QY |
186 | .. option:: --disable-vtysh |
187 | ||
188 | Build without VTYSH. | |
42fc5d26 | 189 | |
013f9762 QY |
190 | .. option:: --enable-fpm |
191 | ||
192 | Build with FPM module support. | |
193 | ||
1f35b46a QY |
194 | .. option:: --enable-numeric-version |
195 | ||
196 | Alpine Linux does not allow non-numeric characters in the version string. | |
d1e7591e | 197 | With this option, we provide a way to strip out these characters for APK dev |
1f35b46a QY |
198 | package builds. |
199 | ||
0d8df934 DS |
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 | ||
83284209 AJ |
208 | .. option:: --enable-gcov |
209 | ||
210 | Code coverage reports from gcov require adjustments to the C and LD flags. | |
211 | With this option, gcov instrumentation is added to the build and coverage | |
212 | reports are created during execution. The check-coverage make target is | |
213 | also created to ease report uploading to codecov.io. The upload requires | |
214 | the COMMIT (git hash) and TOKEN (codecov upload token) environment variables | |
215 | be set. | |
216 | ||
42fc5d26 | 217 | You may specify any combination of the above options to the configure |
dc5564c7 | 218 | script. By default, the executables are placed in :file:`/usr/local/sbin` |
42fc5d26 | 219 | and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/` |
44f2550e | 220 | installation prefix and other directories may be changed using the following |
42fc5d26 QY |
221 | options to the configuration script. |
222 | ||
d1a242fd | 223 | .. option:: --prefix <prefix> |
42fc5d26 | 224 | |
dc5564c7 | 225 | Install architecture-independent files in `prefix` [/usr/local]. |
42fc5d26 | 226 | |
d1a242fd | 227 | .. option:: --sysconfdir <dir> |
42fc5d26 | 228 | |
dc5564c7 QY |
229 | Look for configuration files in `dir` [`prefix`/etc]. Note that sample |
230 | configuration files will be installed here. | |
44f2550e | 231 | |
d1a242fd | 232 | .. option:: --localstatedir <dir> |
42fc5d26 | 233 | |
d1a242fd QY |
234 | Configure zebra to use `dir` for local state files, such as pid files and |
235 | unix sockets. | |
42fc5d26 | 236 | |
11ab5329 | 237 | .. _least-privilege-support: |
42fc5d26 | 238 | |
d1a242fd | 239 | Least-Privilege Support |
717b4866 | 240 | """"""""""""""""""""""" |
42fc5d26 QY |
241 | |
242 | .. index:: FRR Least-Privileges | |
42fc5d26 QY |
243 | .. index:: FRR Privileges |
244 | ||
245 | Additionally, you may configure zebra to drop its elevated privileges | |
246 | shortly after startup and switch to another user. The configure script will | |
247 | automatically try to configure this support. There are three configure | |
248 | options to control the behaviour of FRR daemons. | |
249 | ||
d1a242fd | 250 | .. option:: --enable-user <user> |
42fc5d26 | 251 | |
d1a242fd QY |
252 | Switch to user `user shortly after startup, and run as user `user` in normal |
253 | operation. | |
42fc5d26 | 254 | |
d1a242fd | 255 | .. option:: --enable-group <user> |
42fc5d26 | 256 | |
d1a242fd | 257 | Switch real and effective group to `group` shortly after startup. |
42fc5d26 | 258 | |
d1a242fd | 259 | .. option:: --enable-vty-group <group> |
dc5564c7 | 260 | |
d1e7591e QY |
261 | Create Unix Vty sockets (for use with vtysh) with group ownership set to |
262 | `group`. This allows one to create a separate group which is restricted to | |
d1a242fd QY |
263 | accessing only the vty sockets, hence allowing one to delegate this group to |
264 | individual users, or to run vtysh setgid to this group. | |
42fc5d26 | 265 | |
07a17e6d QY |
266 | The default user and group which will be configured is 'frr' if no user or |
267 | group is specified. Note that this user or group requires write access to the | |
268 | local state directory (see :option:`--localstatedir`) and requires at least | |
269 | read access, and write access if you wish to allow daemons to write out their | |
270 | configuration, to the configuration directory (see :option:`--sysconfdir`). | |
42fc5d26 | 271 | |
dc5564c7 QY |
272 | On systems which have the 'libcap' capabilities manipulation library (currently |
273 | only Linux), FRR will retain only minimal capabilities required and will only | |
274 | raise these capabilities for brief periods. On systems without libcap, FRR will | |
275 | run as the user specified and only raise its UID to 0 for brief periods. | |
42fc5d26 | 276 | |
42fc5d26 | 277 | Linux Notes |
717b4866 | 278 | """"""""""" |
42fc5d26 QY |
279 | |
280 | .. index:: Building on Linux boxes | |
42fc5d26 QY |
281 | .. index:: Linux configurations |
282 | ||
717b4866 QY |
283 | There are several options available only to GNU/Linux systems. If you use |
284 | GNU/Linux, make sure that the current kernel configuration is what you want. | |
285 | FRR will run with any kernel configuration but some recommendations do exist. | |
42fc5d26 | 286 | |
717b4866 QY |
287 | :makevar:`CONFIG_NETLINK` |
288 | Kernel/User Netlink socket. This is a enables an advanced interface between | |
289 | the Linux kernel and *zebra* (:ref:`kernel-interface`). | |
42fc5d26 | 290 | |
717b4866 QY |
291 | :makevar:`CONFIG_RTNETLINK` |
292 | This makes it possible to receive Netlink routing messages. If you specify | |
293 | this option, *zebra* can detect routing information updates directly from | |
294 | the kernel (:ref:`kernel-interface`). | |
44f2550e | 295 | |
717b4866 QY |
296 | :makevar:`CONFIG_IP_MULTICAST` |
297 | This option enables IP multicast and should be specified when you use *ripd* | |
298 | (:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use | |
299 | multicast. | |
42fc5d26 | 300 | |
3c29c38d LB |
301 | Linux sysctl settings and kernel modules |
302 | ```````````````````````````````````````` | |
303 | ||
304 | There are several kernel parameters that impact overall operation of FRR when | |
305 | using Linux as a router. Generally these parameters should be set in a | |
306 | sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on | |
307 | Ubuntu based systems and a new file | |
308 | :file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems. | |
309 | Additional kernel modules are also needed to support MPLS forwarding. | |
310 | ||
311 | :makevar:`IPv4 and IPv6 forwarding` | |
312 | The following are set to enable IP forwarding in the kernel: | |
313 | ||
314 | .. code-block:: shell | |
315 | ||
316 | net.ipv4.conf.all.forwarding=1 | |
317 | net.ipv6.conf.all.forwarding=1 | |
318 | ||
319 | :makevar:`MPLS forwarding` | |
320 | Basic MPLS kernel support was introduced 4.1, additional capability | |
321 | was introduced in 4.3 and 4.5. For some general information on Linux | |
322 | MPLS support see | |
323 | https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf. | |
324 | The following modules should be loaded to support MPLS forwarding, | |
325 | and are generally added to a configuration file such as | |
326 | :file:`/etc/modules-load.d/modules.conf`: | |
327 | ||
328 | .. code-block:: shell | |
329 | ||
330 | # Load MPLS Kernel Modules | |
331 | mpls_router | |
332 | mpls_iptunnel | |
333 | ||
334 | The following is an example to enable MPLS forwarding in the kernel: | |
335 | ||
336 | .. code-block:: shell | |
337 | ||
338 | # Enable MPLS Label processing on all interfaces | |
339 | net.mpls.conf.eth0.input=1 | |
340 | net.mpls.conf.eth1.input=1 | |
341 | net.mpls.conf.eth2.input=1 | |
342 | net.mpls.platform_labels=100000 | |
343 | ||
344 | Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for | |
345 | each interface *'<if>'* used with MPLS and to set labels to an | |
346 | appropriate value. | |
347 | ||
348 | :makevar:`VRF forwarding` | |
349 | General information on Linux VRF support can be found in | |
350 | https://www.kernel.org/doc/Documentation/networking/vrf.txt. Kernel | |
351 | support for VRFs was introduced in 4.3 and improved upon through | |
352 | 4.13, which is the version most used in FRR testing (as of June | |
353 | 2018). Additional background on using Linux VRFs and kernel specific | |
354 | features can be found in | |
355 | http://schd.ws/hosted_files/ossna2017/fe/vrf-tutorial-oss.pdf. | |
356 | ||
357 | The following impacts how BGP TCP sockets are managed across VRFs: | |
358 | ||
359 | .. code-block:: shell | |
360 | ||
361 | net.ipv4.tcp_l3mdev_accept=0 | |
362 | ||
363 | With this setting a BGP TCP socket is opened per VRF. This setting | |
364 | ensures that other TCP services, such as SSH, provided for non-VRF | |
365 | purposes are blocked from VRF associated Linux interfaces. | |
366 | ||
367 | .. code-block:: shell | |
368 | ||
369 | net.ipv4.tcp_l3mdev_accept=1 | |
370 | ||
371 | With this setting a single BGP TCP socket is shared across the | |
372 | system. This setting exposes any TCP service running on the system, | |
373 | e.g., SSH, to all VRFs. Generally this setting is not used in | |
374 | environments where VRFs are used to support multiple administrative | |
375 | groups. | |
376 | ||
377 | **Important note** as of June 2018, Kernel versions 4.14-4.18 have a | |
378 | known bug where VRF-specific TCP sockets are not properly handled. When | |
379 | running these kernel versions, if unable to establish any VRF BGP | |
380 | adjacencies, either downgrade to 4.13 or set | |
381 | 'net.ipv4.tcp_l3mdev_accept=1'. The fix for this issue is planned to be | |
382 | included in future kernel versions so upgrading your kernel may also | |
383 | address this issue. | |
384 | ||
385 | ||
717b4866 QY |
386 | Building |
387 | ^^^^^^^^ | |
42fc5d26 | 388 | |
717b4866 QY |
389 | Once you have chosen your configure options, run the configure script and pass |
390 | the options you chose: | |
42fc5d26 | 391 | |
717b4866 | 392 | .. code-block:: shell |
42fc5d26 | 393 | |
717b4866 QY |
394 | ./configure \ |
395 | --prefix=/usr \ | |
396 | --enable-exampledir=/usr/share/doc/frr/examples/ \ | |
397 | --localstatedir=/var/run/frr \ | |
398 | --sbindir=/usr/lib/frr \ | |
399 | --sysconfdir=/etc/frr \ | |
400 | --enable-pimd \ | |
401 | --enable-watchfrr \ | |
402 | ... | |
44f2550e | 403 | |
717b4866 QY |
404 | After configuring the software, you are ready to build and install it for your |
405 | system. | |
42fc5d26 | 406 | |
717b4866 | 407 | .. code-block:: shell |
42fc5d26 | 408 | |
717b4866 | 409 | make && sudo make install |
42fc5d26 | 410 | |
717b4866 QY |
411 | If everything finishes successfully, FRR should be installed. You should now |
412 | skip to the section on :ref:`basic-setup`. |