doc/install.texi

   1 @node  Installation
   2 @chapter Installation
   3
   4 @cindex How to install Frr
   5 @cindex Installation
   6 @cindex Installing Frr
   7 @cindex Building the system
   8 @cindex Making Frr
   9
  10 There are three steps for installing the software: configuration,
  11 compilation, and installation.
  12
  13 @menu
  14 * Configure the Software::
  15 * Build the Software::
  16 * Install the Software::
  17 @end menu
  18
  19 The easiest way to get Frr running is to issue the following
  20 commands:
  21
  22 @example
  23 % configure
  24 % make
  25 % make install
  26 @end example
  27
  28 @node Configure the Software
  29 @section Configure the Software
  30
  31 @menu
  32 * The Configure script and its options::
  33 * Least-Privilege support::
  34 * Linux notes::
  35 @end menu
  36
  37 @node The Configure script and its options
  38 @subsection The Configure script and its options
  39
  40 @cindex Configuration options
  41 @cindex Options for configuring
  42 @cindex Build options
  43 @cindex Distribution configuration
  44 @cindex Options to @code{./configure}
  45
  46 Frr has an excellent configure script which automatically detects most
  47 host configurations.  There are several additional configure options to
  48 customize the build to include or exclude specific features and dependencies.
  49
  50 @table @option
  51 @item --disable-zebra
  52 Do not build zebra daemon.
  53 @item --disable-ripd
  54 Do not build ripd.
  55 @item --disable-ripngd
  56 Do not build ripngd.
  57 @item --disable-ospfd
  58 Do not build ospfd.
  59 @item --disable-ospf6d
  60 Do not build ospf6d.
  61 @item --disable-bgpd
  62 Do not build bgpd.
  63 @item --disable-bgp-announce
  64 Make @command{bgpd} which does not make bgp announcements at all.  This
  65 feature is good for using @command{bgpd} as a BGP announcement listener.
  66 @item --enable-datacenter
  67 Enable system defaults to work as if in a Data Center. See defaults.h
  68 for what is changed by this configure option.
  69 @item --enable-snmp
  70 Enable SNMP support.  By default, SNMP support is disabled.
  71 @item --disable-ospfapi
  72 Disable support for OSPF-API, an API to interface directly with ospfd.
  73 OSPF-API is enabled if --enable-opaque-lsa is set.
  74 @item --disable-ospfclient
  75 Disable building of the example OSPF-API client.
  76 @item --disable-ospf-ri
  77 Disable support for OSPF Router Information (RFC4970 & RFC5088) this
  78 requires support for Opaque LSAs and Traffic Engineering.
  79 @item --disable-isisd
  80 Do not build isisd.
  81 @item --enable-isis-topology
  82 Enable IS-IS topology generator.
  83 @item --enable-isis-te
  84 Enable Traffic Engineering Extension for ISIS (RFC5305)
  85 @item --enable-multipath=@var{ARG}
  86 Enable support for Equal Cost Multipath. @var{ARG} is the maximum number
  87 of ECMP paths to allow, set to 0 to allow unlimited number of paths.
  88 @item --enable-realms
  89 Enable the support of linux Realms.  Convert tag values from 1-255
  90 into a realm value when inserting into the linux kernel.  Then
  91 routing policy can be assigned to the realm.  See the tc man page.
  92 @item --disable-rtadv
  93 Disable support IPV6 router advertisement in zebra.
  94 @item --enable-gcc-rdynamic
  95 Pass the @command{-rdynamic} option to the linker driver.  This is in most
  96 cases neccessary for getting usable backtraces.  This option defaults to on
  97 if the compiler is detected as gcc, but giving an explicit enable/disable is
  98 suggested.
  99 @item --disable-backtrace
 100 Controls backtrace support for the crash handlers. This is autodetected by
 101 default. Using the switch will enforce the requested behaviour, failing with
 102 an error if support is requested but not available.  On BSD systems, this
 103 needs libexecinfo, while on glibc support for this is part of libc itself.
 104 @item --enable-dev-build
 105 Turn on some options for compiling FRR within a development environment in
 106 mind.  Specifically turn on -g3 -O0 for compiling options and add inclusion
 107 of grammar sandbox.
 108 @item --enable-fuzzing
 109 Turn on some compile options to allow you to run fuzzing tools
 110 against the system.  This tools is intended as a developer
 111 only tool and should not be used for normal operations
 112 @end table
 113
 114 You may specify any combination of the above options to the configure
 115 script.  By default, the executables are placed in @file{/usr/local/sbin}
 116 and the configuration files in @file{/usr/local/etc}. The @file{/usr/local/}
 117 installation prefix and other directories may be changed using the following
 118 options to the configuration script.
 119
 120 @table @option
 121 @item --prefix=@var{prefix}
 122 Install architecture-independent files in @var{prefix} [/usr/local].
 123 @item --sysconfdir=@var{dir}
 124 Look for configuration files in @var{dir} [@var{prefix}/etc]. Note
 125 that sample configuration files will be installed here.
 126 @item --localstatedir=@var{dir}
 127 Configure zebra to use @var{dir} for local state files, such
 128 as pid files and unix sockets.
 129 @end table
 130
 131 @example
 132 % ./configure --disable-snmp
 133 @end example
 134
 135 This command will configure zebra and the routing daemons.
 136
 137 @node Least-Privilege support
 138 @subsection Least-Privilege support
 139
 140 @cindex Frr Least-Privileges
 141 @cindex Frr Privileges
 142
 143 Additionally, you may configure zebra to drop its elevated privileges
 144 shortly after startup and switch to another user. The configure script will
 145 automatically try to configure this support. There are three configure
 146 options to control the behaviour of Frr daemons.
 147
 148 @table @option
 149 @item --enable-user=@var{user}
 150 Switch to user @var{ARG} shortly after startup, and run as user @var{ARG}
 151 in normal operation.
 152 @item --enable-group=@var{group}
 153 Switch real and effective group to @var{group} shortly after
 154 startup.
 155 @item --enable-vty-group=@var{group}
 156 Create Unix Vty sockets (for use with vtysh) with group owndership set to
 157 @var{group}. This allows one to create a seperate group which is
 158 restricted to accessing only the Vty sockets, hence allowing one to
 159 delegate this group to individual users, or to run vtysh setgid to
 160 this group.
 161 @end table
 162
 163 The default user and group which will be configured is 'frr' if no user
 164 or group is specified. Note that this user or group requires write access to
 165 the local state directory (see --localstatedir) and requires at least read
 166 access, and write access if you wish to allow daemons to write out their
 167 configuration, to the configuration directory (see --sysconfdir).
 168
 169 On systems which have the 'libcap' capabilities manipulation library
 170 (currently only linux), the frr system will retain only minimal
 171 capabilities required, further it will only raise these capabilities for
 172 brief periods. On systems without libcap, frr will run as the user
 173 specified and only raise its uid back to uid 0 for brief periods.
 174
 175 @node Linux notes
 176 @subsection Linux Notes
 177
 178 @cindex Configuring Frr
 179 @cindex Building on Linux boxes
 180 @cindex Linux configurations
 181
 182 There are several options available only to @sc{gnu}/Linux systems:
 183 @footnote{@sc{gnu}/Linux has very flexible kernel configuration features}.  If
 184 you use @sc{gnu}/Linux, make sure that the current kernel configuration is
 185 what you want.  Frr will run with any kernel configuration but some
 186 recommendations do exist.
 187
 188 @table @var
 189
 190 @item CONFIG_NETLINK
 191 Kernel/User netlink socket. This is a brand new feature which enables an
 192 advanced interface between the Linux kernel and zebra (@pxref{Kernel Interface}).
 193
 194 @item CONFIG_RTNETLINK
 195 Routing messages.
 196 This makes it possible to receive netlink routing messages.  If you
 197 specify this option, @command{zebra} can detect routing information
 198 updates directly from the kernel (@pxref{Kernel Interface}).
 199
 200 @item CONFIG_IP_MULTICAST
 201 IP: multicasting.
 202 This option should be specified when you use @command{ripd} (@pxref{RIP}) or
 203 @command{ospfd} (@pxref{OSPFv2}) because these protocols use multicast.
 204
 205 @end table
 206
 207 IPv6 support has been added in @sc{gnu}/Linux kernel version 2.2.  If you
 208 try to use the Frr IPv6 feature on a @sc{gnu}/Linux kernel, please
 209 make sure the following libraries have been installed.  Please note that
 210 these libraries will not be needed when you uses @sc{gnu} C library 2.1
 211 or upper.
 212
 213 @table @code
 214
 215 @item inet6-apps
 216 The @code{inet6-apps} package includes basic IPv6 related libraries such
 217 as @code{inet_ntop} and @code{inet_pton}.  Some basic IPv6 programs such
 218 as @command{ping}, @command{ftp}, and @command{inetd} are also
 219 included. The @code{inet-apps} can be found at
 220 @uref{ftp://ftp.inner.net/pub/ipv6/}.
 221
 222 @item net-tools
 223 The @code{net-tools} package provides an IPv6 enabled interface and
 224 routing utility.  It contains @command{ifconfig}, @command{route},
 225 @command{netstat}, and other tools.  @code{net-tools} may be found at
 226 @uref{http://www.tazenda.demon.co.uk/phil/net-tools/}.
 227
 228 @end table
 229 @c A - end of footnote
 230
 231 @node Build the Software
 232 @section Build the Software
 233
 234 After configuring the software, you will need to compile it for your
 235 system. Simply issue the command @command{make} in the root of the source
 236 directory and the software will be compiled. Cliff Note versions of
 237 different compilation examples can be found in the doc/Building_FRR_on_XXX.md
 238 files.  If you have *any* problems at this stage, be certain to send a
 239 bug report @xref{Bug Reports}.
 240
 241 @example
 242 % ./bootstrap.sh
 243 % ./configure <appropriate to your system>
 244 % make
 245 @end example
 246 @c A - End of node, Building the Software
 247
 248
 249 @node Install the Software
 250 @comment  node-name,  next,  previous,  up
 251 @section Install the Software
 252
 253 Installing the software to your system consists of copying the compiled
 254 programs and supporting files to a standard location. After the
 255 installation process has completed, these files have been copied
 256 from your work directory to @file{/usr/local/bin}, and @file{/usr/local/etc}.
 257
 258 To install the Frr suite, issue the following command at your shell
 259 prompt: @command{make install}.
 260
 261 @example
 262 %
 263 % make install
 264 %
 265 @end example
 266
 267 Frr daemons have their own terminal interface or VTY.  After
 268 installation, you have to setup each beast's port number to connect to
 269 them.  Please add the following entries to @file{/etc/services}.
 270
 271 @example
 272 zebrasrv      2600/tcp            # zebra service
 273 zebra         2601/tcp            # zebra vty
 274 ripd          2602/tcp            # RIPd vty
 275 ripngd        2603/tcp            # RIPngd vty
 276 ospfd         2604/tcp            # OSPFd vty
 277 bgpd          2605/tcp            # BGPd vty
 278 ospf6d        2606/tcp            # OSPF6d vty
 279 ospfapi       2607/tcp            # ospfapi
 280 isisd         2608/tcp            # ISISd vty
 281 nhrpd         2610/tcp            # nhrpd vty
 282 pimd          2611/tcp            # PIMd vty
 283 @end example
 284
 285 If you use a FreeBSD newer than 2.2.8, the above entries are already
 286 added to @file{/etc/services} so there is no need to add it. If you
 287 specify a port number when starting the daemon, these entries may not be
 288 needed.
 289
 290 You may need to make changes to the config files in
 291 @file{@value{INSTALL_PREFIX_ETC}/*.conf}. @xref{Config Commands}.