main.texi 17 KB

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