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