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