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 * Multicast RIB Commands::      Commands for controlling MRIB behavior
  14 * zebra Route Filtering::       Commands for zebra route filtering
  15 * zebra FIB push interface::    Interface to optional FPM component
  16 * zebra Terminal Mode Commands::  Commands for zebra's VTY
  17 @end menu
  18
  19
  20 @node Invoking zebra
  21 @section Invoking zebra
  22
  23 Besides the common invocation options (@pxref{Common Invocation Options}), the
  24 @command{zebra} specific invocation options are listed below.
  25
  26 @table @samp
  27 @item -b
  28 @itemx --batch
  29 Runs in batch mode.  @command{zebra} parses configuration file and terminates
  30 immediately.
  31
  32 @item -k
  33 @itemx --keep_kernel
  34 When zebra starts up, don't delete old self inserted routes.
  35
  36 @item -r
  37 @itemx --retain
  38 When program terminates, retain routes added by zebra.
  39
  40 @end table
  41
  42 @node Interface Commands
  43 @section Interface Commands
  44
  45 @menu
  46 * Standard Commands::
  47 * Link Parameters Commands::
  48 @end menu
  49
  50 @node Standard Commands
  51 @subsection Standard Commands
  52
  53 @deffn Command {interface @var{ifname}} {}
  54 @end deffn
  55
  56 @deffn {Interface Command} {shutdown} {}
  57 @deffnx {Interface Command} {no shutdown} {}
  58 Up or down the current interface.
  59 @end deffn
  60
  61 @deffn {Interface Command} {ip address @var{address/prefix}} {}
  62 @deffnx {Interface Command} {ipv6 address @var{address/prefix}} {}
  63 @deffnx {Interface Command} {no ip address @var{address/prefix}} {}
  64 @deffnx {Interface Command} {no ipv6 address @var{address/prefix}} {}
  65 Set the IPv4 or IPv6 address/prefix for the interface.
  66 @end deffn
  67
  68 @deffn {Interface Command} {ip address @var{address/prefix} secondary} {}
  69 @deffnx {Interface Command} {no ip address @var{address/prefix} secondary} {}
  70 Set the secondary flag for this address. This causes ospfd to not treat the
  71 address as a distinct subnet.
  72 @end deffn
  73
  74 @deffn {Interface Command} {description @var{description} ...} {}
  75 Set description for the interface.
  76 @end deffn
  77
  78 @deffn {Interface Command} {multicast} {}
  79 @deffnx {Interface Command} {no multicast} {}
  80 Enable or disables multicast flag for the interface.
  81 @end deffn
  82
  83 @deffn {Interface Command} {bandwidth <1-10000000>} {}
  84 @deffnx {Interface Command} {no bandwidth <1-10000000>} {}
  85 Set bandwidth value of the interface in kilobits/sec.  This is for
  86 calculating OSPF cost. This command does not affect the actual device
  87 configuration.
  88 @end deffn
  89
  90 @deffn {Interface Command} {link-detect} {}
  91 @deffnx {Interface Command} {no link-detect} {}
  92 Enable/disable link-detect on platforms which support this. Currently
  93 only Linux and Solaris, and only where network interface drivers support reporting
  94 link-state via the IFF_RUNNING flag.
  95 @end deffn
  96
  97 @node Link Parameters Commands
  98 @subsection Link Parameters Commands
  99
 100 @deffn {Interface Command} {link-params} {}
 101 @deffnx {Interface Command} {no link-param} {}
 102 Enter into the link parameters sub node. At least 'enable' must be set to activate the link parameters,
 103 and consequently Traffic Engineering on this interface. MPLS-TE must be enable at the OSPF (@ref{OSPF Traffic Engineering})
 104 or ISIS (@ref{ISIS Traffic Engineering}) router level in complement to this.
 105 Disable link parameters for this interface.
 106 @end deffn
 107
 108 Under link parameter statement, the following commands set the different TE values:
 109
 110 @deffn link-params {enable}
 111 Enable link parameters for this interface.
 112 @end deffn
 113
 114 @deffn link-params {metric <0-4294967295>} {}
 115 @deffnx link-params {max-bw @var{bandwidth}} {}
 116 @deffnx link-params {max-rsv-bw @var{bandwidth}} {}
 117 @deffnx link-params {unrsv-bw <0-7> @var{bandwidth}} {}
 118 @deffnx link-params {admin-grp @var{bandwidth}} {}
 119 These commands specifies the Traffic Engineering parameters of the interface in conformity to RFC3630 (OSPF)
 120 or RFC5305 (ISIS).
 121 There are respectively the TE Metric (different from the OSPF or ISIS metric), Maximum Bandwidth (interface speed
 122 by default), Maximum Reservable Bandwidth, Unreserved Bandwidth for each 0-7 priority and Admin Group (ISIS) or
 123 Resource Class/Color (OSPF).
 124
 125 Note that @var{bandwidth} are specified in IEEE floating point format and express in Bytes/second.
 126 @end deffn
 127
 128 @deffn  link-param {delay <0-16777215> [min <0-16777215> | max <0-16777215>]} {}
 129 @deffnx  link-param {delay-variation <0-16777215>} {}
 130 @deffnx  link-param {packet-loss @var{percentage}} {}
 131 @deffnx  link-param {res-bw @var{bandwidth}} {}
 132 @deffnx  link-param {ava-bw @var{bandwidth}} {}
 133 @deffnx  link-param {use-bw @var{bandwidth}} {}
 134 These command specifies additionnal Traffic Engineering parameters of the interface in conformity to
 135 draft-ietf-ospf-te-metrics-extension-05.txt and draft-ietf-isis-te-metrics-extension-03.txt. There are
 136 respectively the delay, jitter, loss, available bandwidth, reservable bandwidth and utilized bandwidth.
 137
 138 Note that @var{bandwidth} are specified in IEEE floating point format and express in Bytes/second.
 139 Delays and delay variation are express in micro-second (µs). Loss is specified in @var{percentage} ranging
 140 from 0 to 50.331642% by step of 0.000003.
 141 @end deffn
 142
 143 @deffn link-param {neighbor <A.B.C.D> as <0-65535>} {}
 144 @deffnx link-param {no neighbor} {}
 145 Specifies the remote ASBR IP address and Autonomous System (AS) number for InterASv2 link in OSPF (RFC5392).
 146 Note that this option is not yet supported for ISIS (RFC5316).
 147 @end deffn
 148
 149
 150 @node Static Route Commands
 151 @section Static Route Commands
 152
 153 Static routing is a very fundamental feature of routing technology.  It
 154 defines static prefix and gateway.
 155
 156 @deffn Command {ip route @var{network} @var{gateway}} {}
 157 @var{network} is destination prefix with format of A.B.C.D/M.
 158 @var{gateway} is gateway for the prefix.  When @var{gateway} is
 159 A.B.C.D format.  It is taken as a IPv4 address gateway.  Otherwise it
 160 is treated as an interface name. If the interface name is @var{null0} then
 161 zebra installs a blackhole route.
 162
 163 @example
 164 ip route 10.0.0.0/8 10.0.0.2
 165 ip route 10.0.0.0/8 ppp0
 166 ip route 10.0.0.0/8 null0
 167 @end example
 168
 169 First example defines 10.0.0.0/8 static route with gateway 10.0.0.2.
 170 Second one defines the same prefix but with gateway to interface ppp0. The
 171 third install a blackhole route.
 172 @end deffn
 173
 174 @deffn Command {ip route @var{network} @var{netmask} @var{gateway}} {}
 175 This is alternate version of above command.  When @var{network} is
 176 A.B.C.D format, user must define @var{netmask} value with A.B.C.D
 177 format.  @var{gateway} is same option as above command
 178
 179 @example
 180 ip route 10.0.0.0 255.0.0.0 10.0.0.2
 181 ip route 10.0.0.0 255.0.0.0 ppp0
 182 ip route 10.0.0.0 255.0.0.0 null0
 183 @end example
 184
 185 These statements are equivalent to those in the previous example.
 186 @end deffn
 187
 188 @deffn Command {ip route @var{network} @var{gateway} @var{distance}} {}
 189 Installs the route with the specified distance.
 190 @end deffn
 191
 192 Multiple nexthop static route
 193
 194 @example
 195 ip route 10.0.0.1/32 10.0.0.2
 196 ip route 10.0.0.1/32 10.0.0.3
 197 ip route 10.0.0.1/32 eth0
 198 @end example
 199
 200 If there is no route to 10.0.0.2 and 10.0.0.3, and interface eth0
 201 is reachable, then the last route is installed into the kernel.
 202
 203 If zebra has been compiled with multipath support, and both 10.0.0.2 and
 204 10.0.0.3 are reachable, zebra will install a multipath route via both
 205 nexthops, if the platform supports this.
 206
 207 @example
 208 zebra> show ip route
 209 S>  10.0.0.1/32 [1/0] via 10.0.0.2 inactive
 210                       via 10.0.0.3 inactive
 211   *                   is directly connected, eth0
 212 @end example
 213
 214 @example
 215 ip route 10.0.0.0/8 10.0.0.2
 216 ip route 10.0.0.0/8 10.0.0.3
 217 ip route 10.0.0.0/8 null0 255
 218 @end example
 219
 220 This will install a multihop route via the specified next-hops if they are
 221 reachable, as well as a high-metric blackhole route, which can be useful to
 222 prevent traffic destined for a prefix to match less-specific routes (eg
 223 default) should the specified gateways not be reachable. Eg:
 224
 225 @example
 226 zebra> show ip route 10.0.0.0/8
 227 Routing entry for 10.0.0.0/8
 228   Known via "static", distance 1, metric 0
 229     10.0.0.2 inactive
 230     10.0.0.3 inactive
 231
 232 Routing entry for 10.0.0.0/8
 233   Known via "static", distance 255, metric 0
 234     directly connected, Null0
 235 @end example
 236
 237 @deffn Command {ipv6 route @var{network} @var{gateway}} {}
 238 @deffnx Command {ipv6 route @var{network} @var{gateway} @var{distance}} {}
 239 These behave similarly to their ipv4 counterparts.
 240 @end deffn
 241
 242
 243 @deffn Command {table @var{tableno}} {}
 244 Select the primary kernel routing table to be used.  This only works
 245 for kernels supporting multiple routing tables (like GNU/Linux 2.2.x
 246 and later).  After setting @var{tableno} with this command,
 247 static routes defined after this are added to the specified table.
 248 @end deffn
 249
 250 @node Multicast RIB Commands
 251 @section Multicast RIB Commands
 252
 253 The Multicast RIB provides a separate table of unicast destinations which
 254 is used for Multicast Reverse Path Forwarding decisions.  It is used with
 255 a multicast source's IP address, hence contains not multicast group
 256 addresses but unicast addresses.
 257
 258 This table is fully separate from the default unicast table.  However,
 259 RPF lookup can include the unicast table.
 260
 261 WARNING: RPF lookup results are non-responsive in this version of Quagga,
 262 i.e. multicast routing does not actively react to changes in underlying
 263 unicast topology!
 264
 265 @deffn Command {ip multicast rpf-lookup-mode @var{mode}} {}
 266 @deffnx Command {no ip multicast rpf-lookup-mode [@var{mode}]} {}
 267
 268 @var{mode} sets the method used to perform RPF lookups.  Supported modes:
 269
 270 @table @samp
 271 @item urib-only
 272 Performs the lookup on the Unicast RIB.  The Multicast RIB is never used.
 273 @item mrib-only
 274 Performs the lookup on the Multicast RIB.  The Unicast RIB is never used.
 275 @item mrib-then-urib
 276 Tries to perform the lookup on the Multicast RIB.  If any route is found,
 277 that route is used.  Otherwise, the Unicast RIB is tried.
 278 @item lower-distance
 279 Performs a lookup on the Multicast RIB and Unicast RIB each.  The result
 280 with the lower administrative distance is used;  if they're equal, the
 281 Multicast RIB takes precedence.
 282 @item longer-prefix
 283 Performs a lookup on the Multicast RIB and Unicast RIB each.  The result
 284 with the longer prefix length is used;  if they're equal, the
 285 Multicast RIB takes precedence.
 286 @end table
 287
 288 The @code{mrib-then-urib} setting is the default behavior if nothing is
 289 configured.  If this is the desired behavior, it should be explicitly
 290 configured to make the configuration immune against possible changes in
 291 what the default behavior is.
 292
 293 WARNING: Unreachable routes do not receive special treatment and do not
 294 cause fallback to a second lookup.
 295 @end deffn
 296
 297 @deffn Command {show ip rpf @var{addr}} {}
 298
 299 Performs a Multicast RPF lookup, as configured with
 300 @command{ip multicast rpf-lookup-mode @var{mode}}.  @var{addr} specifies
 301 the multicast source address to look up.
 302
 303 @example
 304 > show ip rpf 192.0.2.1
 305 Routing entry for 192.0.2.0/24 using Unicast RIB
 306   Known via "kernel", distance 0, metric 0, best
 307   * 198.51.100.1, via eth0
 308 @end example
 309
 310 Indicates that a multicast source lookup for 192.0.2.1 would use an
 311 Unicast RIB entry for 192.0.2.0/24 with a gateway of 198.51.100.1.
 312 @end deffn
 313
 314 @deffn Command {show ip rpf} {}
 315
 316 Prints the entire Multicast RIB.  Note that this is independent of the
 317 configured RPF lookup mode, the Multicast RIB may be printed yet not
 318 used at all.
 319 @end deffn
 320
 321 @deffn Command {ip mroute @var{prefix} @var{nexthop} [@var{distance}]} {}
 322 @deffnx Command {no ip mroute @var{prefix} @var{nexthop} [@var{distance}]} {}
 323
 324 Adds a static route entry to the Multicast RIB.  This performs exactly as
 325 the @command{ip route} command, except that it inserts the route in the
 326 Multicast RIB instead of the Unicast RIB.
 327 @end deffn
 328
 329
 330 @node zebra Route Filtering
 331 @section zebra Route Filtering
 332 Zebra supports @command{prefix-list} and @command{route-map} to match
 333 routes received from other quagga components.  The
 334 @command{permit}/@command{deny} facilities provided by these commands
 335 can be used to filter which routes zebra will install in the kernel.
 336
 337 @deffn Command {ip protocol @var{protocol} route-map @var{routemap}} {}
 338 Apply a route-map filter to routes for the specified protocol. @var{protocol}
 339 can be @b{any} or one of
 340 @b{system},
 341 @b{kernel},
 342 @b{connected},
 343 @b{static},
 344 @b{rip},
 345 @b{ripng},
 346 @b{ospf},
 347 @b{ospf6},
 348 @b{isis},
 349 @b{bgp},
 350 @b{hsls}.
 351 @end deffn
 352
 353 @deffn {Route Map} {set src @var{address}}
 354 Within a route-map, set the preferred source address for matching routes
 355 when installing in the kernel.
 356 @end deffn
 357
 358 The following creates a prefix-list that matches all addresses, a route-map
 359 that sets the preferred source address, and applies the route-map to all
 360 @command{rip} routes.
 361
 362 @example
 363 @group
 364 ip prefix-list ANY permit 0.0.0.0/0 le 32
 365 route-map RM1 permit 10
 366      match ip address prefix-list ANY
 367      set src 10.0.0.1
 368
 369 ip protocol rip route-map RM1
 370 @end group
 371 @end example
 372
 373 @node zebra FIB push interface
 374 @section zebra FIB push interface
 375
 376 Zebra supports a 'FIB push' interface that allows an external
 377 component to learn the forwarding information computed by the Quagga
 378 routing suite.
 379
 380 In Quagga, the Routing Information Base (RIB) resides inside
 381 zebra. Routing protocols communicate their best routes to zebra, and
 382 zebra computes the best route across protocols for each prefix. This
 383 latter information makes up the Forwarding Information Base
 384 (FIB). Zebra feeds the FIB to the kernel, which allows the IP stack in
 385 the kernel to forward packets according to the routes computed by
 386 Quagga. The kernel FIB is updated in an OS-specific way. For example,
 387 the @code{netlink} interface is used on Linux, and route sockets are
 388 used on FreeBSD.
 389
 390 The FIB push interface aims to provide a cross-platform mechanism to
 391 support scenarios where the router has a forwarding path that is
 392 distinct from the kernel, commonly a hardware-based fast path. In
 393 these cases, the FIB needs to be maintained reliably in the fast path
 394 as well. We refer to the component that programs the forwarding plane
 395 (directly or indirectly) as the Forwarding Plane Manager or FPM.
 396
 397 The FIB push interface comprises of a TCP connection between zebra and
 398 the FPM. The connection is initiated by zebra -- that is, the FPM acts
 399 as the TCP server.
 400
 401 The relevant zebra code kicks in when zebra is configured with the
 402 @code{--enable-fpm} flag. Zebra periodically attempts to connect to
 403 the well-known FPM port. Once the connection is up, zebra starts
 404 sending messages containing routes over the socket to the FPM. Zebra
 405 sends a complete copy of the forwarding table to the FPM, including
 406 routes that it may have picked up from the kernel. The existing
 407 interaction of zebra with the kernel remains unchanged -- that is, the
 408 kernel continues to receive FIB updates as before.
 409
 410 The encapsulation header for the messages exchanged with the FPM is
 411 defined by the file @file{fpm/fpm.h} in the quagga tree. The routes
 412 themselves are encoded in netlink or protobuf format, with netlink
 413 being the default.
 414
 415 Protobuf is one of a number of new serialization formats wherein the
 416 message schema is expressed in a purpose-built language. Code for
 417 encoding/decoding to/from the wire format is generated from the
 418 schema. Protobuf messages can be extended easily while maintaining
 419 backward-compatibility with older code. Protobuf has the following
 420 advantages over netlink:
 421
 422 @itemize
 423 @item
 424 Code for serialization/deserialization is generated
 425 automatically. This reduces the likelihood of bugs, allows third-party
 426 programs to be integrated quickly, and makes it easy to add fields.
 427 @item
 428 The message format is not tied to an OS (Linux), and can be evolved
 429 independently.
 430 @end itemize
 431
 432 As mentioned before, zebra encodes routes sent to the FPM in netlink
 433 format by default. The format can be controlled via the
 434 @code{--fpm_format} command-line option to zebra, which currently
 435 takes the values @code{netlink} and @code{protobuf}.
 436
 437 The zebra FPM interface uses replace semantics. That is, if a 'route
 438 add' message for a prefix is followed by another 'route add' message,
 439 the information in the second message is complete by itself, and
 440 replaces the information sent in the first message.
 441
 442 If the connection to the FPM goes down for some reason, zebra sends
 443 the FPM a complete copy of the forwarding table(s) when it reconnects.
 444
 445 @node zebra Terminal Mode Commands
 446 @section zebra Terminal Mode Commands
 447
 448 @deffn Command {show ip route} {}
 449 Display current routes which zebra holds in its database.
 450
 451 @example
 452 @group
 453 Router# show ip route
 454 Codes: K - kernel route, C - connected, S - static, R - RIP,
 455        B - BGP * - FIB route.
 456
 457 K* 0.0.0.0/0              203.181.89.241
 458 S  0.0.0.0/0              203.181.89.1
 459 C* 127.0.0.0/8            lo
 460 C* 203.181.89.240/28      eth0
 461 @end group
 462 @end example
 463 @end deffn
 464
 465 @deffn Command {show ipv6 route} {}
 466 @end deffn
 467
 468 @deffn Command {show interface} {}
 469 @end deffn
 470
 471 @deffn Command {show ip prefix-list [@var{name}]} {}
 472 @end deffn
 473
 474 @deffn Command {show route-map [@var{name}]} {}
 475 @end deffn
 476
 477 @deffn Command {show ip protocol} {}
 478 @end deffn
 479
 480 @deffn Command {show ipforward} {}
 481 Display whether the host's IP forwarding function is enabled or not.
 482 Almost any UNIX kernel can be configured with IP forwarding disabled.
 483 If so, the box can't work as a router.
 484 @end deffn
 485
 486 @deffn Command {show ipv6forward} {}
 487 Display whether the host's IP v6 forwarding is enabled or not.
 488 @end deffn
 489
 490 @deffn Command {show zebra fpm stats} {}
 491 Display statistics related to the zebra code that interacts with the
 492 optional Forwarding Plane Manager (FPM) component.
 493 @end deffn
 494
 495 @deffn Command {clear zebra fpm stats} {}
 496 Reset statistics related to the zebra code that interacts with the
 497 optional Forwarding Plane Manager (FPM) component.
 498 @end deffn