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