doc/install.texi

   1 @node  Installation
   2 @chapter Installation
   3
   4 @cindex How to install Quagga
   5 @cindex Installation
   6 @cindex Installing Quagga
   7 @cindex Building the system
   8 @cindex Making Quagga
   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 Quagga 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 Quagga has an excellent configure script which automatically detects most
  47 host configurations.  There are several additional configure options you can
  48 use to turn off IPv6 support, to disable the compilation of specific
  49 daemons, and to enable SNMP support.
  50
  51 @table @option
  52 @item --disable-ipv6
  53 Turn off IPv6 related features and daemons.  Quagga configure script
  54 automatically detects IPv6 stack.  But sometimes you might want to
  55 disable IPv6 support of Quagga.
  56 @item --disable-zebra
  57 Do not build zebra daemon.
  58 @item --disable-ripd
  59 Do not build ripd.
  60 @item --disable-ripngd
  61 Do not build ripngd.
  62 @item --disable-ospfd
  63 Do not build ospfd.
  64 @item --disable-ospf6d
  65 Do not build ospf6d.
  66 @item --disable-bgpd
  67 Do not build bgpd.
  68 @item --disable-bgp-announce
  69 Make @command{bgpd} which does not make bgp announcements at all.  This
  70 feature is good for using @command{bgpd} as a BGP announcement listener.
  71 @item --enable-netlink
  72 Force to enable @sc{gnu}/Linux netlink interface.  Quagga configure
  73 script detects netlink interface by checking a header file.  When the header
  74 file does not match to the current running kernel, configure script will
  75 not turn on netlink support.
  76 @item --enable-snmp
  77 Enable SNMP support.  By default, SNMP support is disabled.
  78 @item --disable-opaque-lsa
  79 Disable support for Opaque LSAs (RFC2370) in ospfd.
  80 @item --disable-ospfapi
  81 Disable support for OSPF-API, an API to interface directly with ospfd.
  82 OSPF-API is enabled if --enable-opaque-lsa is set.
  83 @item --disable-ospfclient
  84 Disable building of the example OSPF-API client.
  85 @item --disable-ospf-te
  86 Disable support for OSPF Traffic Engineering Extension (RFC3630) this
  87 requires support for Opaque LSAs.
  88 @item --disable-ospf-ri
  89 Disable support for OSPF Router Information (RFC4970 & RFC5088) this
  90 requires support for Opaque LSAs and Traffic Engineering.
  91 @item --enable-isisd
  92 Build isisd.
  93 @item --enable-isis-topology
  94 Enable IS-IS topology generator.
  95 @item --enable-isis-te
  96 Enable Traffic Engineering Extension for ISIS (RFC5305)
  97 @item --enable-multipath=@var{ARG}
  98 Enable support for Equal Cost Multipath. @var{ARG} is the maximum number
  99 of ECMP paths to allow, set to 0 to allow unlimited number of paths.
 100 @item --disable-rtadv
 101 Disable support IPV6 router advertisement in zebra.
 102 @item --enable-gcc-rdynamic
 103 Pass the @command{-rdynamic} option to the linker driver.  This is in most
 104 cases neccessary for getting usable backtraces.  This option defaults to on
 105 if the compiler is detected as gcc, but giving an explicit enable/disable is
 106 suggested.
 107 @item --enable-backtrace
 108 Controls backtrace support for the crash handlers. This is autodetected by
 109 default. Using the switch will enforce the requested behaviour, failing with
 110 an error if support is requested but not available.  On BSD systems, this
 111 needs libexecinfo, while on glibc support for this is part of libc itself.
 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-ipv6
 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 Quagga Least-Privileges
 141 @cindex Quagga 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 Quagga 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 'quagga' 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 quagga system will retain only minimal
 171 capabilities required, further it will only raise these capabilities for
 172 brief periods. On systems without libcap, quagga 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 Quagga
 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.  Quagga 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 Quagga 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. If you have *any* problems
 237 at this stage, be certain to send a bug report @xref{Bug Reports}.
 238
 239 @example
 240 % ./configure
 241 .
 242 .
 243 .
 244 ./configure output
 245 .
 246 .
 247 .
 248 % make
 249 @end example
 250 @c A - End of node, Building the Software
 251
 252
 253 @node Install the Software
 254 @comment  node-name,  next,  previous,  up
 255 @section Install the Software
 256
 257 Installing the software to your system consists of copying the compiled
 258 programs and supporting files to a standard location. After the
 259 installation process has completed, these files have been copied
 260 from your work directory to @file{/usr/local/bin}, and @file{/usr/local/etc}.
 261
 262 To install the Quagga suite, issue the following command at your shell
 263 prompt: @command{make install}.
 264
 265 @example
 266 %
 267 % make install
 268 %
 269 @end example
 270
 271 Quagga daemons have their own terminal interface or VTY.  After
 272 installation, you have to setup each beast's port number to connect to
 273 them.  Please add the following entries to @file{/etc/services}.
 274
 275 @example
 276 zebrasrv      2600/tcp            # zebra service
 277 zebra         2601/tcp            # zebra vty
 278 ripd          2602/tcp            # RIPd vty
 279 ripngd        2603/tcp            # RIPngd vty
 280 ospfd         2604/tcp            # OSPFd vty
 281 bgpd          2605/tcp            # BGPd vty
 282 ospf6d        2606/tcp            # OSPF6d vty
 283 ospfapi       2607/tcp            # ospfapi
 284 isisd         2608/tcp            # ISISd vty
 285 pimd          2611/tcp            # PIMd vty
 286 nhrpd         2612/tcp            # nhrpd vty
 287 @end example
 288
 289 If you use a FreeBSD newer than 2.2.8, the above entries are already
 290 added to @file{/etc/services} so there is no need to add it. If you
 291 specify a port number when starting the daemon, these entries may not be
 292 needed.
 293
 294 You may need to make changes to the config files in
 295 @file{@value{INSTALL_PREFIX_ETC}/*.conf}. @xref{Config Commands}.