doc/main.texi

   1 @node Zebra
   2 @chapter Zebra
   3
   4 @c SYNOPSIS
   5 @command{zebra} is an IP routing manager.  It provides kernel routing
   6 table updates, interface lookups, and redistribution of routes between
   7 different routing protocols.
   8
   9 @menu
  10 * Invoking zebra::              Running the program
  11 * Interface Commands::          Commands for zebra interfaces
  12 * Static Route Commands::       Commands for adding static routes
  13 * zebra Route Filtering::       Commands for zebra route filtering
  14 * zebra FIB push interface::    Interface to optional FPM component
  15 * zebra Terminal Mode Commands::  Commands for zebra's VTY
  16 @end menu
  17
  18
  19 @node Invoking zebra
  20 @section Invoking zebra
  21
  22 Besides the common invocation options (@pxref{Common Invocation Options}), the
  23 @command{zebra} specific invocation options are listed below.
  24
  25 @table @samp
  26 @item -b
  27 @itemx --batch
  28 Runs in batch mode.  @command{zebra} parses configuration file and terminates
  29 immediately.
  30
  31 @item -k
  32 @itemx --keep_kernel
  33 When zebra starts up, don't delete old self inserted routes.
  34
  35 @item -r
  36 @itemx --retain
  37 When program terminates, retain routes added by zebra.
  38
  39 @end table
  40
  41 @node Interface Commands
  42 @section Interface Commands
  43
  44 @deffn Command {interface @var{ifname}} {}
  45 @end deffn
  46
  47 @deffn {Interface Command} {shutdown} {}
  48 @deffnx {Interface Command} {no shutdown} {}
  49 Up or down the current interface.
  50 @end deffn
  51
  52 @deffn {Interface Command} {ip address @var{address/prefix}} {}
  53 @deffnx {Interface Command} {ipv6 address @var{address/prefix}} {}
  54 @deffnx {Interface Command} {no ip address @var{address/prefix}} {}
  55 @deffnx {Interface Command} {no ipv6 address @var{address/prefix}} {}
  56 Set the IPv4 or IPv6 address/prefix for the interface.
  57 @end deffn
  58
  59 @deffn {Interface Command} {ip address @var{address/prefix} secondary} {}
  60 @deffnx {Interface Command} {no ip address @var{address/prefix} secondary} {}
  61 Set the secondary flag for this address. This causes ospfd to not treat the
  62 address as a distinct subnet.
  63 @end deffn
  64
  65 @deffn {Interface Command} {description @var{description} ...} {}
  66 Set description for the interface.
  67 @end deffn
  68
  69 @deffn {Interface Command} {multicast} {}
  70 @deffnx {Interface Command} {no multicast} {}
  71 Enable or disables multicast flag for the interface.
  72 @end deffn
  73
  74 @deffn {Interface Command} {bandwidth <1-10000000>} {}
  75 @deffnx {Interface Command} {no bandwidth <1-10000000>} {}
  76 Set bandwidth value of the interface in kilobits/sec.  This is for
  77 calculating OSPF cost. This command does not affect the actual device
  78 configuration.
  79 @end deffn
  80
  81 @deffn {Interface Command} {link-detect} {}
  82 @deffnx {Interface Command} {no link-detect} {}
  83 Enable/disable link-detect on platforms which support this. Currently
  84 only Linux and Solaris, and only where network interface drivers support reporting
  85 link-state via the IFF_RUNNING flag.
  86 @end deffn
  87
  88 @node Static Route Commands
  89 @section Static Route Commands
  90
  91 Static routing is a very fundamental feature of routing technology.  It
  92 defines static prefix and gateway.
  93
  94 @deffn Command {ip route @var{network} @var{gateway}} {}
  95 @var{network} is destination prefix with format of A.B.C.D/M.
  96 @var{gateway} is gateway for the prefix.  When @var{gateway} is
  97 A.B.C.D format.  It is taken as a IPv4 address gateway.  Otherwise it
  98 is treated as an interface name. If the interface name is @var{null0} then
  99 zebra installs a blackhole route.
 100
 101 @example
 102 ip route 10.0.0.0/8 10.0.0.2
 103 ip route 10.0.0.0/8 ppp0
 104 ip route 10.0.0.0/8 null0
 105 @end example
 106
 107 First example defines 10.0.0.0/8 static route with gateway 10.0.0.2.
 108 Second one defines the same prefix but with gateway to interface ppp0. The
 109 third install a blackhole route.
 110 @end deffn
 111
 112 @deffn Command {ip route @var{network} @var{netmask} @var{gateway}} {}
 113 This is alternate version of above command.  When @var{network} is
 114 A.B.C.D format, user must define @var{netmask} value with A.B.C.D
 115 format.  @var{gateway} is same option as above command
 116
 117 @example
 118 ip route 10.0.0.0 255.255.255.0 10.0.0.2
 119 ip route 10.0.0.0 255.255.255.0 ppp0
 120 ip route 10.0.0.0 255.255.255.0 null0
 121 @end example
 122
 123 These statements are equivalent to those in the previous example.
 124 @end deffn
 125
 126 @deffn Command {ip route @var{network} @var{gateway} @var{distance}} {}
 127 Installs the route with the specified distance.
 128 @end deffn
 129
 130 Multiple nexthop static route
 131
 132 @example
 133 ip route 10.0.0.1/32 10.0.0.2
 134 ip route 10.0.0.1/32 10.0.0.3
 135 ip route 10.0.0.1/32 eth0
 136 @end example
 137
 138 If there is no route to 10.0.0.2 and 10.0.0.3, and interface eth0
 139 is reachable, then the last route is installed into the kernel.
 140
 141 If zebra has been compiled with multipath support, and both 10.0.0.2 and
 142 10.0.0.3 are reachable, zebra will install a multipath route via both
 143 nexthops, if the platform supports this.
 144
 145 @example
 146 zebra> show ip route
 147 S>  10.0.0.1/32 [1/0] via 10.0.0.2 inactive
 148                       via 10.0.0.3 inactive
 149   *                   is directly connected, eth0
 150 @end example
 151
 152 @example
 153 ip route 10.0.0.0/8 10.0.0.2
 154 ip route 10.0.0.0/8 10.0.0.3
 155 ip route 10.0.0.0/8 null0 255
 156 @end example
 157
 158 This will install a multihop route via the specified next-hops if they are
 159 reachable, as well as a high-metric blackhole route, which can be useful to
 160 prevent traffic destined for a prefix to match less-specific routes (eg
 161 default) should the specified gateways not be reachable. Eg:
 162
 163 @example
 164 zebra> show ip route 10.0.0.0/8
 165 Routing entry for 10.0.0.0/8
 166   Known via "static", distance 1, metric 0
 167     10.0.0.2 inactive
 168     10.0.0.3 inactive
 169
 170 Routing entry for 10.0.0.0/8
 171   Known via "static", distance 255, metric 0
 172     directly connected, Null0
 173 @end example
 174
 175 @deffn Command {ipv6 route @var{network} @var{gateway}} {}
 176 @deffnx Command {ipv6 route @var{network} @var{gateway} @var{distance}} {}
 177 These behave similarly to their ipv4 counterparts.
 178 @end deffn
 179
 180
 181 @deffn Command {table @var{tableno}} {}
 182 Select the primary kernel routing table to be used.  This only works
 183 for kernels supporting multiple routing tables (like GNU/Linux 2.2.x
 184 and later).  After setting @var{tableno} with this command,
 185 static routes defined after this are added to the specified table.
 186 @end deffn
 187
 188 @node zebra Route Filtering
 189 @section zebra Route Filtering
 190 Zebra supports @command{prefix-list} and @command{route-map} to match
 191 routes received from other quagga components.  The
 192 @command{permit}/@command{deny} facilities provided by these commands
 193 can be used to filter which routes zebra will install in the kernel.
 194
 195 @deffn Command {ip protocol @var{protocol} route-map @var{routemap}} {}
 196 Apply a route-map filter to routes for the specified protocol. @var{protocol}
 197 can be @b{any} or one of
 198 @b{system},
 199 @b{kernel},
 200 @b{connected},
 201 @b{static},
 202 @b{rip},
 203 @b{ripng},
 204 @b{ospf},
 205 @b{ospf6},
 206 @b{isis},
 207 @b{bgp},
 208 @b{hsls}.
 209 @end deffn
 210
 211 @deffn {Route Map} {set src @var{address}}
 212 Within a route-map, set the preferred source address for matching routes
 213 when installing in the kernel.
 214 @end deffn
 215
 216 @example
 217 The following creates a prefix-list that matches all addresses, a route-map
 218 that sets the preferred source address, and applies the route-map to all
 219 @command{rip} routes.
 220
 221 @group
 222 ip prefix-list ANY permit 0.0.0.0/0 le 32
 223 route-map RM1 permit 10
 224      match ip address prefix-list ANY
 225      set src 10.0.0.1
 226
 227 ip protocol rip route-map RM1
 228 @end group
 229 @end example
 230
 231 @node zebra FIB push interface
 232 @section zebra FIB push interface
 233
 234 Zebra supports a 'FIB push' interface that allows an external
 235 component to learn the forwarding information computed by the Quagga
 236 routing suite.
 237
 238 In Quagga, the Routing Information Base (RIB) resides inside
 239 zebra. Routing protocols communicate their best routes to zebra, and
 240 zebra computes the best route across protocols for each prefix. This
 241 latter information makes up the Forwarding Information Base
 242 (FIB). Zebra feeds the FIB to the kernel, which allows the IP stack in
 243 the kernel to forward packets according to the routes computed by
 244 Quagga. The kernel FIB is updated in an OS-specific way. For example,
 245 the @code{netlink} interface is used on Linux, and route sockets are
 246 used on FreeBSD.
 247
 248 The FIB push interface aims to provide a cross-platform mechanism to
 249 support scenarios where the router has a forwarding path that is
 250 distinct from the kernel, commonly a hardware-based fast path. In
 251 these cases, the FIB needs to be maintained reliably in the fast path
 252 as well. We refer to the component that programs the forwarding plane
 253 (directly or indirectly) as the Forwarding Plane Manager or FPM.
 254
 255 The FIB push interface comprises of a TCP connection between zebra and
 256 the FPM. The connection is initiated by zebra -- that is, the FPM acts
 257 as the TCP server.
 258
 259 The relevant zebra code kicks in when zebra is configured with the
 260 @code{--enable-fpm} flag. Zebra periodically attempts to connect to
 261 the well-known FPM port. Once the connection is up, zebra starts
 262 sending messages containing routes over the socket to the FPM. Zebra
 263 sends a complete copy of the forwarding table to the FPM, including
 264 routes that it may have picked up from the kernel. The existing
 265 interaction of zebra with the kernel remains unchanged -- that is, the
 266 kernel continues to receive FIB updates as before.
 267
 268 The format of the messages exchanged with the FPM is defined by the
 269 file @file{fpm/fpm.h} in the quagga tree.
 270
 271 The zebra FPM interface uses replace semantics. That is, if a 'route
 272 add' message for a prefix is followed by another 'route add' message,
 273 the information in the second message is complete by itself, and
 274 replaces the information sent in the first message.
 275
 276 If the connection to the FPM goes down for some reason, zebra sends
 277 the FPM a complete copy of the forwarding table(s) when it reconnects.
 278
 279 @node zebra Terminal Mode Commands
 280 @section zebra Terminal Mode Commands
 281
 282 @deffn Command {show ip route} {}
 283 Display current routes which zebra holds in its database.
 284
 285 @example
 286 @group
 287 Router# show ip route
 288 Codes: K - kernel route, C - connected, S - static, R - RIP,
 289        B - BGP * - FIB route.
 290
 291 K* 0.0.0.0/0              203.181.89.241
 292 S  0.0.0.0/0              203.181.89.1
 293 C* 127.0.0.0/8            lo
 294 C* 203.181.89.240/28      eth0
 295 @end group
 296 @end example
 297 @end deffn
 298
 299 @deffn Command {show ipv6 route} {}
 300 @end deffn
 301
 302 @deffn Command {show interface} {}
 303 @end deffn
 304
 305 @deffn Command {show ip prefix-list [@var{name}]} {}
 306 @end deffn
 307
 308 @deffn Command {show route-map [@var{name}]} {}
 309 @end deffn
 310
 311 @deffn Command {show ip protocol} {}
 312 @end deffn
 313
 314 @deffn Command {show ipforward} {}
 315 Display whether the host's IP forwarding function is enabled or not.
 316 Almost any UNIX kernel can be configured with IP forwarding disabled.
 317 If so, the box can't work as a router.
 318 @end deffn
 319
 320 @deffn Command {show ipv6forward} {}
 321 Display whether the host's IP v6 forwarding is enabled or not.
 322 @end deffn
 323
 324 @deffn Command {show zebra fpm stats} {}
 325 Display statistics related to the zebra code that interacts with the
 326 optional Forwarding Plane Manager (FPM) component.
 327 @end deffn
 328
 329 @deffn Command {clear zebra fpm stats} {}
 330 Reset statistics related to the zebra code that interacts with the
 331 optional Forwarding Plane Manager (FPM) component.
 332 @end deffn