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 --enable-opaque-lsa
  83 Enable 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 --enable-ospf-te
  90 Enable 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 --enable-rtadv
  96 Enable support IPV6 router advertisement in zebra.
  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-ipv6
 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 Quagga Least-Privileges
 126 @cindex Quagga 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 Quagga 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 'quagga' 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 quagga system will retain only minimal
 156 capabilities required, further it will only raise these capabilities for
 157 brief periods. On systems without libcap, quagga 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 Quagga
 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.  Quagga 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 Quagga 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. If you have *any* problems
 222 at this stage, be certain to send a bug report @xref{Bug Reports}.
 223
 224 @example
 225 % ./configure
 226 .
 227 .
 228 .
 229 ./configure output
 230 .
 231 .
 232 .
 233 % make
 234 @end example
 235 @c A - End of node, Building the Software
 236
 237
 238 @node Install the Software
 239 @comment  node-name,  next,  previous,  up
 240 @section Install the Software
 241
 242 Installing the software to your system consists of copying the compiled
 243 programs and supporting files to a standard location. After the
 244 installation process has completed, these files have been copied
 245 from your work directory to @file{/usr/local/bin}, and @file{/usr/local/etc}.
 246
 247 To install the Quagga suite, issue the following command at your shell
 248 prompt: @command{make install}.
 249
 250 @example
 251 %
 252 % make install
 253 %
 254 @end example
 255
 256 Quagga daemons have their own terminal interface or VTY.  After
 257 installation, you have to setup each beast's port number to connect to
 258 them.  Please add the following entries to @file{/etc/services}.
 259
 260 @example
 261 zebrasrv      2600/tcp            # zebra service
 262 zebra         2601/tcp            # zebra vty
 263 ripd          2602/tcp            # RIPd vty
 264 ripngd        2603/tcp            # RIPngd vty
 265 ospfd         2604/tcp            # OSPFd vty
 266 bgpd          2605/tcp            # BGPd vty
 267 ospf6d        2606/tcp            # OSPF6d vty
 268 ospfapi       2607/tcp            # ospfapi
 269 isisd         2608/tcp            # ISISd vty
 270 @end example
 271
 272 If you use a FreeBSD newer than 2.2.8, the above entries are already
 273 added to @file{/etc/services} so there is no need to add it. If you
 274 specify a port number when starting the daemon, these entries may not be
 275 needed.
 276
 277 You may need to make changes to the config files in
 278 @file{@value{INSTALL_PREFIX_ETC}/*.conf}. @xref{Config Commands}.