Annotation of embedaddon/bird/doc/bird-6.html, revision 1.1
1.1 ! misho 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
! 2: <HTML>
! 3: <HEAD>
! 4: <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9">
! 5: <TITLE>BIRD User's Guide: Protocols</TITLE>
! 6: <LINK HREF="bird-7.html" REL=next>
! 7: <LINK HREF="bird-5.html" REL=previous>
! 8: <LINK HREF="bird.html#toc6" REL=contents>
! 9: </HEAD>
! 10: <BODY>
! 11: <A HREF="bird-7.html">Next</A>
! 12: <A HREF="bird-5.html">Previous</A>
! 13: <A HREF="bird.html#toc6">Contents</A>
! 14: <HR>
! 15: <H2><A NAME="protocols"></A> <A NAME="s6">6.</A> <A HREF="bird.html#toc6">Protocols</A></H2>
! 16:
! 17: <H2><A NAME="babel"></A> <A NAME="ss6.1">6.1</A> <A HREF="bird.html#toc6.1">Babel</A>
! 18: </H2>
! 19:
! 20: <H3><A NAME="babel-intro"></A> Introduction</H3>
! 21:
! 22: <P>The Babel protocol
! 23: (<A HREF="http://www.rfc-editor.org/info/rfc6126">RFC 6126</A>) is a loop-avoiding distance-vector routing protocol that is
! 24: robust and efficient both in ordinary wired networks and in wireless mesh
! 25: networks. Babel is conceptually very simple in its operation and "just works"
! 26: in its default configuration, though some configuration is possible and in some
! 27: cases desirable.
! 28: <P>
! 29: <P>While the Babel protocol is dual stack (i.e., can carry both IPv4 and IPv6
! 30: routes over the same IPv6 transport), BIRD presently implements only the IPv6
! 31: subset of the protocol. No Babel extensions are implemented, but the BIRD
! 32: implementation can coexist with implementations using the extensions (and will
! 33: just ignore extension messages).
! 34: <P>
! 35: <P>The Babel protocol implementation in BIRD is currently in alpha stage.
! 36: <P>
! 37: <H3><A NAME="babel-config"></A> Configuration</H3>
! 38:
! 39: <P>Babel supports no global configuration options apart from those common to all
! 40: other protocols, but supports the following per-interface configuration options:
! 41: <P>
! 42: <HR>
! 43: <PRE>
! 44: protocol babel [<name>] {
! 45: interface <interface pattern> {
! 46: type <wired|wireless>;
! 47: rxcost <number>;
! 48: hello interval <number>;
! 49: update interval <number>;
! 50: port <number>;
! 51: tx class|dscp <number>;
! 52: tx priority <number>;
! 53: rx buffer <number>;
! 54: tx length <number>;
! 55: check link <switch>;
! 56: };
! 57: }
! 58: </PRE>
! 59: <HR>
! 60: <P>
! 61: <DL>
! 62: <DT><CODE>
! 63: <A NAME="babel-type"></A> type wired|wireless </CODE><DD><P>This option specifies the interface type: Wired or wireless. Wired
! 64: interfaces are considered more reliable, and so the default hello
! 65: interval is higher, and a neighbour is considered unreachable after only
! 66: a small number of "hello" packets are lost. On wireless interfaces,
! 67: hello packets are sent more often, and the ETX link quality estimation
! 68: technique is used to compute the metrics of routes discovered over this
! 69: interface. This technique will gradually degrade the metric of routes
! 70: when packets are lost rather than the more binary up/down mechanism of
! 71: wired type links. Default: <CODE>wired</CODE>.
! 72: <P>
! 73: <DT><CODE>
! 74: <A NAME="babel-rxcost"></A> rxcost <I>num</I></CODE><DD><P>This specifies the RX cost of the interface. The route metrics will be
! 75: computed from this value with a mechanism determined by the interface
! 76: <CODE>type</CODE>. Default: 96 for wired interfaces, 256 for wireless.
! 77: <P>
! 78: <DT><CODE>
! 79: <A NAME="babel-hello"></A> hello interval <I>num</I></CODE><DD><P>Interval at which periodic "hello" messages are sent on this interface,
! 80: in seconds. Default: 4 seconds.
! 81: <P>
! 82: <DT><CODE>
! 83: <A NAME="babel-update"></A> update interval <I>num</I></CODE><DD><P>Interval at which periodic (full) updates are sent. Default: 4 times the
! 84: hello interval.
! 85: <P>
! 86: <DT><CODE>
! 87: <A NAME="babel-port"></A> port <I>number</I></CODE><DD><P>This option selects an UDP port to operate on. The default is to operate
! 88: on port 6696 as specified in the Babel RFC.
! 89: <P>
! 90: <DT><CODE>
! 91: <A NAME="babel-tx-class"></A> tx class|dscp|priority <I>number</I></CODE><DD><P>These options specify the ToS/DiffServ/Traffic class/Priority of the
! 92: outgoing Babel packets. See
! 93: <A HREF="bird-3.html#proto-tx-class">tx class</A> common
! 94: option for detailed description.
! 95: <P>
! 96: <DT><CODE>
! 97: <A NAME="babel-rx-buffer"></A> rx buffer <I>number</I></CODE><DD><P>This option specifies the size of buffers used for packet processing.
! 98: The buffer size should be bigger than maximal size of received packets.
! 99: The default value is the interface MTU, and the value will be clamped to a
! 100: minimum of 512 bytes + IP packet overhead.
! 101: <P>
! 102: <DT><CODE>
! 103: <A NAME="babel-tx-length"></A> tx length <I>number</I></CODE><DD><P>This option specifies the maximum length of generated Babel packets. To
! 104: avoid IP fragmentation, it should not exceed the interface MTU value.
! 105: The default value is the interface MTU value, and the value will be
! 106: clamped to a minimum of 512 bytes + IP packet overhead.
! 107: <P>
! 108: <DT><CODE>
! 109: <A NAME="babel-check-link"></A> check link <I>switch</I></CODE><DD><P>If set, the hardware link state (as reported by OS) is taken into
! 110: consideration. When the link disappears (e.g. an ethernet cable is
! 111: unplugged), neighbors are immediately considered unreachable and all
! 112: routes received from them are withdrawn. It is possible that some
! 113: hardware drivers or platforms do not implement this feature. Default:
! 114: yes.
! 115: </DL>
! 116: <P>
! 117: <H3><A NAME="babel-attr"></A> Attributes</H3>
! 118:
! 119: <P>Babel defines just one attribute: the internal babel metric of the route. It
! 120: is exposed as the <CODE>babel_metric</CODE> attribute and has range from 1 to infinity
! 121: (65535).
! 122: <P>
! 123: <H3><A NAME="babel-exam"></A> Example</H3>
! 124:
! 125: <P>
! 126: <HR>
! 127: <PRE>
! 128: protocol babel {
! 129: interface "eth*" {
! 130: type wired;
! 131: };
! 132: interface "wlan0", "wlan1" {
! 133: type wireless;
! 134: hello interval 1;
! 135: rxcost 512;
! 136: };
! 137: interface "tap0";
! 138:
! 139: # This matches the default of babeld: redistribute all addresses
! 140: # configured on local interfaces, plus re-distribute all routes received
! 141: # from other babel peers.
! 142:
! 143: export where (source = RTS_DEVICE) || (source = RTS_BABEL);
! 144: }
! 145: </PRE>
! 146: <HR>
! 147: <P>
! 148: <P>
! 149: <H2><A NAME="bfd"></A> <A NAME="ss6.2">6.2</A> <A HREF="bird.html#toc6.2">BFD</A>
! 150: </H2>
! 151:
! 152: <H3><A NAME="bfd-intro"></A> Introduction</H3>
! 153:
! 154: <P>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it
! 155: is an independent tool providing liveness and failure detection. Routing
! 156: protocols like OSPF and BGP use integrated periodic "hello" messages to monitor
! 157: liveness of neighbors, but detection times of these mechanisms are high (e.g. 40
! 158: seconds by default in OSPF, could be set down to several seconds). BFD offers
! 159: universal, fast and low-overhead mechanism for failure detection, which could be
! 160: attached to any routing protocol in an advisory role.
! 161: <P>
! 162: <P>BFD consists of mostly independent BFD sessions. Each session monitors an
! 163: unicast bidirectional path between two BFD-enabled routers. This is done by
! 164: periodically sending control packets in both directions. BFD does not handle
! 165: neighbor discovery, BFD sessions are created on demand by request of other
! 166: protocols (like OSPF or BGP), which supply appropriate information like IP
! 167: addresses and associated interfaces. When a session changes its state, these
! 168: protocols are notified and act accordingly (e.g. break an OSPF adjacency when
! 169: the BFD session went down).
! 170: <P>
! 171: <P>BIRD implements basic BFD behavior as defined in <A HREF="http://www.rfc-editor.org/info/rfc5880">RFC 5880</A> (some
! 172: advanced features like the echo mode or authentication are not implemented), IP
! 173: transport for BFD as defined in <A HREF="http://www.rfc-editor.org/info/rfc5881">RFC 5881</A> and <A HREF="http://www.rfc-editor.org/info/rfc5883">RFC 5883</A> and
! 174: interaction with client protocols as defined in <A HREF="http://www.rfc-editor.org/info/rfc5882">RFC 5882</A>.
! 175: <P>
! 176: <P>Note that BFD implementation in BIRD is currently a new feature in
! 177: development, expect some rough edges and possible UI and configuration changes
! 178: in the future. Also note that we currently support at most one protocol instance.
! 179: <P>
! 180: <P>BFD packets are sent with a dynamic source port number. Linux systems use by
! 181: default a bit different dynamic port range than the IANA approved one
! 182: (49152-65535). If you experience problems with compatibility, please adjust
! 183: <CODE>/proc/sys/net/ipv4/ip_local_port_range</CODE>
! 184: <P>
! 185: <H3><A NAME="bfd-config"></A> Configuration</H3>
! 186:
! 187: <P>BFD configuration consists mainly of multiple definitions of interfaces.
! 188: Most BFD config options are session specific. When a new session is requested
! 189: and dynamically created, it is configured from one of these definitions. For
! 190: sessions to directly connected neighbors, <CODE>interface</CODE> definitions are chosen
! 191: based on the interface associated with the session, while <CODE>multihop</CODE>
! 192: definition is used for multihop sessions. If no definition is relevant, the
! 193: session is just created with the default configuration. Therefore, an empty BFD
! 194: configuration is often sufficient.
! 195: <P>
! 196: <P>Note that to use BFD for other protocols like OSPF or BGP, these protocols
! 197: also have to be configured to request BFD sessions, usually by <CODE>bfd</CODE> option.
! 198: <P>
! 199: <P>Some of BFD session options require <I>time</I> value, which has to be specified
! 200: with the appropriate unit: <I>num</I> <CODE>s</CODE>|<CODE>ms</CODE>|<CODE>us</CODE>. Although microseconds
! 201: are allowed as units, practical minimum values are usually in order of tens of
! 202: milliseconds.
! 203: <P>
! 204: <HR>
! 205: <PRE>
! 206: protocol bfd [<name>] {
! 207: interface <interface pattern> {
! 208: interval <time>;
! 209: min rx interval <time>;
! 210: min tx interval <time>;
! 211: idle tx interval <time>;
! 212: multiplier <num>;
! 213: passive <switch>;
! 214: authentication none;
! 215: authentication simple;
! 216: authentication [meticulous] keyed md5|sha1;
! 217: password "<text>";
! 218: password "<text>" {
! 219: id <num>;
! 220: generate from "<date>";
! 221: generate to "<date>";
! 222: accept from "<date>";
! 223: accept to "<date>";
! 224: from "<date>";
! 225: to "<date>";
! 226: };
! 227: };
! 228: multihop {
! 229: interval <time>;
! 230: min rx interval <time>;
! 231: min tx interval <time>;
! 232: idle tx interval <time>;
! 233: multiplier <num>;
! 234: passive <switch>;
! 235: };
! 236: neighbor <ip> [dev "<interface>"] [local <ip>] [multihop <switch>];
! 237: }
! 238: </PRE>
! 239: <HR>
! 240: <P>
! 241: <DL>
! 242: <DT><CODE>
! 243: <A NAME="bfd-iface"></A> interface <I>pattern</I> [, <I>...</I>] { <I>options</I> }</CODE><DD><P>Interface definitions allow to specify options for sessions associated
! 244: with such interfaces and also may contain interface specific options.
! 245: See
! 246: <A HREF="bird-3.html#proto-iface">interface</A> common option for a detailed
! 247: description of interface patterns. Note that contrary to the behavior of
! 248: <CODE>interface</CODE> definitions of other protocols, BFD protocol would accept
! 249: sessions (in default configuration) even on interfaces not covered by
! 250: such definitions.
! 251: <P>
! 252: <DT><CODE>
! 253: <A NAME="bfd-multihop"></A> multihop { <I>options</I> }</CODE><DD><P>Multihop definitions allow to specify options for multihop BFD sessions,
! 254: in the same manner as <CODE>interface</CODE> definitions are used for directly
! 255: connected sessions. Currently only one such definition (for all multihop
! 256: sessions) could be used.
! 257: <P>
! 258: <DT><CODE>
! 259: <A NAME="bfd-neighbor"></A> neighbor <I>ip</I> [dev "<I>interface</I>"] [local <I>ip</I>] [multihop <I>switch</I>]</CODE><DD><P>BFD sessions are usually created on demand as requested by other
! 260: protocols (like OSPF or BGP). This option allows to explicitly add
! 261: a BFD session to the specified neighbor regardless of such requests.
! 262: <P>The session is identified by the IP address of the neighbor, with
! 263: optional specification of used interface and local IP. By default
! 264: the neighbor must be directly connected, unless the session is
! 265: configured as multihop. Note that local IP must be specified for
! 266: multihop sessions.
! 267: </DL>
! 268: <P>
! 269: <P>Session specific options (part of <CODE>interface</CODE> and <CODE>multihop</CODE> definitions):
! 270: <P>
! 271: <DL>
! 272: <DT><CODE>
! 273: <A NAME="bfd-interval"></A> interval <I>time</I></CODE><DD><P>BFD ensures availability of the forwarding path associated with the
! 274: session by periodically sending BFD control packets in both
! 275: directions. The rate of such packets is controlled by two options,
! 276: <CODE>min rx interval</CODE> and <CODE>min tx interval</CODE> (see below). This option
! 277: is just a shorthand to set both of these options together.
! 278: <P>
! 279: <DT><CODE>
! 280: <A NAME="bfd-min-rx-interval"></A> min rx interval <I>time</I></CODE><DD><P>This option specifies the minimum RX interval, which is announced to the
! 281: neighbor and used there to limit the neighbor's rate of generated BFD
! 282: control packets. Default: 10 ms.
! 283: <P>
! 284: <DT><CODE>
! 285: <A NAME="bfd-min-tx-interval"></A> min tx interval <I>time</I></CODE><DD><P>This option specifies the desired TX interval, which controls the rate
! 286: of generated BFD control packets (together with <CODE>min rx interval</CODE>
! 287: announced by the neighbor). Note that this value is used only if the BFD
! 288: session is up, otherwise the value of <CODE>idle tx interval</CODE> is used
! 289: instead. Default: 100 ms.
! 290: <P>
! 291: <DT><CODE>
! 292: <A NAME="bfd-idle-tx-interval"></A> idle tx interval <I>time</I></CODE><DD><P>In order to limit unnecessary traffic in cases where a neighbor is not
! 293: available or not running BFD, the rate of generated BFD control packets
! 294: is lower when the BFD session is not up. This option specifies the
! 295: desired TX interval in such cases instead of <CODE>min tx interval</CODE>.
! 296: Default: 1 s.
! 297: <P>
! 298: <DT><CODE>
! 299: <A NAME="bfd-multiplier"></A> multiplier <I>num</I></CODE><DD><P>Failure detection time for BFD sessions is based on established rate of
! 300: BFD control packets (<CODE>min rx/tx interval</CODE>) multiplied by this
! 301: multiplier, which is essentially (ignoring jitter) a number of missed
! 302: packets after which the session is declared down. Note that rates and
! 303: multipliers could be different in each direction of a BFD session.
! 304: Default: 5.
! 305: <P>
! 306: <DT><CODE>
! 307: <A NAME="bfd-passive"></A> passive <I>switch</I></CODE><DD><P>Generally, both BFD session endpoints try to establish the session by
! 308: sending control packets to the other side. This option allows to enable
! 309: passive mode, which means that the router does not send BFD packets
! 310: until it has received one from the other side. Default: disabled.
! 311: <P>
! 312: <DT><CODE>authentication none</CODE><DD><P>No passwords are sent in BFD packets. This is the default value.
! 313: <P>
! 314: <DT><CODE>authentication simple</CODE><DD><P>Every packet carries 16 bytes of password. Received packets lacking this
! 315: password are ignored. This authentication mechanism is very weak.
! 316: <P>
! 317: <DT><CODE>authentication [meticulous] keyed md5|sha1</CODE><DD><P>An authentication code is appended to each packet. The cryptographic
! 318: algorithm is keyed MD5 or keyed SHA-1. Note that the algorithm is common
! 319: for all keys (on one interface), in contrast to OSPF or RIP, where it
! 320: is a per-key option. Passwords (keys) are not sent open via network.
! 321: <P>The <CODE>meticulous</CODE> variant means that cryptographic sequence numbers
! 322: are increased for each sent packet, while in the basic variant they are
! 323: increased about once per second. Generally, the <CODE>meticulous</CODE> variant
! 324: offers better resistance to replay attacks but may require more
! 325: computation.
! 326: <P>
! 327: <DT><CODE>password "<I>text</I>"</CODE><DD><P>Specifies a password used for authentication. See
! 328: <A HREF="bird-3.html#proto-iface">interface</A><@@ref>dsc-passpassword</A> common option for detailed description. Note that
! 329: password option <CODE>algorithm</CODE> is not available in BFD protocol. The
! 330: algorithm is selected by <CODE>authentication</CODE> option for all passwords.
! 331: <P>
! 332: </DL>
! 333: <P>
! 334: <H3><A NAME="bfd-exam"></A> Example</H3>
! 335:
! 336: <P>
! 337: <HR>
! 338: <PRE>
! 339: protocol bfd {
! 340: interface "eth*" {
! 341: min rx interval 20 ms;
! 342: min tx interval 50 ms;
! 343: idle tx interval 300 ms;
! 344: };
! 345: interface "gre*" {
! 346: interval 200 ms;
! 347: multiplier 10;
! 348: passive;
! 349: };
! 350: multihop {
! 351: interval 200 ms;
! 352: multiplier 10;
! 353: };
! 354:
! 355: neighbor 192.168.1.10;
! 356: neighbor 192.168.2.2 dev "eth2";
! 357: neighbor 192.168.10.1 local 192.168.1.1 multihop;
! 358: }
! 359: </PRE>
! 360: <HR>
! 361: <P>
! 362: <P>
! 363: <H2><A NAME="bgp"></A> <A NAME="ss6.3">6.3</A> <A HREF="bird.html#toc6.3">BGP</A>
! 364: </H2>
! 365:
! 366: <P>The Border Gateway Protocol is the routing protocol used for backbone level
! 367: routing in the today's Internet. Contrary to other protocols, its convergence
! 368: does not rely on all routers following the same rules for route selection,
! 369: making it possible to implement any routing policy at any router in the network,
! 370: the only restriction being that if a router advertises a route, it must accept
! 371: and forward packets according to it.
! 372: <P>
! 373: <P>BGP works in terms of autonomous systems (often abbreviated as AS). Each AS
! 374: is a part of the network with common management and common routing policy. It is
! 375: identified by a unique 16-bit number (ASN). Routers within each AS usually
! 376: exchange AS-internal routing information with each other using an interior
! 377: gateway protocol (IGP, such as OSPF or RIP). Boundary routers at the border of
! 378: the AS communicate global (inter-AS) network reachability information with their
! 379: neighbors in the neighboring AS'es via exterior BGP (eBGP) and redistribute
! 380: received information to other routers in the AS via interior BGP (iBGP).
! 381: <P>
! 382: <P>Each BGP router sends to its neighbors updates of the parts of its routing
! 383: table it wishes to export along with complete path information (a list of AS'es
! 384: the packet will travel through if it uses the particular route) in order to
! 385: avoid routing loops.
! 386: <P>
! 387: <P>BIRD supports all requirements of the BGP4 standard as defined in
! 388: <A HREF="http://www.rfc-editor.org/info/rfc4271">RFC 4271</A> It also supports the community attributes (<A HREF="http://www.rfc-editor.org/info/rfc1997">RFC 1997</A>),
! 389: capability negotiation (<A HREF="http://www.rfc-editor.org/info/rfc5492">RFC 5492</A>), MD5 password authentication (<A HREF="http://www.rfc-editor.org/info/rfc2385">RFC 2385</A>), extended communities (<A HREF="http://www.rfc-editor.org/info/rfc4360">RFC 4360</A>), route reflectors (<A HREF="http://www.rfc-editor.org/info/rfc4456">RFC 4456</A>), graceful restart (<A HREF="http://www.rfc-editor.org/info/rfc4724">RFC 4724</A>), multiprotocol extensions
! 390: (<A HREF="http://www.rfc-editor.org/info/rfc4760">RFC 4760</A>), 4B AS numbers (<A HREF="http://www.rfc-editor.org/info/rfc4893">RFC 4893</A>), and 4B AS numbers in
! 391: extended communities (<A HREF="http://www.rfc-editor.org/info/rfc5668">RFC 5668</A>).
! 392: <P>
! 393: <P>For IPv6, it uses the standard multiprotocol extensions defined in
! 394: <A HREF="http://www.rfc-editor.org/info/rfc4760">RFC 4760</A> and applied to IPv6 according to <A HREF="http://www.rfc-editor.org/info/rfc2545">RFC 2545</A>.
! 395: <P>
! 396: <H3><A NAME="bgp-route-select-rules"></A> Route selection rules</H3>
! 397:
! 398: <P>BGP doesn't have any simple metric, so the rules for selection of an optimal
! 399: route among multiple BGP routes with the same preference are a bit more complex
! 400: and they are implemented according to the following algorithm. It starts the
! 401: first rule, if there are more "best" routes, then it uses the second rule to
! 402: choose among them and so on.
! 403: <P>
! 404: <UL>
! 405: <LI>Prefer route with the highest Local Preference attribute.</LI>
! 406: <LI>Prefer route with the shortest AS path.</LI>
! 407: <LI>Prefer IGP origin over EGP and EGP origin over incomplete.</LI>
! 408: <LI>Prefer the lowest value of the Multiple Exit Discriminator.</LI>
! 409: <LI>Prefer routes received via eBGP over ones received via iBGP.</LI>
! 410: <LI>Prefer routes with lower internal distance to a boundary router.</LI>
! 411: <LI>Prefer the route with the lowest value of router ID of the
! 412: advertising router.</LI>
! 413: </UL>
! 414: <P>
! 415: <H3><A NAME="bgp-igp-routing-table"></A> IGP routing table</H3>
! 416:
! 417: <P>BGP is mainly concerned with global network reachability and with routes to
! 418: other autonomous systems. When such routes are redistributed to routers in the
! 419: AS via BGP, they contain IP addresses of a boundary routers (in route attribute
! 420: NEXT_HOP). BGP depends on existing IGP routing table with AS-internal routes to
! 421: determine immediate next hops for routes and to know their internal distances to
! 422: boundary routers for the purpose of BGP route selection. In BIRD, there is
! 423: usually one routing table used for both IGP routes and BGP routes.
! 424: <P>
! 425: <H3><A NAME="bgp-config"></A> Configuration</H3>
! 426:
! 427: <P>Each instance of the BGP corresponds to one neighboring router. This allows
! 428: to set routing policy and all the other parameters differently for each neighbor
! 429: using the following configuration parameters:
! 430: <P>
! 431: <DL>
! 432: <DT><CODE>
! 433: <A NAME="bgp-local"></A> local [<I>ip</I>] as <I>number</I></CODE><DD><P>Define which AS we are part of. (Note that contrary to other IP routers,
! 434: BIRD is able to act as a router located in multiple AS'es simultaneously,
! 435: but in such cases you need to tweak the BGP paths manually in the filters
! 436: to get consistent behavior.) Optional <CODE>ip</CODE> argument specifies a source
! 437: address, equivalent to the <CODE>source address</CODE> option (see below). This
! 438: parameter is mandatory.
! 439: <P>
! 440: <DT><CODE>
! 441: <A NAME="bgp-neighbor"></A> neighbor [<I>ip</I>] [port <I>number</I>] [as <I>number</I>]</CODE><DD><P>Define neighboring router this instance will be talking to and what AS
! 442: it is located in. In case the neighbor is in the same AS as we are, we
! 443: automatically switch to iBGP. Optionally, the remote port may also be
! 444: specified. The parameter may be used multiple times with different
! 445: sub-options (e.g., both <CODE>neighbor 10.0.0.1 as 65000;</CODE> and
! 446: <CODE>neighbor 10.0.0.1; neighbor as 65000;</CODE> are valid). This parameter is
! 447: mandatory.
! 448: <P>
! 449: <DT><CODE>
! 450: <A NAME="bgp-iface"></A> interface <I>string</I></CODE><DD><P>Define interface we should use for link-local BGP IPv6 sessions.
! 451: Interface can also be specified as a part of <CODE>neighbor address</CODE>
! 452: (e.g., <CODE>neighbor fe80::1234%eth0 as 65000;</CODE>). It is an error to use
! 453: this parameter for non link-local sessions.
! 454: <P>
! 455: <DT><CODE>
! 456: <A NAME="bgp-direct"></A> direct</CODE><DD><P>Specify that the neighbor is directly connected. The IP address of the
! 457: neighbor must be from a directly reachable IP range (i.e. associated
! 458: with one of your router's interfaces), otherwise the BGP session
! 459: wouldn't start but it would wait for such interface to appear. The
! 460: alternative is the <CODE>multihop</CODE> option. Default: enabled for eBGP.
! 461: <P>
! 462: <DT><CODE>
! 463: <A NAME="bgp-multihop"></A> multihop [<I>number</I>]</CODE><DD><P>Configure multihop BGP session to a neighbor that isn't directly
! 464: connected. Accurately, this option should be used if the configured
! 465: neighbor IP address does not match with any local network subnets. Such
! 466: IP address have to be reachable through system routing table. The
! 467: alternative is the <CODE>direct</CODE> option. For multihop BGP it is
! 468: recommended to explicitly configure the source address to have it
! 469: stable. Optional <CODE>number</CODE> argument can be used to specify the number
! 470: of hops (used for TTL). Note that the number of networks (edges) in a
! 471: path is counted; i.e., if two BGP speakers are separated by one router,
! 472: the number of hops is 2. Default: enabled for iBGP.
! 473: <P>
! 474: <DT><CODE>
! 475: <A NAME="bgp-source-address"></A> source address <I>ip</I></CODE><DD><P>Define local address we should use for next hop calculation and as a
! 476: source address for the BGP session. Default: the address of the local
! 477: end of the interface our neighbor is connected to.
! 478: <P>
! 479: <DT><CODE>
! 480: <A NAME="bgp-next-hop-self"></A> next hop self</CODE><DD><P>Avoid calculation of the Next Hop attribute and always advertise our own
! 481: source address as a next hop. This needs to be used only occasionally to
! 482: circumvent misconfigurations of other routers. Default: disabled.
! 483: <P>
! 484: <DT><CODE>
! 485: <A NAME="bgp-next-hop-keep"></A> next hop keep</CODE><DD><P>Forward the received Next Hop attribute even in situations where the
! 486: local address should be used instead, like when the route is sent to an
! 487: interface with a different subnet. Default: disabled.
! 488: <P>
! 489: <DT><CODE>
! 490: <A NAME="bgp-missing-lladdr"></A> missing lladdr self|drop|ignore</CODE><DD><P>Next Hop attribute in BGP-IPv6 sometimes contains just the global IPv6
! 491: address, but sometimes it has to contain both global and link-local IPv6
! 492: addresses. This option specifies what to do if BIRD have to send both
! 493: addresses but does not know link-local address. This situation might
! 494: happen when routes from other protocols are exported to BGP, or when
! 495: improper updates are received from BGP peers. <CODE>self</CODE> means that BIRD
! 496: advertises its own local address instead. <CODE>drop</CODE> means that BIRD
! 497: skips that prefixes and logs error. <CODE>ignore</CODE> means that BIRD ignores
! 498: the problem and sends just the global address (and therefore forms
! 499: improper BGP update). Default: <CODE>self</CODE>, unless BIRD is configured as a
! 500: route server (option <CODE>rs client</CODE>), in that case default is <CODE>ignore</CODE>,
! 501: because route servers usually do not forward packets themselves.
! 502: <P>
! 503: <DT><CODE>
! 504: <A NAME="bgp-gateway"></A> gateway direct|recursive</CODE><DD><P>For received routes, their <CODE>gw</CODE> (immediate next hop) attribute is
! 505: computed from received <CODE>bgp_next_hop</CODE> attribute. This option
! 506: specifies how it is computed. Direct mode means that the IP address from
! 507: <CODE>bgp_next_hop</CODE> is used if it is directly reachable, otherwise the
! 508: neighbor IP address is used. Recursive mode means that the gateway is
! 509: computed by an IGP routing table lookup for the IP address from
! 510: <CODE>bgp_next_hop</CODE>. Note that there is just one level of indirection in
! 511: recursive mode - the route obtained by the lookup must not be recursive
! 512: itself, to prevent mutually recursive routes.
! 513: <P>Recursive mode is the behavior specified by the BGP
! 514: standard. Direct mode is simpler, does not require any routes in a
! 515: routing table, and was used in older versions of BIRD, but does not
! 516: handle well nontrivial iBGP setups and multihop. Recursive mode is
! 517: incompatible with
! 518: <A HREF="bird-2.html#dsc-table-sorted">sorted tables</A>. Default:
! 519: <CODE>direct</CODE> for direct sessions, <CODE>recursive</CODE> for multihop sessions.
! 520: <P>
! 521: <DT><CODE>
! 522: <A NAME="bgp-igp-table"></A> igp table <I>name</I></CODE><DD><P>Specifies a table that is used as an IGP routing table. Default: the
! 523: same as the table BGP is connected to.
! 524: <P>
! 525: <DT><CODE>
! 526: <A NAME="bgp-check-link"></A> check link <I>switch</I></CODE><DD><P>BGP could use hardware link state into consideration. If enabled,
! 527: BIRD tracks the link state of the associated interface and when link
! 528: disappears (e.g. an ethernet cable is unplugged), the BGP session is
! 529: immediately shut down. Note that this option cannot be used with
! 530: multihop BGP. Default: disabled.
! 531: <P>
! 532: <DT><CODE>
! 533: <A NAME="bgp-bfd"></A> bfd <I>switch</I></CODE><DD><P>BGP could use BFD protocol as an advisory mechanism for neighbor
! 534: liveness and failure detection. If enabled, BIRD setups a BFD session
! 535: for the BGP neighbor and tracks its liveness by it. This has an
! 536: advantage of an order of magnitude lower detection times in case of
! 537: failure. Note that BFD protocol also has to be configured, see
! 538: <A HREF="#bfd">BFD</A> section for details. Default: disabled.
! 539: <P>
! 540: <DT><CODE>
! 541: <A NAME="bgp-ttl-security"></A> ttl security <I>switch</I></CODE><DD><P>Use GTSM (<A HREF="http://www.rfc-editor.org/info/rfc5082">RFC 5082</A> - the generalized TTL security mechanism). GTSM
! 542: protects against spoofed packets by ignoring received packets with a
! 543: smaller than expected TTL. To work properly, GTSM have to be enabled on
! 544: both sides of a BGP session. If both <CODE>ttl security</CODE> and
! 545: <CODE>multihop</CODE> options are enabled, <CODE>multihop</CODE> option should specify
! 546: proper hop value to compute expected TTL. Kernel support required:
! 547: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only.
! 548: Note that full (ICMP protection, for example) <A HREF="http://www.rfc-editor.org/info/rfc5082">RFC 5082</A> support is
! 549: provided by Linux only. Default: disabled.
! 550: <P>
! 551: <DT><CODE>
! 552: <A NAME="bgp-pass"></A> password <I>string</I></CODE><DD><P>Use this password for MD5 authentication of BGP sessions (<A HREF="http://www.rfc-editor.org/info/rfc2385">RFC 2385</A>). When
! 553: used on BSD systems, see also <CODE>setkey</CODE> option below. Default: no
! 554: authentication.
! 555: <P>
! 556: <DT><CODE>
! 557: <A NAME="bgp-setkey"></A> setkey <I>switch</I></CODE><DD><P>On BSD systems, keys for TCP MD5 authentication are stored in the global
! 558: SA/SP database, which can be accessed by external utilities (e.g.
! 559: setkey(8)). BIRD configures security associations in the SA/SP database
! 560: automatically based on <CODE>password</CODE> options (see above), this option
! 561: allows to disable automatic updates by BIRD when manual configuration by
! 562: external utilities is preferred. Note that automatic SA/SP database
! 563: updates are currently implemented only for FreeBSD. Passwords have to be
! 564: set manually by an external utility on NetBSD and OpenBSD. Default:
! 565: enabled (ignored on non-FreeBSD).
! 566: <P>
! 567: <DT><CODE>
! 568: <A NAME="bgp-passive"></A> passive <I>switch</I></CODE><DD><P>Standard BGP behavior is both initiating outgoing connections and
! 569: accepting incoming connections. In passive mode, outgoing connections
! 570: are not initiated. Default: off.
! 571: <P>
! 572: <DT><CODE>
! 573: <A NAME="bgp-rr-client"></A> rr client</CODE><DD><P>Be a route reflector and treat the neighbor as a route reflection
! 574: client. Default: disabled.
! 575: <P>
! 576: <DT><CODE>
! 577: <A NAME="bgp-rr-cluster-id"></A> rr cluster id <I>IPv4 address</I></CODE><DD><P>Route reflectors use cluster id to avoid route reflection loops. When
! 578: there is one route reflector in a cluster it usually uses its router id
! 579: as a cluster id, but when there are more route reflectors in a cluster,
! 580: these need to be configured (using this option) to use a common cluster
! 581: id. Clients in a cluster need not know their cluster id and this option
! 582: is not allowed for them. Default: the same as router id.
! 583: <P>
! 584: <DT><CODE>
! 585: <A NAME="bgp-rs-client"></A> rs client</CODE><DD><P>Be a route server and treat the neighbor as a route server client.
! 586: A route server is used as a replacement for full mesh EBGP routing in
! 587: Internet exchange points in a similar way to route reflectors used in
! 588: IBGP routing. BIRD does not implement obsoleted <A HREF="http://www.rfc-editor.org/info/rfc1863">RFC 1863</A>, but
! 589: uses ad-hoc implementation, which behaves like plain EBGP but reduces
! 590: modifications to advertised route attributes to be transparent (for
! 591: example does not prepend its AS number to AS PATH attribute and
! 592: keeps MED attribute). Default: disabled.
! 593: <P>
! 594: <DT><CODE>
! 595: <A NAME="bgp-secondary"></A> secondary <I>switch</I></CODE><DD><P>Usually, if an export filter rejects a selected route, no other route is
! 596: propagated for that network. This option allows to try the next route in
! 597: order until one that is accepted is found or all routes for that network
! 598: are rejected. This can be used for route servers that need to propagate
! 599: different tables to each client but do not want to have these tables
! 600: explicitly (to conserve memory). This option requires that the connected
! 601: routing table is
! 602: <A HREF="bird-2.html#dsc-table-sorted">sorted</A>. Default: off.
! 603: <P>
! 604: <DT><CODE>
! 605: <A NAME="bgp-add-paths"></A> add paths <I>switch</I>|rx|tx</CODE><DD><P>Standard BGP can propagate only one path (route) per destination network
! 606: (usually the selected one). This option controls the add-path protocol
! 607: extension, which allows to advertise any number of paths to a
! 608: destination. Note that to be active, add-path has to be enabled on both
! 609: sides of the BGP session, but it could be enabled separately for RX and
! 610: TX direction. When active, all available routes accepted by the export
! 611: filter are advertised to the neighbor. Default: off.
! 612: <P>
! 613: <DT><CODE>
! 614: <A NAME="bgp-allow-local-as"></A> allow local as [<I>number</I>]</CODE><DD><P>BGP prevents routing loops by rejecting received routes with the local
! 615: AS number in the AS path. This option allows to loose or disable the
! 616: check. Optional <CODE>number</CODE> argument can be used to specify the maximum
! 617: number of local ASNs in the AS path that is allowed for received
! 618: routes. When the option is used without the argument, the check is
! 619: completely disabled and you should ensure loop-free behavior by some
! 620: other means. Default: 0 (no local AS number allowed).
! 621: <P>
! 622: <DT><CODE>
! 623: <A NAME="bgp-enable-route-refresh"></A> enable route refresh <I>switch</I></CODE><DD><P>After the initial route exchange, BGP protocol uses incremental updates
! 624: to keep BGP speakers synchronized. Sometimes (e.g., if BGP speaker
! 625: changes its import filter, or if there is suspicion of inconsistency) it
! 626: is necessary to do a new complete route exchange. BGP protocol extension
! 627: Route Refresh (<A HREF="http://www.rfc-editor.org/info/rfc2918">RFC 2918</A>) allows BGP speaker to request
! 628: re-advertisement of all routes from its neighbor. BGP protocol
! 629: extension Enhanced Route Refresh (<A HREF="http://www.rfc-editor.org/info/rfc7313">RFC 7313</A>) specifies explicit
! 630: begin and end for such exchanges, therefore the receiver can remove
! 631: stale routes that were not advertised during the exchange. This option
! 632: specifies whether BIRD advertises these capabilities and supports
! 633: related procedures. Note that even when disabled, BIRD can send route
! 634: refresh requests. Default: on.
! 635: <P>
! 636: <DT><CODE>
! 637: <A NAME="bgp-graceful-restart"></A> graceful restart <I>switch</I>|aware</CODE><DD><P>When a BGP speaker restarts or crashes, neighbors will discard all
! 638: received paths from the speaker, which disrupts packet forwarding even
! 639: when the forwarding plane of the speaker remains intact. <A HREF="http://www.rfc-editor.org/info/rfc4724">RFC 4724</A> specifies an optional graceful restart mechanism to
! 640: alleviate this issue. This option controls the mechanism. It has three
! 641: states: Disabled, when no support is provided. Aware, when the graceful
! 642: restart support is announced and the support for restarting neighbors
! 643: is provided, but no local graceful restart is allowed (i.e.
! 644: receiving-only role). Enabled, when the full graceful restart
! 645: support is provided (i.e. both restarting and receiving role). Note
! 646: that proper support for local graceful restart requires also
! 647: configuration of other protocols. Default: aware.
! 648: <P>
! 649: <DT><CODE>
! 650: <A NAME="bgp-graceful-restart-time"></A> graceful restart time <I>number</I></CODE><DD><P>The restart time is announced in the BGP graceful restart capability
! 651: and specifies how long the neighbor would wait for the BGP session to
! 652: re-establish after a restart before deleting stale routes. Default:
! 653: 120 seconds.
! 654: <P>
! 655: <DT><CODE>
! 656: <A NAME="bgp-interpret-communities"></A> interpret communities <I>switch</I></CODE><DD><P><A HREF="http://www.rfc-editor.org/info/rfc1997">RFC 1997</A> demands that BGP speaker should process well-known
! 657: communities like no-export (65535, 65281) or no-advertise (65535,
! 658: 65282). For example, received route carrying a no-adverise community
! 659: should not be advertised to any of its neighbors. If this option is
! 660: enabled (which is by default), BIRD has such behavior automatically (it
! 661: is evaluated when a route is exported to the BGP protocol just before
! 662: the export filter). Otherwise, this integrated processing of
! 663: well-known communities is disabled. In that case, similar behavior can
! 664: be implemented in the export filter. Default: on.
! 665: <P>
! 666: <DT><CODE>
! 667: <A NAME="bgp-enable-as4"></A> enable as4 <I>switch</I></CODE><DD><P>BGP protocol was designed to use 2B AS numbers and was extended later to
! 668: allow 4B AS number. BIRD supports 4B AS extension, but by disabling this
! 669: option it can be persuaded not to advertise it and to maintain old-style
! 670: sessions with its neighbors. This might be useful for circumventing bugs
! 671: in neighbor's implementation of 4B AS extension. Even when disabled
! 672: (off), BIRD behaves internally as AS4-aware BGP router. Default: on.
! 673: <P>
! 674: <DT><CODE>
! 675: <A NAME="bgp-enable-extended-messages"></A> enable extended messages <I>switch</I></CODE><DD><P>The BGP protocol uses maximum message length of 4096 bytes. This option
! 676: provides an extension to allow extended messages with length up
! 677: to 65535 bytes. Default: off.
! 678: <P>
! 679: <DT><CODE>
! 680: <A NAME="bgp-capabilities"></A> capabilities <I>switch</I></CODE><DD><P>Use capability advertisement to advertise optional capabilities. This is
! 681: standard behavior for newer BGP implementations, but there might be some
! 682: older BGP implementations that reject such connection attempts. When
! 683: disabled (off), features that request it (4B AS support) are also
! 684: disabled. Default: on, with automatic fallback to off when received
! 685: capability-related error.
! 686: <P>
! 687: <DT><CODE>
! 688: <A NAME="bgp-advertise-ipv4"></A> advertise ipv4 <I>switch</I></CODE><DD><P>Advertise IPv4 multiprotocol capability. This is not a correct behavior
! 689: according to the strict interpretation of <A HREF="http://www.rfc-editor.org/info/rfc4760">RFC 4760</A>, but it is
! 690: widespread and required by some BGP implementations (Cisco and Quagga).
! 691: This option is relevant to IPv4 mode with enabled capability
! 692: advertisement only. Default: on.
! 693: <P>
! 694: <DT><CODE>
! 695: <A NAME="bgp-route-limit"></A> route limit <I>number</I></CODE><DD><P>The maximal number of routes that may be imported from the protocol. If
! 696: the route limit is exceeded, the connection is closed with an error.
! 697: Limit is currently implemented as <CODE>import limit <I>number</I> action
! 698: restart</CODE>. This option is obsolete and it is replaced by
! 699: <A HREF="bird-3.html#proto-import-limit">import limit option</A>. Default: no limit.
! 700: <P>
! 701: <DT><CODE>
! 702: <A NAME="bgp-disable-after-error"></A> disable after error <I>switch</I></CODE><DD><P>When an error is encountered (either locally or by the other side),
! 703: disable the instance automatically and wait for an administrator to fix
! 704: the problem manually. Default: off.
! 705: <P>
! 706: <DT><CODE>
! 707: <A NAME="bgp-hold-time"></A> hold time <I>number</I></CODE><DD><P>Time in seconds to wait for a Keepalive message from the other side
! 708: before considering the connection stale. Default: depends on agreement
! 709: with the neighboring router, we prefer 240 seconds if the other side is
! 710: willing to accept it.
! 711: <P>
! 712: <DT><CODE>
! 713: <A NAME="bgp-startup-hold-time"></A> startup hold time <I>number</I></CODE><DD><P>Value of the hold timer used before the routers have a chance to exchange
! 714: open messages and agree on the real value. Default: 240 seconds.
! 715: <P>
! 716: <DT><CODE>
! 717: <A NAME="bgp-keepalive-time"></A> keepalive time <I>number</I></CODE><DD><P>Delay in seconds between sending of two consecutive Keepalive messages.
! 718: Default: One third of the hold time.
! 719: <P>
! 720: <DT><CODE>
! 721: <A NAME="bgp-connect-delay-time"></A> connect delay time <I>number</I></CODE><DD><P>Delay in seconds between protocol startup and the first attempt to
! 722: connect. Default: 5 seconds.
! 723: <P>
! 724: <DT><CODE>
! 725: <A NAME="bgp-connect-retry-time"></A> connect retry time <I>number</I></CODE><DD><P>Time in seconds to wait before retrying a failed attempt to connect.
! 726: Default: 120 seconds.
! 727: <P>
! 728: <DT><CODE>
! 729: <A NAME="bgp-error-wait-time"></A> error wait time <I>number</I>,<I>number</I></CODE><DD><P>Minimum and maximum delay in seconds between a protocol failure (either
! 730: local or reported by the peer) and automatic restart. Doesn't apply
! 731: when <CODE>disable after error</CODE> is configured. If consecutive errors
! 732: happen, the delay is increased exponentially until it reaches the
! 733: maximum. Default: 60, 300.
! 734: <P>
! 735: <DT><CODE>
! 736: <A NAME="bgp-error-forget-time"></A> error forget time <I>number</I></CODE><DD><P>Maximum time in seconds between two protocol failures to treat them as a
! 737: error sequence which makes <CODE>error wait time</CODE> increase exponentially.
! 738: Default: 300 seconds.
! 739: <P>
! 740: <DT><CODE>
! 741: <A NAME="bgp-path-metric"></A> path metric <I>switch</I></CODE><DD><P>Enable comparison of path lengths when deciding which BGP route is the
! 742: best one. Default: on.
! 743: <P>
! 744: <DT><CODE>
! 745: <A NAME="bgp-med-metric"></A> med metric <I>switch</I></CODE><DD><P>Enable comparison of MED attributes (during best route selection) even
! 746: between routes received from different ASes. This may be useful if all
! 747: MED attributes contain some consistent metric, perhaps enforced in
! 748: import filters of AS boundary routers. If this option is disabled, MED
! 749: attributes are compared only if routes are received from the same AS
! 750: (which is the standard behavior). Default: off.
! 751: <P>
! 752: <DT><CODE>
! 753: <A NAME="bgp-deterministic-med"></A> deterministic med <I>switch</I></CODE><DD><P>BGP route selection algorithm is often viewed as a comparison between
! 754: individual routes (e.g. if a new route appears and is better than the
! 755: current best one, it is chosen as the new best one). But the proper
! 756: route selection, as specified by <A HREF="http://www.rfc-editor.org/info/rfc4271">RFC 4271</A>, cannot be fully
! 757: implemented in that way. The problem is mainly in handling the MED
! 758: attribute. BIRD, by default, uses an simplification based on individual
! 759: route comparison, which in some cases may lead to temporally dependent
! 760: behavior (i.e. the selection is dependent on the order in which routes
! 761: appeared). This option enables a different (and slower) algorithm
! 762: implementing proper <A HREF="http://www.rfc-editor.org/info/rfc4271">RFC 4271</A> route selection, which is
! 763: deterministic. Alternative way how to get deterministic behavior is to
! 764: use <CODE>med metric</CODE> option. This option is incompatible with
! 765: <A HREF="bird-2.html#dsc-table-sorted">sorted tables</A>. Default: off.
! 766: <P>
! 767: <DT><CODE>
! 768: <A NAME="bgp-igp-metric"></A> igp metric <I>switch</I></CODE><DD><P>Enable comparison of internal distances to boundary routers during best
! 769: route selection. Default: on.
! 770: <P>
! 771: <DT><CODE>
! 772: <A NAME="bgp-prefer-older"></A> prefer older <I>switch</I></CODE><DD><P>Standard route selection algorithm breaks ties by comparing router IDs.
! 773: This changes the behavior to prefer older routes (when both are external
! 774: and from different peer). For details, see <A HREF="http://www.rfc-editor.org/info/rfc5004">RFC 5004</A>. Default: off.
! 775: <P>
! 776: <DT><CODE>
! 777: <A NAME="bgp-default-med"></A> default bgp_med <I>number</I></CODE><DD><P>Value of the Multiple Exit Discriminator to be used during route
! 778: selection when the MED attribute is missing. Default: 0.
! 779: <P>
! 780: <DT><CODE>
! 781: <A NAME="bgp-default-local-pref"></A> default bgp_local_pref <I>number</I></CODE><DD><P>A default value for the Local Preference attribute. It is used when
! 782: a new Local Preference attribute is attached to a route by the BGP
! 783: protocol itself (for example, if a route is received through eBGP and
! 784: therefore does not have such attribute). Default: 100 (0 in pre-1.2.0
! 785: versions of BIRD).
! 786: </DL>
! 787: <P>
! 788: <H3><A NAME="bgp-attr"></A> Attributes</H3>
! 789:
! 790: <P>BGP defines several route attributes. Some of them (those marked with
! 791: `<CODE>I</CODE>' in the table below) are available on internal BGP connections only,
! 792: some of them (marked with `<CODE>O</CODE>') are optional.
! 793: <P>
! 794: <DL>
! 795: <DT><CODE>
! 796: <A NAME="rta-bgp-path"></A> bgppath bgp_path/</CODE><DD><P>Sequence of AS numbers describing the AS path the packet will travel
! 797: through when forwarded according to the particular route. In case of
! 798: internal BGP it doesn't contain the number of the local AS.
! 799: <P>
! 800: <DT><CODE>
! 801: <A NAME="rta-bgp-local-pref"></A> int bgp_local_pref/ [I]</CODE><DD><P>Local preference value used for selection among multiple BGP routes (see
! 802: the selection rules above). It's used as an additional metric which is
! 803: propagated through the whole local AS.
! 804: <P>
! 805: <DT><CODE>
! 806: <A NAME="rta-bgp-med"></A> int bgp_med/ [O]</CODE><DD><P>The Multiple Exit Discriminator of the route is an optional attribute
! 807: which is used on external (inter-AS) links to convey to an adjacent AS
! 808: the optimal entry point into the local AS. The received attribute is
! 809: also propagated over internal BGP links. The attribute value is zeroed
! 810: when a route is exported to an external BGP instance to ensure that the
! 811: attribute received from a neighboring AS is not propagated to other
! 812: neighboring ASes. A new value might be set in the export filter of an
! 813: external BGP instance. See <A HREF="http://www.rfc-editor.org/info/rfc4451">RFC 4451</A> for further discussion of
! 814: BGP MED attribute.
! 815: <P>
! 816: <DT><CODE>
! 817: <A NAME="rta-bgp-origin"></A> enum bgp_origin/</CODE><DD><P>Origin of the route: either <CODE>ORIGIN_IGP</CODE> if the route has originated
! 818: in an interior routing protocol or <CODE>ORIGIN_EGP</CODE> if it's been imported
! 819: from the <CODE>EGP</CODE> protocol (nowadays it seems to be obsolete) or
! 820: <CODE>ORIGIN_INCOMPLETE</CODE> if the origin is unknown.
! 821: <P>
! 822: <DT><CODE>
! 823: <A NAME="rta-bgp-next-hop"></A> ip bgp_next_hop/</CODE><DD><P>Next hop to be used for forwarding of packets to this destination. On
! 824: internal BGP connections, it's an address of the originating router if
! 825: it's inside the local AS or a boundary router the packet will leave the
! 826: AS through if it's an exterior route, so each BGP speaker within the AS
! 827: has a chance to use the shortest interior path possible to this point.
! 828: <P>
! 829: <DT><CODE>
! 830: <A NAME="rta-bgp-atomic-aggr"></A> void bgp_atomic_aggr/ [O]</CODE><DD><P>This is an optional attribute which carries no value, but the sole
! 831: presence of which indicates that the route has been aggregated from
! 832: multiple routes by some router on the path from the originator.
! 833: <P>
! 834: <DT><CODE>
! 835: <A NAME="rta-bgp-community"></A> clist bgp_community/ [O]</CODE><DD><P>List of community values associated with the route. Each such value is a
! 836: pair (represented as a <CODE>pair</CODE> data type inside the filters) of 16-bit
! 837: integers, the first of them containing the number of the AS which
! 838: defines the community and the second one being a per-AS identifier.
! 839: There are lots of uses of the community mechanism, but generally they
! 840: are used to carry policy information like "don't export to USA peers".
! 841: As each AS can define its own routing policy, it also has a complete
! 842: freedom about which community attributes it defines and what will their
! 843: semantics be.
! 844: <P>
! 845: <DT><CODE>
! 846: <A NAME="rta-bgp-ext-community"></A> eclist bgp_ext_community/ [O]</CODE><DD><P>List of extended community values associated with the route. Extended
! 847: communities have similar usage as plain communities, but they have an
! 848: extended range (to allow 4B ASNs) and a nontrivial structure with a type
! 849: field. Individual community values are represented using an <CODE>ec</CODE> data
! 850: type inside the filters.
! 851: <P>
! 852: <DT><CODE>
! 853: <A NAME="rta-bgp-large-community"></A> lclist <CODE>bgp_large_community</CODE> [O]</CODE><DD><P>List of large community values associated with the route. Large BGP
! 854: communities is another variant of communities, but contrary to extended
! 855: communities they behave very much the same way as regular communities,
! 856: just larger -- they are uniform untyped triplets of 32bit numbers.
! 857: Individual community values are represented using an <CODE>lc</CODE> data type
! 858: inside the filters.
! 859: <P>
! 860: <DT><CODE>
! 861: <A NAME="rta-bgp-originator-id"></A> quad bgp_originator_id/ [I, O]</CODE><DD><P>This attribute is created by the route reflector when reflecting the
! 862: route and contains the router ID of the originator of the route in the
! 863: local AS.
! 864: <P>
! 865: <DT><CODE>
! 866: <A NAME="rta-bgp-cluster-list"></A> clist bgp_cluster_list/ [I, O]</CODE><DD><P>This attribute contains a list of cluster IDs of route reflectors. Each
! 867: route reflector prepends its cluster ID when reflecting the route.
! 868: </DL>
! 869: <P>
! 870: <H3><A NAME="bgp-exam"></A> Example</H3>
! 871:
! 872: <P>
! 873: <HR>
! 874: <PRE>
! 875: protocol bgp {
! 876: local as 65000; # Use a private AS number
! 877: neighbor 198.51.100.130 as 64496; # Our neighbor ...
! 878: multihop; # ... which is connected indirectly
! 879: export filter { # We use non-trivial export rules
! 880: if source = RTS_STATIC then { # Export only static routes
! 881: # Assign our community
! 882: bgp_community.add((65000,64501));
! 883: # Artificially increase path length
! 884: # by advertising local AS number twice
! 885: if bgp_path ~ [= 65000 =] then
! 886: bgp_path.prepend(65000);
! 887: accept;
! 888: }
! 889: reject;
! 890: };
! 891: import all;
! 892: source address 198.51.100.14; # Use a non-standard source address
! 893: }
! 894: </PRE>
! 895: <HR>
! 896: <P>
! 897: <P>
! 898: <H2><A NAME="device"></A> <A NAME="ss6.4">6.4</A> <A HREF="bird.html#toc6.4">Device</A>
! 899: </H2>
! 900:
! 901: <P>The Device protocol is not a real routing protocol. It doesn't generate any
! 902: routes and it only serves as a module for getting information about network
! 903: interfaces from the kernel.
! 904: <P>
! 905: <P>Except for very unusual circumstances, you probably should include this
! 906: protocol in the configuration since almost all other protocols require network
! 907: interfaces to be defined for them to work with.
! 908: <P>
! 909: <H3><A NAME="device-config"></A> Configuration</H3>
! 910:
! 911: <P>
! 912: <DL>
! 913: <P>
! 914: <DT><CODE>
! 915: <A NAME="device-scan-time"></A> scan time <I>number</I></CODE><DD><P>Time in seconds between two scans of the network interface list. On
! 916: systems where we are notified about interface status changes
! 917: asynchronously (such as newer versions of Linux), we need to scan the
! 918: list only in order to avoid confusion by lost notification messages,
! 919: so the default time is set to a large value.
! 920: <P>
! 921: <DT><CODE>
! 922: <A NAME="device-primary"></A> primary [ "<I>mask</I>" ] <I>prefix</I></CODE><DD><P>If a network interface has more than one network address, BIRD has to
! 923: choose one of them as a primary one. By default, BIRD chooses the
! 924: lexicographically smallest address as the primary one.
! 925: <P>This option allows to specify which network address should be chosen as
! 926: a primary one. Network addresses that match <I>prefix</I> are preferred to
! 927: non-matching addresses. If more <CODE>primary</CODE> options are used, the first
! 928: one has the highest preference. If "<I>mask</I>" is specified, then such
! 929: <CODE>primary</CODE> option is relevant only to matching network interfaces.
! 930: <P>In all cases, an address marked by operating system as secondary cannot
! 931: be chosen as the primary one.
! 932: </DL>
! 933: <P>
! 934: <P>As the Device protocol doesn't generate any routes, it cannot have
! 935: any attributes. Example configuration looks like this:
! 936: <P>
! 937: <P>
! 938: <HR>
! 939: <PRE>
! 940: protocol device {
! 941: scan time 10; # Scan the interfaces often
! 942: primary "eth0" 192.168.1.1;
! 943: primary 192.168.0.0/16;
! 944: }
! 945: </PRE>
! 946: <HR>
! 947: <P>
! 948: <P>
! 949: <H2><A NAME="direct"></A> <A NAME="ss6.5">6.5</A> <A HREF="bird.html#toc6.5">Direct</A>
! 950: </H2>
! 951:
! 952: <P>The Direct protocol is a simple generator of device routes for all the
! 953: directly connected networks according to the list of interfaces provided by the
! 954: kernel via the Device protocol.
! 955: <P>
! 956: <P>The question is whether it is a good idea to have such device routes in BIRD
! 957: routing table. OS kernel usually handles device routes for directly connected
! 958: networks by itself so we don't need (and don't want) to export these routes to
! 959: the kernel protocol. OSPF protocol creates device routes for its interfaces
! 960: itself and BGP protocol is usually used for exporting aggregate routes. Although
! 961: there are some use cases that use the direct protocol (like abusing eBGP as an
! 962: IGP routing protocol), in most cases it is not needed to have these device
! 963: routes in BIRD routing table and to use the direct protocol.
! 964: <P>
! 965: <P>There is one notable case when you definitely want to use the direct protocol
! 966: -- running BIRD on BSD systems. Having high priority device routes for directly
! 967: connected networks from the direct protocol protects kernel device routes from
! 968: being overwritten or removed by IGP routes during some transient network
! 969: conditions, because a lower priority IGP route for the same network is not
! 970: exported to the kernel routing table. This is an issue on BSD systems only, as
! 971: on Linux systems BIRD cannot change non-BIRD route in the kernel routing table.
! 972: <P>
! 973: <P>There are just few configuration options for the Direct protocol:
! 974: <P>
! 975: <P>
! 976: <DL>
! 977: <DT><CODE>
! 978: <A NAME="direct-iface"></A> interface <I>pattern</I> [, <I>...</I>]</CODE><DD><P>By default, the Direct protocol will generate device routes for all the
! 979: interfaces available. If you want to restrict it to some subset of
! 980: interfaces or addresses (e.g. if you're using multiple routing tables
! 981: for policy routing and some of the policy domains don't contain all
! 982: interfaces), just use this clause. See
! 983: <A HREF="bird-3.html#proto-iface">interface</A>
! 984: common option for detailed description. The Direct protocol uses
! 985: extended interface clauses.
! 986: <P>
! 987: <DT><CODE>
! 988: <A NAME="direct-check-link"></A> check link <I>switch</I></CODE><DD><P>If enabled, a hardware link state (reported by OS) is taken into
! 989: consideration. Routes for directly connected networks are generated only
! 990: if link up is reported and they are withdrawn when link disappears
! 991: (e.g., an ethernet cable is unplugged). Default value is no.
! 992: </DL>
! 993: <P>
! 994: <P>Direct device routes don't contain any specific attributes.
! 995: <P>
! 996: <P>Example config might look like this:
! 997: <P>
! 998: <P>
! 999: <HR>
! 1000: <PRE>
! 1001: protocol direct {
! 1002: interface "-arc*", "*"; # Exclude the ARCnets
! 1003: }
! 1004: </PRE>
! 1005: <HR>
! 1006: <P>
! 1007: <P>
! 1008: <H2><A NAME="krt"></A> <A NAME="ss6.6">6.6</A> <A HREF="bird.html#toc6.6">Kernel</A>
! 1009: </H2>
! 1010:
! 1011: <P>The Kernel protocol is not a real routing protocol. Instead of communicating
! 1012: with other routers in the network, it performs synchronization of BIRD's routing
! 1013: tables with the OS kernel. Basically, it sends all routing table updates to the
! 1014: kernel and from time to time it scans the kernel tables to see whether some
! 1015: routes have disappeared (for example due to unnoticed up/down transition of an
! 1016: interface) or whether an `alien' route has been added by someone else (depending
! 1017: on the <CODE>learn</CODE> switch, such routes are either ignored or accepted to our
! 1018: table).
! 1019: <P>
! 1020: <P>Unfortunately, there is one thing that makes the routing table synchronization
! 1021: a bit more complicated. In the kernel routing table there are also device routes
! 1022: for directly connected networks. These routes are usually managed by OS itself
! 1023: (as a part of IP address configuration) and we don't want to touch that. They
! 1024: are completely ignored during the scan of the kernel tables and also the export
! 1025: of device routes from BIRD tables to kernel routing tables is restricted to
! 1026: prevent accidental interference. This restriction can be disabled using
! 1027: <CODE>device routes</CODE> switch.
! 1028: <P>
! 1029: <P>If your OS supports only a single routing table, you can configure only one
! 1030: instance of the Kernel protocol. If it supports multiple tables (in order to
! 1031: allow policy routing; such an OS is for example Linux), you can run as many
! 1032: instances as you want, but each of them must be connected to a different BIRD
! 1033: routing table and to a different kernel table.
! 1034: <P>
! 1035: <P>Because the kernel protocol is partially integrated with the connected
! 1036: routing table, there are two limitations - it is not possible to connect more
! 1037: kernel protocols to the same routing table and changing route destination
! 1038: (gateway) in an export filter of a kernel protocol does not work. Both
! 1039: limitations can be overcome using another routing table and the pipe protocol.
! 1040: <P>
! 1041: <H3><A NAME="krt-config"></A> Configuration</H3>
! 1042:
! 1043: <P>
! 1044: <DL>
! 1045: <DT><CODE>
! 1046: <A NAME="krt-persist"></A> persist <I>switch</I></CODE><DD><P>Tell BIRD to leave all its routes in the routing tables when it exits
! 1047: (instead of cleaning them up).
! 1048: <P>
! 1049: <DT><CODE>
! 1050: <A NAME="krt-scan-time"></A> scan time <I>number</I></CODE><DD><P>Time in seconds between two consecutive scans of the kernel routing
! 1051: table.
! 1052: <P>
! 1053: <DT><CODE>
! 1054: <A NAME="krt-learn"></A> learn <I>switch</I></CODE><DD><P>Enable learning of routes added to the kernel routing tables by other
! 1055: routing daemons or by the system administrator. This is possible only on
! 1056: systems which support identification of route authorship.
! 1057: <P>
! 1058: <DT><CODE>
! 1059: <A NAME="krt-device-routes"></A> device routes <I>switch</I></CODE><DD><P>Enable export of device routes to the kernel routing table. By default,
! 1060: such routes are rejected (with the exception of explicitly configured
! 1061: device routes from the static protocol) regardless of the export filter
! 1062: to protect device routes in kernel routing table (managed by OS itself)
! 1063: from accidental overwriting or erasing.
! 1064: <P>
! 1065: <DT><CODE>
! 1066: <A NAME="krt-kernel-table"></A> kernel table <I>number</I></CODE><DD><P>Select which kernel table should this particular instance of the Kernel
! 1067: protocol work with. Available only on systems supporting multiple
! 1068: routing tables.
! 1069: <P>
! 1070: <DT><CODE>
! 1071: <A NAME="krt-metric"></A> metric <I>number</I></CODE><DD><P>(Linux)
! 1072: Use specified value as a kernel metric (priority) for all routes sent to
! 1073: the kernel. When multiple routes for the same network are in the kernel
! 1074: routing table, the Linux kernel chooses one with lower metric. Also,
! 1075: routes with different metrics do not clash with each other, therefore
! 1076: using dedicated metric value is a reliable way to avoid overwriting
! 1077: routes from other sources (e.g. kernel device routes). Metric 0 has a
! 1078: special meaning of undefined metric, in which either OS default is used,
! 1079: or per-route metric can be set using <CODE>krt_metric</CODE> attribute. Default:
! 1080: 0 (undefined).
! 1081: <P>
! 1082: <DT><CODE>
! 1083: <A NAME="krt-graceful-restart"></A> graceful restart <I>switch</I></CODE><DD><P>Participate in graceful restart recovery. If this option is enabled and
! 1084: a graceful restart recovery is active, the Kernel protocol will defer
! 1085: synchronization of routing tables until the end of the recovery. Note
! 1086: that import of kernel routes to BIRD is not affected.
! 1087: <P>
! 1088: <DT><CODE>
! 1089: <A NAME="krt-merge-paths"></A> merge paths <I>switch</I> [limit <I>number</I>]</CODE><DD><P>Usually, only best routes are exported to the kernel protocol. With path
! 1090: merging enabled, both best routes and equivalent non-best routes are
! 1091: merged during export to generate one ECMP (equal-cost multipath) route
! 1092: for each network. This is useful e.g. for BGP multipath. Note that best
! 1093: routes are still pivotal for route export (responsible for most
! 1094: properties of resulting ECMP routes), while exported non-best routes are
! 1095: responsible just for additional multipath next hops. This option also
! 1096: allows to specify a limit on maximal number of nexthops in one route. By
! 1097: default, multipath merging is disabled. If enabled, default value of the
! 1098: limit is 16.
! 1099: </DL>
! 1100: <P>
! 1101: <H3><A NAME="krt-attr"></A> Attributes</H3>
! 1102:
! 1103: <P>The Kernel protocol defines several attributes. These attributes are
! 1104: translated to appropriate system (and OS-specific) route attributes. We support
! 1105: these attributes:
! 1106: <P>
! 1107: <DL>
! 1108: <DT><CODE>
! 1109: <A NAME="rta-krt-source"></A> int krt_source/</CODE><DD><P>The original source of the imported kernel route. The value is
! 1110: system-dependent. On Linux, it is a value of the protocol field of the
! 1111: route. See /etc/iproute2/rt_protos for common values. On BSD, it is
! 1112: based on STATIC and PROTOx flags. The attribute is read-only.
! 1113: <P>
! 1114: <DT><CODE>
! 1115: <A NAME="rta-krt-metric"></A> int krt_metric/</CODE><DD><P>(Linux)
! 1116: The kernel metric of the route. When multiple same routes are in a
! 1117: kernel routing table, the Linux kernel chooses one with lower metric.
! 1118: Note that preferred way to set kernel metric is to use protocol option
! 1119: <CODE>metric</CODE>, unless per-route metric values are needed.
! 1120: <P>
! 1121: <DT><CODE>
! 1122: <A NAME="rta-krt-prefsrc"></A> ip krt_prefsrc/</CODE><DD><P>(Linux)
! 1123: The preferred source address. Used in source address selection for
! 1124: outgoing packets. Has to be one of the IP addresses of the router.
! 1125: <P>
! 1126: <DT><CODE>
! 1127: <A NAME="rta-krt-realm"></A> int krt_realm/</CODE><DD><P>(Linux)
! 1128: The realm of the route. Can be used for traffic classification.
! 1129: <P>
! 1130: <DT><CODE>
! 1131: <A NAME="rta-krt-scope"></A> int krt_scope/</CODE><DD><P>(Linux IPv4)
! 1132: The scope of the route. Valid values are 0-254, although Linux kernel
! 1133: may reject some values depending on route type and nexthop. It is
! 1134: supposed to represent `indirectness' of the route, where nexthops of
! 1135: routes are resolved through routes with a higher scope, but in current
! 1136: kernels anything below <I>link</I> (253) is treated as <I>global</I> (0).
! 1137: When not present, global scope is implied for all routes except device
! 1138: routes, where link scope is used by default.
! 1139: </DL>
! 1140: <P>
! 1141: <P>In Linux, there is also a plenty of obscure route attributes mostly focused
! 1142: on tuning TCP performance of local connections. BIRD supports most of these
! 1143: attributes, see Linux or iproute2 documentation for their meaning. Attributes
! 1144: <CODE>krt_lock_*</CODE> and <CODE>krt_feature_*</CODE> have type bool, others have type int.
! 1145: Supported attributes are:
! 1146: <P><CODE>krt_mtu</CODE>, <CODE>krt_lock_mtu</CODE>, <CODE>krt_window</CODE>, <CODE>krt_lock_window</CODE>,
! 1147: <CODE>krt_rtt</CODE>, <CODE>krt_lock_rtt</CODE>, <CODE>krt_rttvar</CODE>, <CODE>krt_lock_rttvar</CODE>,
! 1148: <CODE>krt_sstresh</CODE>, <CODE>krt_lock_sstresh</CODE>, <CODE>krt_cwnd</CODE>, <CODE>krt_lock_cwnd</CODE>,
! 1149: <CODE>krt_advmss</CODE>, <CODE>krt_lock_advmss</CODE>, <CODE>krt_reordering</CODE>, <CODE>krt_lock_reordering</CODE>,
! 1150: <CODE>krt_hoplimit</CODE>, <CODE>krt_lock_hoplimit</CODE>, <CODE>krt_rto_min</CODE>, <CODE>krt_lock_rto_min</CODE>,
! 1151: <CODE>krt_initcwnd</CODE>, <CODE>krt_initrwnd</CODE>, <CODE>krt_quickack</CODE>,
! 1152: <CODE>krt_feature_ecn</CODE>, <CODE>krt_feature_allfrag</CODE>
! 1153: <P>
! 1154: <H3><A NAME="krt-exam"></A> Example</H3>
! 1155:
! 1156: <P>A simple configuration can look this way:
! 1157: <P>
! 1158: <P>
! 1159: <HR>
! 1160: <PRE>
! 1161: protocol kernel {
! 1162: export all;
! 1163: }
! 1164: </PRE>
! 1165: <HR>
! 1166: <P>
! 1167: <P>Or for a system with two routing tables:
! 1168: <P>
! 1169: <P>
! 1170: <HR>
! 1171: <PRE>
! 1172: protocol kernel { # Primary routing table
! 1173: learn; # Learn alien routes from the kernel
! 1174: persist; # Don't remove routes on bird shutdown
! 1175: scan time 10; # Scan kernel routing table every 10 seconds
! 1176: import all;
! 1177: export all;
! 1178: }
! 1179:
! 1180: protocol kernel { # Secondary routing table
! 1181: table auxtable;
! 1182: kernel table 100;
! 1183: export all;
! 1184: }
! 1185: </PRE>
! 1186: <HR>
! 1187: <P>
! 1188: <P>
! 1189: <H2><A NAME="ospf"></A> <A NAME="ss6.7">6.7</A> <A HREF="bird.html#toc6.7">OSPF</A>
! 1190: </H2>
! 1191:
! 1192: <H3><A NAME="ospf-intro"></A> Introduction</H3>
! 1193:
! 1194: <P>Open Shortest Path First (OSPF) is a quite complex interior gateway
! 1195: protocol. The current IPv4 version (OSPFv2) is defined in <A HREF="http://www.rfc-editor.org/info/rfc2328">RFC 2328</A> and
! 1196: the current IPv6 version (OSPFv3) is defined in <A HREF="http://www.rfc-editor.org/info/rfc5340">RFC 5340</A> It's a link
! 1197: state (a.k.a. shortest path first) protocol -- each router maintains a database
! 1198: describing the autonomous system's topology. Each participating router has an
! 1199: identical copy of the database and all routers run the same algorithm
! 1200: calculating a shortest path tree with themselves as a root. OSPF chooses the
! 1201: least cost path as the best path.
! 1202: <P>
! 1203: <P>In OSPF, the autonomous system can be split to several areas in order to
! 1204: reduce the amount of resources consumed for exchanging the routing information
! 1205: and to protect the other areas from incorrect routing data. Topology of the area
! 1206: is hidden to the rest of the autonomous system.
! 1207: <P>
! 1208: <P>Another very important feature of OSPF is that it can keep routing information
! 1209: from other protocols (like Static or BGP) in its link state database as external
! 1210: routes. Each external route can be tagged by the advertising router, making it
! 1211: possible to pass additional information between routers on the boundary of the
! 1212: autonomous system.
! 1213: <P>
! 1214: <P>OSPF quickly detects topological changes in the autonomous system (such as
! 1215: router interface failures) and calculates new loop-free routes after a short
! 1216: period of convergence. Only a minimal amount of routing traffic is involved.
! 1217: <P>
! 1218: <P>Each router participating in OSPF routing periodically sends Hello messages
! 1219: to all its interfaces. This allows neighbors to be discovered dynamically. Then
! 1220: the neighbors exchange theirs parts of the link state database and keep it
! 1221: identical by flooding updates. The flooding process is reliable and ensures that
! 1222: each router detects all changes.
! 1223: <P>
! 1224: <H3><A NAME="ospf-config"></A> Configuration</H3>
! 1225:
! 1226: <P>In the main part of configuration, there can be multiple definitions of OSPF
! 1227: areas, each with a different id. These definitions includes many other switches
! 1228: and multiple definitions of interfaces. Definition of interface may contain many
! 1229: switches and constant definitions and list of neighbors on nonbroadcast
! 1230: networks.
! 1231: <P>
! 1232: <HR>
! 1233: <PRE>
! 1234: protocol ospf <name> {
! 1235: rfc1583compat <switch>;
! 1236: instance id <num>;
! 1237: stub router <switch>;
! 1238: tick <num>;
! 1239: ecmp <switch> [limit <num>];
! 1240: merge external <switch>;
! 1241: area <id> {
! 1242: stub;
! 1243: nssa;
! 1244: summary <switch>;
! 1245: default nssa <switch>;
! 1246: default cost <num>;
! 1247: default cost2 <num>;
! 1248: translator <switch>;
! 1249: translator stability <num>;
! 1250:
! 1251: networks {
! 1252: <prefix>;
! 1253: <prefix> hidden;
! 1254: }
! 1255: external {
! 1256: <prefix>;
! 1257: <prefix> hidden;
! 1258: <prefix> tag <num>;
! 1259: }
! 1260: stubnet <prefix>;
! 1261: stubnet <prefix> {
! 1262: hidden <switch>;
! 1263: summary <switch>;
! 1264: cost <num>;
! 1265: }
! 1266: interface <interface pattern> [instance <num>] {
! 1267: cost <num>;
! 1268: stub <switch>;
! 1269: hello <num>;
! 1270: poll <num>;
! 1271: retransmit <num>;
! 1272: priority <num>;
! 1273: wait <num>;
! 1274: dead count <num>;
! 1275: dead <num>;
! 1276: secondary <switch>;
! 1277: rx buffer [normal|large|<num>];
! 1278: tx length <num>;
! 1279: type [broadcast|bcast|pointopoint|ptp|
! 1280: nonbroadcast|nbma|pointomultipoint|ptmp];
! 1281: link lsa suppression <switch>;
! 1282: strict nonbroadcast <switch>;
! 1283: real broadcast <switch>;
! 1284: ptp netmask <switch>;
! 1285: check link <switch>;
! 1286: bfd <switch>;
! 1287: ecmp weight <num>;
! 1288: ttl security [<switch>; | tx only]
! 1289: tx class|dscp <num>;
! 1290: tx priority <num>;
! 1291: authentication none|simple|cryptographic;
! 1292: password "<text>";
! 1293: password "<text>" {
! 1294: id <num>;
! 1295: generate from "<date>";
! 1296: generate to "<date>";
! 1297: accept from "<date>";
! 1298: accept to "<date>";
! 1299: from "<date>";
! 1300: to "<date>";
! 1301: algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 );
! 1302: };
! 1303: neighbors {
! 1304: <ip>;
! 1305: <ip> eligible;
! 1306: };
! 1307: };
! 1308: virtual link <id> [instance <num>] {
! 1309: hello <num>;
! 1310: retransmit <num>;
! 1311: wait <num>;
! 1312: dead count <num>;
! 1313: dead <num>;
! 1314: authentication none|simple|cryptographic;
! 1315: password "<text>";
! 1316: password "<text>" {
! 1317: id <num>;
! 1318: generate from "<date>";
! 1319: generate to "<date>";
! 1320: accept from "<date>";
! 1321: accept to "<date>";
! 1322: from "<date>";
! 1323: to "<date>";
! 1324: algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 );
! 1325: };
! 1326: };
! 1327: };
! 1328: }
! 1329: </PRE>
! 1330: <HR>
! 1331: <P>
! 1332: <DL>
! 1333: <DT><CODE>
! 1334: <A NAME="ospf-rfc1583compat"></A> rfc1583compat <I>switch</I></CODE><DD><P>This option controls compatibility of routing table calculation with
! 1335: <A HREF="http://www.rfc-editor.org/info/rfc1583">RFC 1583</A>. Default value is no.
! 1336: <P>
! 1337: <DT><CODE>
! 1338: <A NAME="ospf-instance-id"></A> instance id <I>num</I></CODE><DD><P>When multiple OSPF protocol instances are active on the same links, they
! 1339: should use different instance IDs to distinguish their packets. Although
! 1340: it could be done on per-interface basis, it is often preferred to set
! 1341: one instance ID to whole OSPF domain/topology (e.g., when multiple
! 1342: instances are used to represent separate logical topologies on the same
! 1343: physical network). This option specifies the default instance ID for all
! 1344: interfaces of the OSPF instance. Note that this option, if used, must
! 1345: precede interface definitions. Default value is 0.
! 1346: <P>
! 1347: <DT><CODE>
! 1348: <A NAME="ospf-stub-router"></A> stub router <I>switch</I></CODE><DD><P>This option configures the router to be a stub router, i.e., a router
! 1349: that participates in the OSPF topology but does not allow transit
! 1350: traffic. In OSPFv2, this is implemented by advertising maximum metric
! 1351: for outgoing links. In OSPFv3, the stub router behavior is announced by
! 1352: clearing the R-bit in the router LSA. See <A HREF="http://www.rfc-editor.org/info/rfc6987">RFC 6987</A> for details.
! 1353: Default value is no.
! 1354: <P>
! 1355: <DT><CODE>
! 1356: <A NAME="ospf-tick"></A> tick <I>num</I></CODE><DD><P>The routing table calculation and clean-up of areas' databases is not
! 1357: performed when a single link state change arrives. To lower the CPU
! 1358: utilization, it's processed later at periodical intervals of <I>num</I>
! 1359: seconds. The default value is 1.
! 1360: <P>
! 1361: <DT><CODE>
! 1362: <A NAME="ospf-ecmp"></A> ecmp <I>switch</I> [limit <I>number</I>]</CODE><DD><P>This option specifies whether OSPF is allowed to generate ECMP
! 1363: (equal-cost multipath) routes. Such routes are used when there are
! 1364: several directions to the destination, each with the same (computed)
! 1365: cost. This option also allows to specify a limit on maximum number of
! 1366: nexthops in one route. By default, ECMP is disabled. If enabled,
! 1367: default value of the limit is 16.
! 1368: <P>
! 1369: <DT><CODE>
! 1370: <A NAME="ospf-merge-external"></A> merge external <I>switch</I></CODE><DD><P>This option specifies whether OSPF should merge external routes from
! 1371: different routers/LSAs for the same destination. When enabled together
! 1372: with <CODE>ecmp</CODE>, equal-cost external routes will be combined to multipath
! 1373: routes in the same way as regular routes. When disabled, external routes
! 1374: from different LSAs are treated as separate even if they represents the
! 1375: same destination. Default value is no.
! 1376: <P>
! 1377: <DT><CODE>
! 1378: <A NAME="ospf-area"></A> area <I>id</I></CODE><DD><P>This defines an OSPF area with given area ID (an integer or an IPv4
! 1379: address, similarly to a router ID). The most important area is the
! 1380: backbone (ID 0) to which every other area must be connected.
! 1381: <P>
! 1382: <DT><CODE>
! 1383: <A NAME="ospf-stub"></A> stub</CODE><DD><P>This option configures the area to be a stub area. External routes are
! 1384: not flooded into stub areas. Also summary LSAs can be limited in stub
! 1385: areas (see option <CODE>summary</CODE>). By default, the area is not a stub
! 1386: area.
! 1387: <P>
! 1388: <DT><CODE>
! 1389: <A NAME="ospf-nssa"></A> nssa</CODE><DD><P>This option configures the area to be a NSSA (Not-So-Stubby Area). NSSA
! 1390: is a variant of a stub area which allows a limited way of external route
! 1391: propagation. Global external routes are not propagated into a NSSA, but
! 1392: an external route can be imported into NSSA as a (area-wide) NSSA-LSA
! 1393: (and possibly translated and/or aggregated on area boundary). By
! 1394: default, the area is not NSSA.
! 1395: <P>
! 1396: <DT><CODE>
! 1397: <A NAME="ospf-summary"></A> summary <I>switch</I></CODE><DD><P>This option controls propagation of summary LSAs into stub or NSSA
! 1398: areas. If enabled, summary LSAs are propagated as usual, otherwise just
! 1399: the default summary route (0.0.0.0/0) is propagated (this is sometimes
! 1400: called totally stubby area). If a stub area has more area boundary
! 1401: routers, propagating summary LSAs could lead to more efficient routing
! 1402: at the cost of larger link state database. Default value is no.
! 1403: <P>
! 1404: <DT><CODE>
! 1405: <A NAME="ospf-default-nssa"></A> default nssa <I>switch</I></CODE><DD><P>When <CODE>summary</CODE> option is enabled, default summary route is no longer
! 1406: propagated to the NSSA. In that case, this option allows to originate
! 1407: default route as NSSA-LSA to the NSSA. Default value is no.
! 1408: <P>
! 1409: <DT><CODE>
! 1410: <A NAME="ospf-default-cost"></A> default cost <I>num</I></CODE><DD><P>This option controls the cost of a default route propagated to stub and
! 1411: NSSA areas. Default value is 1000.
! 1412: <P>
! 1413: <DT><CODE>
! 1414: <A NAME="ospf-default-cost2"></A> default cost2 <I>num</I></CODE><DD><P>When a default route is originated as NSSA-LSA, its cost can use either
! 1415: type 1 or type 2 metric. This option allows to specify the cost of a
! 1416: default route in type 2 metric. By default, type 1 metric (option
! 1417: <CODE>default cost</CODE>) is used.
! 1418: <P>
! 1419: <DT><CODE>
! 1420: <A NAME="ospf-translator"></A> translator <I>switch</I></CODE><DD><P>This option controls translation of NSSA-LSAs into external LSAs. By
! 1421: default, one translator per NSSA is automatically elected from area
! 1422: boundary routers. If enabled, this area boundary router would
! 1423: unconditionally translate all NSSA-LSAs regardless of translator
! 1424: election. Default value is no.
! 1425: <P>
! 1426: <DT><CODE>
! 1427: <A NAME="ospf-translator-stability"></A> translator stability <I>num</I></CODE><DD><P>This option controls the translator stability interval (in seconds).
! 1428: When the new translator is elected, the old one keeps translating until
! 1429: the interval is over. Default value is 40.
! 1430: <P>
! 1431: <DT><CODE>
! 1432: <A NAME="ospf-networks"></A> networks { <I>set</I> }</CODE><DD><P>Definition of area IP ranges. This is used in summary LSA origination.
! 1433: Hidden networks are not propagated into other areas.
! 1434: <P>
! 1435: <DT><CODE>
! 1436: <A NAME="ospf-external"></A> external { <I>set</I> }</CODE><DD><P>Definition of external area IP ranges for NSSAs. This is used for
! 1437: NSSA-LSA translation. Hidden networks are not translated into external
! 1438: LSAs. Networks can have configured route tag.
! 1439: <P>
! 1440: <DT><CODE>
! 1441: <A NAME="ospf-stubnet"></A> stubnet <I>prefix</I> { <I>options</I> }</CODE><DD><P>Stub networks are networks that are not transit networks between OSPF
! 1442: routers. They are also propagated through an OSPF area as a part of a
! 1443: link state database. By default, BIRD generates a stub network record
! 1444: for each primary network address on each OSPF interface that does not
! 1445: have any OSPF neighbors, and also for each non-primary network address
! 1446: on each OSPF interface. This option allows to alter a set of stub
! 1447: networks propagated by this router.
! 1448: <P>Each instance of this option adds a stub network with given network
! 1449: prefix to the set of propagated stub network, unless option <CODE>hidden</CODE>
! 1450: is used. It also suppresses default stub networks for given network
! 1451: prefix. When option <CODE>summary</CODE> is used, also default stub networks
! 1452: that are subnetworks of given stub network are suppressed. This might be
! 1453: used, for example, to aggregate generated stub networks.
! 1454: <P>
! 1455: <DT><CODE>
! 1456: <A NAME="ospf-iface"></A> interface <I>pattern</I> [instance <I>num</I>]</CODE><DD><P>Defines that the specified interfaces belong to the area being defined.
! 1457: See
! 1458: <A HREF="bird-3.html#proto-iface">interface</A> common option for detailed
! 1459: description. In OSPFv2, extended interface clauses are used, because
! 1460: each network prefix is handled as a separate virtual interface.
! 1461: <P>You can specify alternative instance ID for the interface definition,
! 1462: therefore it is possible to have several instances of that interface
! 1463: with different options or even in different areas. For OSPFv2, instance
! 1464: ID support is an extension (<A HREF="http://www.rfc-editor.org/info/rfc6549">RFC 6549</A>) and is supposed to be set
! 1465: per-protocol. For OSPFv3, it is an integral feature.
! 1466: <P>
! 1467: <DT><CODE>
! 1468: <A NAME="ospf-virtual-link"></A> virtual link <I>id</I> [instance <I>num</I>]</CODE><DD><P>Virtual link to router with the router id. Virtual link acts as a
! 1469: point-to-point interface belonging to backbone. The actual area is used
! 1470: as a transport area. This item cannot be in the backbone. Like with
! 1471: <CODE>interface</CODE> option, you could also use several virtual links to one
! 1472: destination with different instance IDs.
! 1473: <P>
! 1474: <DT><CODE>
! 1475: <A NAME="ospf-cost"></A> cost <I>num</I></CODE><DD><P>Specifies output cost (metric) of an interface. Default value is 10.
! 1476: <P>
! 1477: <DT><CODE>
! 1478: <A NAME="ospf-stub-iface"></A> stub <I>switch</I></CODE><DD><P>If set to interface it does not listen to any packet and does not send
! 1479: any hello. Default value is no.
! 1480: <P>
! 1481: <DT><CODE>
! 1482: <A NAME="ospf-hello"></A> hello <I>num</I></CODE><DD><P>Specifies interval in seconds between sending of Hello messages. Beware,
! 1483: all routers on the same network need to have the same hello interval.
! 1484: Default value is 10.
! 1485: <P>
! 1486: <DT><CODE>
! 1487: <A NAME="ospf-poll"></A> poll <I>num</I></CODE><DD><P>Specifies interval in seconds between sending of Hello messages for some
! 1488: neighbors on NBMA network. Default value is 20.
! 1489: <P>
! 1490: <DT><CODE>
! 1491: <A NAME="ospf-retransmit"></A> retransmit <I>num</I></CODE><DD><P>Specifies interval in seconds between retransmissions of unacknowledged
! 1492: updates. Default value is 5.
! 1493: <P>
! 1494: <DT><CODE>
! 1495: <A NAME="ospf-priority"></A> priority <I>num</I></CODE><DD><P>On every multiple access network (e.g., the Ethernet) Designated Router
! 1496: and Backup Designated router are elected. These routers have some special
! 1497: functions in the flooding process. Higher priority increases preferences
! 1498: in this election. Routers with priority 0 are not eligible. Default
! 1499: value is 1.
! 1500: <P>
! 1501: <DT><CODE>
! 1502: <A NAME="ospf-wait"></A> wait <I>num</I></CODE><DD><P>After start, router waits for the specified number of seconds between
! 1503: starting election and building adjacency. Default value is 4*<I>hello</I>.
! 1504: <P>
! 1505: <DT><CODE>
! 1506: <A NAME="ospf-dead-count"></A> dead count <I>num</I></CODE><DD><P>When the router does not receive any messages from a neighbor in
! 1507: <I>dead count</I>*<I>hello</I> seconds, it will consider the neighbor down.
! 1508: <P>
! 1509: <DT><CODE>
! 1510: <A NAME="ospf-dead"></A> dead <I>num</I></CODE><DD><P>When the router does not receive any messages from a neighbor in
! 1511: <I>dead</I> seconds, it will consider the neighbor down. If both directives
! 1512: <CODE>dead count</CODE> and <CODE>dead</CODE> are used, <CODE>dead</CODE> has precedence.
! 1513: <P>
! 1514: <DT><CODE>
! 1515: <A NAME="ospf-secondary"></A> secondary <I>switch</I></CODE><DD><P>On BSD systems, older versions of BIRD supported OSPFv2 only for the
! 1516: primary IP address of an interface, other IP ranges on the interface
! 1517: were handled as stub networks. Since v1.4.1, regular operation on
! 1518: secondary IP addresses is supported, but disabled by default for
! 1519: compatibility. This option allows to enable it. The option is a
! 1520: transitional measure, will be removed in the next major release as the
! 1521: behavior will be changed. On Linux systems, the option is irrelevant, as
! 1522: operation on non-primary addresses is already the regular behavior.
! 1523: <P>
! 1524: <DT><CODE>
! 1525: <A NAME="ospf-rx-buffer"></A> rx buffer <I>num</I></CODE><DD><P>This option allows to specify the size of buffers used for packet
! 1526: processing. The buffer size should be bigger than maximal size of any
! 1527: packets. By default, buffers are dynamically resized as needed, but a
! 1528: fixed value could be specified. Value <CODE>large</CODE> means maximal allowed
! 1529: packet size - 65535.
! 1530: <P>
! 1531: <DT><CODE>
! 1532: <A NAME="ospf-tx-length"></A> tx length <I>num</I></CODE><DD><P>Transmitted OSPF messages that contain large amount of information are
! 1533: segmented to separate OSPF packets to avoid IP fragmentation. This
! 1534: option specifies the soft ceiling for the length of generated OSPF
! 1535: packets. Default value is the MTU of the network interface. Note that
! 1536: larger OSPF packets may still be generated if underlying OSPF messages
! 1537: cannot be splitted (e.g. when one large LSA is propagated).
! 1538: <P>
! 1539: <DT><CODE>
! 1540: <A NAME="ospf-type-bcast"></A> type broadcast|bcast</CODE><DD><P>BIRD detects a type of a connected network automatically, but sometimes
! 1541: it's convenient to force use of a different type manually. On broadcast
! 1542: networks (like ethernet), flooding and Hello messages are sent using
! 1543: multicasts (a single packet for all the neighbors). A designated router
! 1544: is elected and it is responsible for synchronizing the link-state
! 1545: databases and originating network LSAs. This network type cannot be used
! 1546: on physically NBMA networks and on unnumbered networks (networks without
! 1547: proper IP prefix).
! 1548: <P>
! 1549: <DT><CODE>
! 1550: <A NAME="ospf-type-ptp"></A> type pointopoint|ptp</CODE><DD><P>Point-to-point networks connect just 2 routers together. No election is
! 1551: performed and no network LSA is originated, which makes it simpler and
! 1552: faster to establish. This network type is useful not only for physically
! 1553: PtP ifaces (like PPP or tunnels), but also for broadcast networks used
! 1554: as PtP links. This network type cannot be used on physically NBMA
! 1555: networks.
! 1556: <P>
! 1557: <DT><CODE>
! 1558: <A NAME="ospf-type-nbma"></A> type nonbroadcast|nbma</CODE><DD><P>On NBMA networks, the packets are sent to each neighbor separately
! 1559: because of lack of multicast capabilities. Like on broadcast networks,
! 1560: a designated router is elected, which plays a central role in propagation
! 1561: of LSAs. This network type cannot be used on unnumbered networks.
! 1562: <P>
! 1563: <DT><CODE>
! 1564: <A NAME="ospf-type-ptmp"></A> type pointomultipoint|ptmp</CODE><DD><P>This is another network type designed to handle NBMA networks. In this
! 1565: case the NBMA network is treated as a collection of PtP links. This is
! 1566: useful if not every pair of routers on the NBMA network has direct
! 1567: communication, or if the NBMA network is used as an (possibly
! 1568: unnumbered) PtP link.
! 1569: <P>
! 1570: <DT><CODE>
! 1571: <A NAME="ospf-link-lsa-suppression"></A> link lsa suppression <I>switch</I></CODE><DD><P>In OSPFv3, link LSAs are generated for each link, announcing link-local
! 1572: IPv6 address of the router to its local neighbors. These are useless on
! 1573: PtP or PtMP networks and this option allows to suppress the link LSA
! 1574: origination for such interfaces. The option is ignored on other than PtP
! 1575: or PtMP interfaces. Default value is no.
! 1576: <P>
! 1577: <DT><CODE>
! 1578: <A NAME="ospf-strict-nonbroadcast"></A> strict nonbroadcast <I>switch</I></CODE><DD><P>If set, don't send hello to any undefined neighbor. This switch is
! 1579: ignored on other than NBMA or PtMP interfaces. Default value is no.
! 1580: <P>
! 1581: <DT><CODE>
! 1582: <A NAME="ospf-real-broadcast"></A> real broadcast <I>switch</I></CODE><DD><P>In <CODE>type broadcast</CODE> or <CODE>type ptp</CODE> network configuration, OSPF
! 1583: packets are sent as IP multicast packets. This option changes the
! 1584: behavior to using old-fashioned IP broadcast packets. This may be useful
! 1585: as a workaround if IP multicast for some reason does not work or does
! 1586: not work reliably. This is a non-standard option and probably is not
! 1587: interoperable with other OSPF implementations. Default value is no.
! 1588: <P>
! 1589: <DT><CODE>
! 1590: <A NAME="ospf-ptp-netmask"></A> ptp netmask <I>switch</I></CODE><DD><P>In <CODE>type ptp</CODE> network configurations, OSPFv2 implementations should
! 1591: ignore received netmask field in hello packets and should send hello
! 1592: packets with zero netmask field on unnumbered PtP links. But some OSPFv2
! 1593: implementations perform netmask checking even for PtP links. This option
! 1594: specifies whether real netmask will be used in hello packets on <CODE>type
! 1595: ptp</CODE> interfaces. You should ignore this option unless you meet some
! 1596: compatibility problems related to this issue. Default value is no for
! 1597: unnumbered PtP links, yes otherwise.
! 1598: <P>
! 1599: <DT><CODE>
! 1600: <A NAME="ospf-check-link"></A> check link <I>switch</I></CODE><DD><P>If set, a hardware link state (reported by OS) is taken into consideration.
! 1601: When a link disappears (e.g. an ethernet cable is unplugged), neighbors
! 1602: are immediately considered unreachable and only the address of the iface
! 1603: (instead of whole network prefix) is propagated. It is possible that
! 1604: some hardware drivers or platforms do not implement this feature.
! 1605: Default value is no.
! 1606: <P>
! 1607: <DT><CODE>
! 1608: <A NAME="ospf-bfd"></A> bfd <I>switch</I></CODE><DD><P>OSPF could use BFD protocol as an advisory mechanism for neighbor
! 1609: liveness and failure detection. If enabled, BIRD setups a BFD session
! 1610: for each OSPF neighbor and tracks its liveness by it. This has an
! 1611: advantage of an order of magnitude lower detection times in case of
! 1612: failure. Note that BFD protocol also has to be configured, see
! 1613: <A HREF="#bfd">BFD</A> section for details. Default value is no.
! 1614: <P>
! 1615: <DT><CODE>
! 1616: <A NAME="ospf-ttl-security"></A> ttl security [<I>switch</I> | tx only]</CODE><DD><P>TTL security is a feature that protects routing protocols from remote
! 1617: spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
! 1618: destined to neighbors. Because TTL is decremented when packets are
! 1619: forwarded, it is non-trivial to spoof packets with TTL 255 from remote
! 1620: locations. Note that this option would interfere with OSPF virtual
! 1621: links.
! 1622: <P>If this option is enabled, the router will send OSPF packets with TTL
! 1623: 255 and drop received packets with TTL less than 255. If this option si
! 1624: set to <CODE>tx only</CODE>, TTL 255 is used for sent packets, but is not
! 1625: checked for received packets. Default value is no.
! 1626: <P>
! 1627: <DT><CODE>
! 1628: <A NAME="ospf-tx-class"></A> tx class|dscp|priority <I>num</I></CODE><DD><P>These options specify the ToS/DiffServ/Traffic class/Priority of the
! 1629: outgoing OSPF packets. See
! 1630: <A HREF="bird-3.html#proto-tx-class">tx class</A> common
! 1631: option for detailed description.
! 1632: <P>
! 1633: <DT><CODE>
! 1634: <A NAME="ospf-ecmp-weight"></A> ecmp weight <I>num</I></CODE><DD><P>When ECMP (multipath) routes are allowed, this value specifies a
! 1635: relative weight used for nexthops going through the iface. Allowed
! 1636: values are 1-256. Default value is 1.
! 1637: <P>
! 1638: <DT><CODE>
! 1639: <A NAME="ospf-auth-none"></A> authentication none</CODE><DD><P>No passwords are sent in OSPF packets. This is the default value.
! 1640: <P>
! 1641: <DT><CODE>
! 1642: <A NAME="ospf-auth-simple"></A> authentication simple</CODE><DD><P>Every packet carries 8 bytes of password. Received packets lacking this
! 1643: password are ignored. This authentication mechanism is very weak.
! 1644: This option is not available in OSPFv3.
! 1645: <P>
! 1646: <DT><CODE>
! 1647: <A NAME="ospf-auth-cryptographic"></A> authentication cryptographic</CODE><DD><P>An authentication code is appended to every packet. The specific
! 1648: cryptographic algorithm is selected by option <CODE>algorithm</CODE> for each
! 1649: key. The default cryptographic algorithm for OSPFv2 keys is Keyed-MD5
! 1650: and for OSPFv3 keys is HMAC-SHA-256. Passwords are not sent open via
! 1651: network, so this mechanism is quite secure. Packets can still be read by
! 1652: an attacker.
! 1653: <P>
! 1654: <DT><CODE>
! 1655: <A NAME="ospf-pass"></A> password "<I>text</I>"</CODE><DD><P>Specifies a password used for authentication. See
! 1656: <A HREF="bird-3.html#proto-pass">password</A> common option for detailed
! 1657: description.
! 1658: <P>
! 1659: <DT><CODE>
! 1660: <A NAME="ospf-neighbors"></A> neighbors { <I>set</I> } </CODE><DD><P>A set of neighbors to which Hello messages on NBMA or PtMP networks are
! 1661: to be sent. For NBMA networks, some of them could be marked as eligible.
! 1662: In OSPFv3, link-local addresses should be used, using global ones is
! 1663: possible, but it is nonstandard and might be problematic. And definitely,
! 1664: link-local and global addresses should not be mixed.
! 1665: </DL>
! 1666: <P>
! 1667: <H3><A NAME="ospf-attr"></A> Attributes</H3>
! 1668:
! 1669: <P>OSPF defines four route attributes. Each internal route has a <CODE>metric</CODE>.
! 1670: <P>
! 1671: <P>Metric is ranging from 1 to infinity (65535). External routes use
! 1672: <CODE>metric type 1</CODE> or <CODE>metric type 2</CODE>. A <CODE>metric of type 1</CODE> is comparable
! 1673: with internal <CODE>metric</CODE>, a <CODE>metric of type 2</CODE> is always longer than any
! 1674: <CODE>metric of type 1</CODE> or any <CODE>internal metric</CODE>. <CODE>Internal metric</CODE> or
! 1675: <CODE>metric of type 1</CODE> is stored in attribute <CODE>ospf_metric1</CODE>, <CODE>metric type
! 1676: 2</CODE> is stored in attribute <CODE>ospf_metric2</CODE>. If you specify both metrics only
! 1677: metric1 is used.
! 1678: <P>
! 1679: <P>Each external route can also carry attribute <CODE>ospf_tag</CODE> which is a 32-bit
! 1680: integer which is used when exporting routes to other protocols; otherwise, it
! 1681: doesn't affect routing inside the OSPF domain at all. The fourth attribute
! 1682: <CODE>ospf_router_id</CODE> is a router ID of the router advertising that route /
! 1683: network. This attribute is read-only. Default is <CODE>ospf_metric2 = 10000</CODE> and
! 1684: <CODE>ospf_tag = 0</CODE>.
! 1685: <P>
! 1686: <H3><A NAME="ospf-exam"></A> Example</H3>
! 1687:
! 1688: <P>
! 1689: <HR>
! 1690: <PRE>
! 1691: protocol ospf MyOSPF {
! 1692: rfc1583compat yes;
! 1693: tick 2;
! 1694: export filter {
! 1695: if source = RTS_BGP then {
! 1696: ospf_metric1 = 100;
! 1697: accept;
! 1698: }
! 1699: reject;
! 1700: };
! 1701: area 0.0.0.0 {
! 1702: interface "eth*" {
! 1703: cost 11;
! 1704: hello 15;
! 1705: priority 100;
! 1706: retransmit 7;
! 1707: authentication simple;
! 1708: password "aaa";
! 1709: };
! 1710: interface "ppp*" {
! 1711: cost 100;
! 1712: authentication cryptographic;
! 1713: password "abc" {
! 1714: id 1;
! 1715: generate to "22-04-2003 11:00:06";
! 1716: accept from "17-01-2001 12:01:05";
! 1717: algorithm hmac sha384;
! 1718: };
! 1719: password "def" {
! 1720: id 2;
! 1721: generate to "22-07-2005 17:03:21";
! 1722: accept from "22-02-2001 11:34:06";
! 1723: algorithm hmac sha512;
! 1724: };
! 1725: };
! 1726: interface "arc0" {
! 1727: cost 10;
! 1728: stub yes;
! 1729: };
! 1730: interface "arc1";
! 1731: };
! 1732: area 120 {
! 1733: stub yes;
! 1734: networks {
! 1735: 172.16.1.0/24;
! 1736: 172.16.2.0/24 hidden;
! 1737: }
! 1738: interface "-arc0" , "arc*" {
! 1739: type nonbroadcast;
! 1740: authentication none;
! 1741: strict nonbroadcast yes;
! 1742: wait 120;
! 1743: poll 40;
! 1744: dead count 8;
! 1745: neighbors {
! 1746: 192.168.120.1 eligible;
! 1747: 192.168.120.2;
! 1748: 192.168.120.10;
! 1749: };
! 1750: };
! 1751: };
! 1752: }
! 1753: </PRE>
! 1754: <HR>
! 1755: <P>
! 1756: <P>
! 1757: <H2><A NAME="pipe"></A> <A NAME="ss6.8">6.8</A> <A HREF="bird.html#toc6.8">Pipe</A>
! 1758: </H2>
! 1759:
! 1760: <H3><A NAME="pipe-intro"></A> Introduction</H3>
! 1761:
! 1762: <P>The Pipe protocol serves as a link between two routing tables, allowing
! 1763: routes to be passed from a table declared as primary (i.e., the one the pipe is
! 1764: connected to using the <CODE>table</CODE> configuration keyword) to the secondary one
! 1765: (declared using <CODE>peer table</CODE>) and vice versa, depending on what's allowed by
! 1766: the filters. Export filters control export of routes from the primary table to
! 1767: the secondary one, import filters control the opposite direction.
! 1768: <P>
! 1769: <P>The Pipe protocol may work in the transparent mode mode or in the opaque
! 1770: mode. In the transparent mode, the Pipe protocol retransmits all routes from
! 1771: one table to the other table, retaining their original source and attributes.
! 1772: If import and export filters are set to accept, then both tables would have
! 1773: the same content. The transparent mode is the default mode.
! 1774: <P>
! 1775: <P>In the opaque mode, the Pipe protocol retransmits optimal route from one
! 1776: table to the other table in a similar way like other protocols send and receive
! 1777: routes. Retransmitted route will have the source set to the Pipe protocol, which
! 1778: may limit access to protocol specific route attributes. This mode is mainly for
! 1779: compatibility, it is not suggested for new configs. The mode can be changed by
! 1780: <CODE>mode</CODE> option.
! 1781: <P>
! 1782: <P>The primary use of multiple routing tables and the Pipe protocol is for
! 1783: policy routing, where handling of a single packet doesn't depend only on its
! 1784: destination address, but also on its source address, source interface, protocol
! 1785: type and other similar parameters. In many systems (Linux being a good example),
! 1786: the kernel allows to enforce routing policies by defining routing rules which
! 1787: choose one of several routing tables to be used for a packet according to its
! 1788: parameters. Setting of these rules is outside the scope of BIRD's work (on
! 1789: Linux, you can use the <CODE>ip</CODE> command), but you can create several routing
! 1790: tables in BIRD, connect them to the kernel ones, use filters to control which
! 1791: routes appear in which tables and also you can employ the Pipe protocol for
! 1792: exporting a selected subset of one table to another one.
! 1793: <P>
! 1794: <H3><A NAME="pipe-config"></A> Configuration</H3>
! 1795:
! 1796: <P>
! 1797: <DL>
! 1798: <DT><CODE>
! 1799: <A NAME="pipe-peer-table"></A> peer table <I>table</I></CODE><DD><P>Defines secondary routing table to connect to. The primary one is
! 1800: selected by the <CODE>table</CODE> keyword.
! 1801: <P>
! 1802: <DT><CODE>
! 1803: <A NAME="pipe-mode"></A> mode opaque|transparent</CODE><DD><P>Specifies the mode for the pipe to work in. Default is transparent.
! 1804: </DL>
! 1805: <P>
! 1806: <H3><A NAME="pipe-attr"></A> Attributes</H3>
! 1807:
! 1808: <P>The Pipe protocol doesn't define any route attributes.
! 1809: <P>
! 1810: <H3><A NAME="pipe-exam"></A> Example</H3>
! 1811:
! 1812: <P>Let's consider a router which serves as a boundary router of two different
! 1813: autonomous systems, each of them connected to a subset of interfaces of the
! 1814: router, having its own exterior connectivity and wishing to use the other AS as
! 1815: a backup connectivity in case of outage of its own exterior line.
! 1816: <P>
! 1817: <P>Probably the simplest solution to this situation is to use two routing tables
! 1818: (we'll call them <CODE>as1</CODE> and <CODE>as2</CODE>) and set up kernel routing rules, so that
! 1819: packets having arrived from interfaces belonging to the first AS will be routed
! 1820: according to <CODE>as1</CODE> and similarly for the second AS. Thus we have split our
! 1821: router to two logical routers, each one acting on its own routing table, having
! 1822: its own routing protocols on its own interfaces. In order to use the other AS's
! 1823: routes for backup purposes, we can pass the routes between the tables through a
! 1824: Pipe protocol while decreasing their preferences and correcting their BGP paths
! 1825: to reflect the AS boundary crossing.
! 1826: <P>
! 1827: <HR>
! 1828: <PRE>
! 1829: table as1; # Define the tables
! 1830: table as2;
! 1831:
! 1832: protocol kernel kern1 { # Synchronize them with the kernel
! 1833: table as1;
! 1834: kernel table 1;
! 1835: }
! 1836:
! 1837: protocol kernel kern2 {
! 1838: table as2;
! 1839: kernel table 2;
! 1840: }
! 1841:
! 1842: protocol bgp bgp1 { # The outside connections
! 1843: table as1;
! 1844: local as 1;
! 1845: neighbor 192.168.0.1 as 1001;
! 1846: export all;
! 1847: import all;
! 1848: }
! 1849:
! 1850: protocol bgp bgp2 {
! 1851: table as2;
! 1852: local as 2;
! 1853: neighbor 10.0.0.1 as 1002;
! 1854: export all;
! 1855: import all;
! 1856: }
! 1857:
! 1858: protocol pipe { # The Pipe
! 1859: table as1;
! 1860: peer table as2;
! 1861: export filter {
! 1862: if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks
! 1863: if preference>10 then preference = preference-10;
! 1864: if source=RTS_BGP then bgp_path.prepend(1);
! 1865: accept;
! 1866: }
! 1867: reject;
! 1868: };
! 1869: import filter {
! 1870: if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks
! 1871: if preference>10 then preference = preference-10;
! 1872: if source=RTS_BGP then bgp_path.prepend(2);
! 1873: accept;
! 1874: }
! 1875: reject;
! 1876: };
! 1877: }
! 1878: </PRE>
! 1879: <HR>
! 1880: <P>
! 1881: <P>
! 1882: <H2><A NAME="radv"></A> <A NAME="ss6.9">6.9</A> <A HREF="bird.html#toc6.9">RAdv</A>
! 1883: </H2>
! 1884:
! 1885: <H3><A NAME="radv-intro"></A> Introduction</H3>
! 1886:
! 1887: <P>The RAdv protocol is an implementation of Router Advertisements, which are
! 1888: used in the IPv6 stateless autoconfiguration. IPv6 routers send (in irregular
! 1889: time intervals or as an answer to a request) advertisement packets to connected
! 1890: networks. These packets contain basic information about a local network (e.g. a
! 1891: list of network prefixes), which allows network hosts to autoconfigure network
! 1892: addresses and choose a default route. BIRD implements router behavior as defined
! 1893: in <A HREF="http://www.rfc-editor.org/info/rfc4861">RFC 4861</A> and also the DNS extensions from <A HREF="http://www.rfc-editor.org/info/rfc6106">RFC 6106</A>.
! 1894: <P>
! 1895: <H3><A NAME="radv-config"></A> Configuration</H3>
! 1896:
! 1897: <P>There are several classes of definitions in RAdv configuration -- interface
! 1898: definitions, prefix definitions and DNS definitions:
! 1899: <P>
! 1900: <DL>
! 1901: <DT><CODE>
! 1902: <A NAME="radv-iface"></A> interface <I>pattern</I> [, <I>...</I>] { <I>options</I> }</CODE><DD><P>Interface definitions specify a set of interfaces on which the
! 1903: protocol is activated and contain interface specific options.
! 1904: See
! 1905: <A HREF="bird-3.html#proto-iface">interface</A> common options for
! 1906: detailed description.
! 1907: <P>
! 1908: <DT><CODE>
! 1909: <A NAME="radv-prefix"></A> prefix <I>prefix</I> { <I>options</I> }</CODE><DD><P>Prefix definitions allow to modify a list of advertised prefixes. By
! 1910: default, the advertised prefixes are the same as the network prefixes
! 1911: assigned to the interface. For each network prefix, the matching prefix
! 1912: definition is found and its options are used. If no matching prefix
! 1913: definition is found, the prefix is used with default options.
! 1914: <P>Prefix definitions can be either global or interface-specific. The
! 1915: second ones are part of interface options. The prefix definition
! 1916: matching is done in the first-match style, when interface-specific
! 1917: definitions are processed before global definitions. As expected, the
! 1918: prefix definition is matching if the network prefix is a subnet of the
! 1919: prefix in prefix definition.
! 1920: <P>
! 1921: <DT><CODE>
! 1922: <A NAME="radv-rdnss"></A> rdnss { <I>options</I> }</CODE><DD><P>RDNSS definitions allow to specify a list of advertised recursive DNS
! 1923: servers together with their options. As options are seldom necessary,
! 1924: there is also a short variant <CODE>rdnss <I>address</I></CODE> that just
! 1925: specifies one DNS server. Multiple definitions are cumulative. RDNSS
! 1926: definitions may also be interface-specific when used inside interface
! 1927: options. By default, interface uses both global and interface-specific
! 1928: options, but that can be changed by <CODE>rdnss local</CODE> option.
! 1929: dsc-iface
! 1930: <DT><CODE>
! 1931: <A NAME="radv-dnssl"></A> dnssl { <I>options</I> }</CODE><DD><P>DNSSL definitions allow to specify a list of advertised DNS search
! 1932: domains together with their options. Like <CODE>rdnss</CODE> above, multiple
! 1933: definitions are cumulative, they can be used also as interface-specific
! 1934: options and there is a short variant <CODE>dnssl <I>domain</I></CODE> that just
! 1935: specifies one DNS search domain.
! 1936: <P>
! 1937: <DT><CODE>
! 1938: <A NAME="radv-trigger"></A> trigger <I>prefix</I></CODE><DD><P>RAdv protocol could be configured to change its behavior based on
! 1939: availability of routes. When this option is used, the protocol waits in
! 1940: suppressed state until a <I>trigger route</I> (for the specified network)
! 1941: is exported to the protocol, the protocol also returnsd to suppressed
! 1942: state if the <I>trigger route</I> disappears. Note that route export
! 1943: depends on specified export filter, as usual. This option could be used,
! 1944: e.g., for handling failover in multihoming scenarios.
! 1945: <P>During suppressed state, router advertisements are generated, but with
! 1946: some fields zeroed. Exact behavior depends on which fields are zeroed,
! 1947: this can be configured by <CODE>sensitive</CODE> option for appropriate
! 1948: fields. By default, just <CODE>default lifetime</CODE> (also called <CODE>router
! 1949: lifetime</CODE>) is zeroed, which means hosts cannot use the router as a
! 1950: default router. <CODE>preferred lifetime</CODE> and <CODE>valid lifetime</CODE> could
! 1951: also be configured as <CODE>sensitive</CODE> for a prefix, which would cause
! 1952: autoconfigured IPs to be deprecated or even removed.
! 1953: </DL>
! 1954: <P>
! 1955: <P>Interface specific options:
! 1956: <P>
! 1957: <DL>
! 1958: <DT><CODE>
! 1959: <A NAME="radv-iface-max-ra-interval"></A> max ra interval <I>expr</I></CODE><DD><P>Unsolicited router advertisements are sent in irregular time intervals.
! 1960: This option specifies the maximum length of these intervals, in seconds.
! 1961: Valid values are 4-1800. Default: 600
! 1962: <P>
! 1963: <DT><CODE>
! 1964: <A NAME="radv-iface-min-ra-interval"></A> min ra interval <I>expr</I></CODE><DD><P>This option specifies the minimum length of that intervals, in seconds.
! 1965: Must be at least 3 and at most 3/4 * <CODE>max ra interval</CODE>. Default:
! 1966: about 1/3 * <CODE>max ra interval</CODE>.
! 1967: <P>
! 1968: <DT><CODE>
! 1969: <A NAME="radv-iface-min-delay"></A> min delay <I>expr</I></CODE><DD><P>The minimum delay between two consecutive router advertisements, in
! 1970: seconds. Default: 3
! 1971: <P>
! 1972: <DT><CODE>
! 1973: <A NAME="radv-iface-managed"></A> managed <I>switch</I></CODE><DD><P>This option specifies whether hosts should use DHCPv6 for IP address
! 1974: configuration. Default: no
! 1975: <P>
! 1976: <DT><CODE>
! 1977: <A NAME="radv-iface-other-config"></A> other config <I>switch</I></CODE><DD><P>This option specifies whether hosts should use DHCPv6 to receive other
! 1978: configuration information. Default: no
! 1979: <P>
! 1980: <DT><CODE>
! 1981: <A NAME="radv-iface-link-mtu"></A> link mtu <I>expr</I></CODE><DD><P>This option specifies which value of MTU should be used by hosts. 0
! 1982: means unspecified. Default: 0
! 1983: <P>
! 1984: <DT><CODE>
! 1985: <A NAME="radv-iface-reachable-time"></A> reachable time <I>expr</I></CODE><DD><P>This option specifies the time (in milliseconds) how long hosts should
! 1986: assume a neighbor is reachable (from the last confirmation). Maximum is
! 1987: 3600000, 0 means unspecified. Default 0.
! 1988: <P>
! 1989: <DT><CODE>
! 1990: <A NAME="radv-iface-retrans-timer"></A> retrans timer <I>expr</I></CODE><DD><P>This option specifies the time (in milliseconds) how long hosts should
! 1991: wait before retransmitting Neighbor Solicitation messages. 0 means
! 1992: unspecified. Default 0.
! 1993: <P>
! 1994: <DT><CODE>
! 1995: <A NAME="radv-iface-current-hop-limit"></A> current hop limit <I>expr</I></CODE><DD><P>This option specifies which value of Hop Limit should be used by
! 1996: hosts. Valid values are 0-255, 0 means unspecified. Default: 64
! 1997: <P>
! 1998: <DT><CODE>
! 1999: <A NAME="radv-iface-default-lifetime"></A> default lifetime <I>expr</I> [sensitive <I>switch</I>]</CODE><DD><P>This option specifies the time (in seconds) how long (after the receipt
! 2000: of RA) hosts may use the router as a default router. 0 means do not use
! 2001: as a default router. For <CODE>sensitive</CODE> option, see
! 2002: <A HREF="#radv-trigger">trigger</A>.
! 2003: Default: 3 * <CODE>max ra interval</CODE>, <CODE>sensitive</CODE> yes.
! 2004: <P>
! 2005: <DT><CODE>
! 2006: <A NAME="radv-iface-default-preference-low"></A> default preference low|medium|high</CODE><DD><P>This option specifies the Default Router Preference value to advertise
! 2007: to hosts. Default: medium.
! 2008: <P>
! 2009: <DT><CODE>
! 2010: <A NAME="radv-iface-rdnss-local"></A> rdnss local <I>switch</I></CODE><DD><P>Use only local (interface-specific) RDNSS definitions for this
! 2011: interface. Otherwise, both global and local definitions are used. Could
! 2012: also be used to disable RDNSS for given interface if no local definitons
! 2013: are specified. Default: no.
! 2014: <P>
! 2015: <DT><CODE>
! 2016: <A NAME="radv-iface-dnssl-local"></A> dnssl local <I>switch</I></CODE><DD><P>Use only local DNSSL definitions for this interface. See <CODE>rdnss local</CODE>
! 2017: option above. Default: no.
! 2018: </DL>
! 2019: <P>
! 2020: <P>
! 2021: <P>Prefix specific options
! 2022: <P>
! 2023: <DL>
! 2024: <DT><CODE>
! 2025: <A NAME="radv-prefix-skip"></A> skip <I>switch</I></CODE><DD><P>This option allows to specify that given prefix should not be
! 2026: advertised. This is useful for making exceptions from a default policy
! 2027: of advertising all prefixes. Note that for withdrawing an already
! 2028: advertised prefix it is more useful to advertise it with zero valid
! 2029: lifetime. Default: no
! 2030: <P>
! 2031: <DT><CODE>
! 2032: <A NAME="radv-prefix-onlink"></A> onlink <I>switch</I></CODE><DD><P>This option specifies whether hosts may use the advertised prefix for
! 2033: onlink determination. Default: yes
! 2034: <P>
! 2035: <DT><CODE>
! 2036: <A NAME="radv-prefix-autonomous"></A> autonomous <I>switch</I></CODE><DD><P>This option specifies whether hosts may use the advertised prefix for
! 2037: stateless autoconfiguration. Default: yes
! 2038: <P>
! 2039: <DT><CODE>
! 2040: <A NAME="radv-prefix-valid-lifetime"></A> valid lifetime <I>expr</I> [sensitive <I>switch</I>]</CODE><DD><P>This option specifies the time (in seconds) how long (after the
! 2041: receipt of RA) the prefix information is valid, i.e., autoconfigured
! 2042: IP addresses can be assigned and hosts with that IP addresses are
! 2043: considered directly reachable. 0 means the prefix is no longer
! 2044: valid. For <CODE>sensitive</CODE> option, see
! 2045: <A HREF="#radv-trigger">trigger</A>.
! 2046: Default: 86400 (1 day), <CODE>sensitive</CODE> no.
! 2047: <P>
! 2048: <DT><CODE>
! 2049: <A NAME="radv-prefix-preferred-lifetime"></A> preferred lifetime <I>expr</I> [sensitive <I>switch</I>]</CODE><DD><P>This option specifies the time (in seconds) how long (after the
! 2050: receipt of RA) IP addresses generated from the prefix using stateless
! 2051: autoconfiguration remain preferred. For <CODE>sensitive</CODE> option,
! 2052: see
! 2053: <A HREF="#radv-trigger">trigger</A>. Default: 14400 (4 hours),
! 2054: <CODE>sensitive</CODE> no.
! 2055: </DL>
! 2056: <P>
! 2057: <P>
! 2058: <P>RDNSS specific options:
! 2059: <P>
! 2060: <DL>
! 2061: <DT><CODE>
! 2062: <A NAME="radv-rdnss-ns"></A> ns <I>address</I></CODE><DD><P>This option specifies one recursive DNS server. Can be used multiple
! 2063: times for multiple servers. It is mandatory to have at least one
! 2064: <CODE>ns</CODE> option in <CODE>rdnss</CODE> definition.
! 2065: <P>
! 2066: <DT><CODE>
! 2067: <A NAME="radv-rdnss-lifetime"></A> lifetime [mult] <I>expr</I></CODE><DD><P>This option specifies the time how long the RDNSS information may be
! 2068: used by clients after the receipt of RA. It is expressed either in
! 2069: seconds or (when <CODE>mult</CODE> is used) in multiples of <CODE>max ra
! 2070: interval</CODE>. Note that RDNSS information is also invalidated when
! 2071: <CODE>default lifetime</CODE> expires. 0 means these addresses are no longer
! 2072: valid DNS servers. Default: 3 * <CODE>max ra interval</CODE>.
! 2073: </DL>
! 2074: <P>
! 2075: <P>
! 2076: <P>DNSSL specific options:
! 2077: <P>
! 2078: <DL>
! 2079: <DT><CODE>
! 2080: <A NAME="radv-dnssl-domain"></A> domain <I>address</I></CODE><DD><P>This option specifies one DNS search domain. Can be used multiple times
! 2081: for multiple domains. It is mandatory to have at least one <CODE>domain</CODE>
! 2082: option in <CODE>dnssl</CODE> definition.
! 2083: <P>
! 2084: <DT><CODE>
! 2085: <A NAME="radv-dnssl-lifetime"></A> lifetime [mult] <I>expr</I></CODE><DD><P>This option specifies the time how long the DNSSL information may be
! 2086: used by clients after the receipt of RA. Details are the same as for
! 2087: RDNSS <CODE>lifetime</CODE> option above. Default: 3 * <CODE>max ra interval</CODE>.
! 2088: </DL>
! 2089: <P>
! 2090: <P>
! 2091: <H3><A NAME="radv-exam"></A> Example</H3>
! 2092:
! 2093: <P>
! 2094: <HR>
! 2095: <PRE>
! 2096: protocol radv {
! 2097: interface "eth2" {
! 2098: max ra interval 5; # Fast failover with more routers
! 2099: managed yes; # Using DHCPv6 on eth2
! 2100: prefix ::/0 {
! 2101: autonomous off; # So do not autoconfigure any IP
! 2102: };
! 2103: };
! 2104:
! 2105: interface "eth*"; # No need for any other options
! 2106:
! 2107: prefix 2001:0DB8:1234::/48 {
! 2108: preferred lifetime 0; # Deprecated address range
! 2109: };
! 2110:
! 2111: prefix 2001:0DB8:2000::/48 {
! 2112: autonomous off; # Do not autoconfigure
! 2113: };
! 2114:
! 2115: rdnss 2001:0DB8:1234::10; # Short form of RDNSS
! 2116:
! 2117: rdnss {
! 2118: lifetime mult 10;
! 2119: ns 2001:0DB8:1234::11;
! 2120: ns 2001:0DB8:1234::12;
! 2121: };
! 2122:
! 2123: dnssl {
! 2124: lifetime 3600;
! 2125: domain "abc.com";
! 2126: domain "xyz.com";
! 2127: };
! 2128: }
! 2129: </PRE>
! 2130: <HR>
! 2131: <P>
! 2132: <P>
! 2133: <H2><A NAME="rip"></A> <A NAME="ss6.10">6.10</A> <A HREF="bird.html#toc6.10">RIP</A>
! 2134: </H2>
! 2135:
! 2136: <H3><A NAME="rip-intro"></A> Introduction</H3>
! 2137:
! 2138: <P>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol,
! 2139: where each router broadcasts (to all its neighbors) distances to all networks it
! 2140: can reach. When a router hears distance to another network, it increments it and
! 2141: broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some
! 2142: network goes unreachable, routers keep telling each other that its distance is
! 2143: the original distance plus 1 (actually, plus interface metric, which is usually
! 2144: one). After some time, the distance reaches infinity (that's 15 in RIP) and all
! 2145: routers know that network is unreachable. RIP tries to minimize situations where
! 2146: counting to infinity is necessary, because it is slow. Due to infinity being 16,
! 2147: you can't use RIP on networks where maximal distance is higher than 15
! 2148: hosts.
! 2149: <P>
! 2150: <P>BIRD supports RIPv1 (<A HREF="http://www.rfc-editor.org/info/rfc1058">RFC 1058</A>), RIPv2 (<A HREF="http://www.rfc-editor.org/info/rfc2453">RFC 2453</A>), RIPng (<A HREF="http://www.rfc-editor.org/info/rfc2080">RFC 2080</A>), and RIP cryptographic authentication (<A HREF="http://www.rfc-editor.org/info/rfc4822">RFC 4822</A>).
! 2151: <P>
! 2152: <P>RIP is a very simple protocol, and it has a lot of shortcomings. Slow
! 2153: convergence, big network load and inability to handle larger networks makes it
! 2154: pretty much obsolete. It is still usable on very small networks.
! 2155: <P>
! 2156: <H3><A NAME="rip-config"></A> Configuration</H3>
! 2157:
! 2158: <P>RIP configuration consists mainly of common protocol options and interface
! 2159: definitions, most RIP options are interface specific.
! 2160: <P>
! 2161: <HR>
! 2162: <PRE>
! 2163: protocol rip [<name>] {
! 2164: infinity <number>;
! 2165: ecmp <switch> [limit <number>];
! 2166: interface <interface pattern> {
! 2167: metric <number>;
! 2168: mode multicast|broadcast;
! 2169: passive <switch>;
! 2170: address <ip>;
! 2171: port <number>;
! 2172: version 1|2;
! 2173: split horizon <switch>;
! 2174: poison reverse <switch>;
! 2175: check zero <switch>;
! 2176: update time <number>;
! 2177: timeout time <number>;
! 2178: garbage time <number>;
! 2179: ecmp weight <number>;
! 2180: ttl security <switch>; | tx only;
! 2181: tx class|dscp <number>;
! 2182: tx priority <number>;
! 2183: rx buffer <number>;
! 2184: tx length <number>;
! 2185: check link <switch>;
! 2186: authentication none|plaintext|cryptographic;
! 2187: password "<text>";
! 2188: password "<text>" {
! 2189: id <num>;
! 2190: generate from "<date>";
! 2191: generate to "<date>";
! 2192: accept from "<date>";
! 2193: accept to "<date>";
! 2194: from "<date>";
! 2195: to "<date>";
! 2196: algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 );
! 2197: };
! 2198: };
! 2199: }
! 2200: </PRE>
! 2201: <HR>
! 2202: <P>
! 2203: <DL>
! 2204: <DT><CODE>
! 2205: <A NAME="rip-infinity"></A> infinity <I>number</I></CODE><DD><P>Selects the distance of infinity. Bigger values will make
! 2206: protocol convergence even slower. The default value is 16.
! 2207: <P>
! 2208: <DT><CODE>
! 2209: <A NAME="rip-ecmp"></A> ecmp <I>switch</I> [limit <I>number</I>]</CODE><DD><P>This option specifies whether RIP is allowed to generate ECMP
! 2210: (equal-cost multipath) routes. Such routes are used when there are
! 2211: several directions to the destination, each with the same (computed)
! 2212: cost. This option also allows to specify a limit on maximum number of
! 2213: nexthops in one route. By default, ECMP is disabled. If enabled,
! 2214: default value of the limit is 16.
! 2215: <P>
! 2216: <DT><CODE>
! 2217: <A NAME="rip-iface"></A> interface <I>pattern</I> [, <I>...</I>] { <I>options</I> }</CODE><DD><P>Interface definitions specify a set of interfaces on which the
! 2218: protocol is activated and contain interface specific options.
! 2219: See
! 2220: <A HREF="bird-3.html#proto-iface">interface</A> common options for
! 2221: detailed description.
! 2222: </DL>
! 2223: <P>
! 2224: <P>Interface specific options:
! 2225: <P>
! 2226: <DL>
! 2227: <DT><CODE>
! 2228: <A NAME="rip-iface-metric"></A> metric <I>num</I></CODE><DD><P>This option specifies the metric of the interface. When a route is
! 2229: received from the interface, its metric is increased by this value
! 2230: before further processing. Valid values are 1-255, but values higher
! 2231: than infinity has no further meaning. Default: 1.
! 2232: <P>
! 2233: <DT><CODE>
! 2234: <A NAME="rip-iface-mode"></A> mode multicast|broadcast</CODE><DD><P>This option selects the mode for RIP to use on the interface. The
! 2235: default is multicast mode for RIPv2 and broadcast mode for RIPv1.
! 2236: RIPng always uses the multicast mode.
! 2237: <P>
! 2238: <DT><CODE>
! 2239: <A NAME="rip-iface-passive"></A> passive <I>switch</I></CODE><DD><P>Passive interfaces receive routing updates but do not transmit any
! 2240: messages. Default: no.
! 2241: <P>
! 2242: <DT><CODE>
! 2243: <A NAME="rip-iface-address"></A> address <I>ip</I></CODE><DD><P>This option specifies a destination address used for multicast or
! 2244: broadcast messages, the default is the official RIP (224.0.0.9) or RIPng
! 2245: (ff02::9) multicast address, or an appropriate broadcast address in the
! 2246: broadcast mode.
! 2247: <P>
! 2248: <DT><CODE>
! 2249: <A NAME="rip-iface-port"></A> port <I>number</I></CODE><DD><P>This option selects an UDP port to operate on, the default is the
! 2250: official RIP (520) or RIPng (521) port.
! 2251: <P>
! 2252: <DT><CODE>
! 2253: <A NAME="rip-iface-version"></A> version 1|2</CODE><DD><P>This option selects the version of RIP used on the interface. For RIPv1,
! 2254: automatic subnet aggregation is not implemented, only classful network
! 2255: routes and host routes are propagated. Note that BIRD allows RIPv1 to be
! 2256: configured with features that are defined for RIPv2 only, like
! 2257: authentication or using multicast sockets. The default is RIPv2 for IPv4
! 2258: RIP, the option is not supported for RIPng, as no further versions are
! 2259: defined.
! 2260: <P>
! 2261: <DT><CODE>
! 2262: <A NAME="rip-iface-version-only"></A> version only <I>switch</I></CODE><DD><P>Regardless of RIP version configured for the interface, BIRD accepts
! 2263: incoming packets of any RIP version. This option restrict accepted
! 2264: packets to the configured version. Default: no.
! 2265: <P>
! 2266: <DT><CODE>
! 2267: <A NAME="rip-iface-split-horizon"></A> split horizon <I>switch</I></CODE><DD><P>Split horizon is a scheme for preventing routing loops. When split
! 2268: horizon is active, routes are not regularly propagated back to the
! 2269: interface from which they were received. They are either not propagated
! 2270: back at all (plain split horizon) or propagated back with an infinity
! 2271: metric (split horizon with poisoned reverse). Therefore, other routers
! 2272: on the interface will not consider the router as a part of an
! 2273: independent path to the destination of the route. Default: yes.
! 2274: <P>
! 2275: <DT><CODE>
! 2276: <A NAME="rip-iface-poison-reverse"></A> poison reverse <I>switch</I></CODE><DD><P>When split horizon is active, this option specifies whether the poisoned
! 2277: reverse variant (propagating routes back with an infinity metric) is
! 2278: used. The poisoned reverse has some advantages in faster convergence,
! 2279: but uses more network traffic. Default: yes.
! 2280: <P>
! 2281: <DT><CODE>
! 2282: <A NAME="rip-iface-check-zero"></A> check zero <I>switch</I></CODE><DD><P>Received RIPv1 packets with non-zero values in reserved fields should
! 2283: be discarded. This option specifies whether the check is performed or
! 2284: such packets are just processed as usual. Default: yes.
! 2285: <P>
! 2286: <DT><CODE>
! 2287: <A NAME="rip-iface-update-time"></A> update time <I>number</I></CODE><DD><P>Specifies the number of seconds between periodic updates. A lower number
! 2288: will mean faster convergence but bigger network load. Default: 30.
! 2289: <P>
! 2290: <DT><CODE>
! 2291: <A NAME="rip-iface-timeout-time"></A> timeout time <I>number</I></CODE><DD><P>Specifies the time interval (in seconds) between the last received route
! 2292: announcement and the route expiration. After that, the network is
! 2293: considered unreachable, but still is propagated with infinity distance.
! 2294: Default: 180.
! 2295: <P>
! 2296: <DT><CODE>
! 2297: <A NAME="rip-iface-garbage-time"></A> garbage time <I>number</I></CODE><DD><P>Specifies the time interval (in seconds) between the route expiration
! 2298: and the removal of the unreachable network entry. The garbage interval,
! 2299: when a route with infinity metric is propagated, is used for both
! 2300: internal (after expiration) and external (after withdrawal) routes.
! 2301: Default: 120.
! 2302: <P>
! 2303: <DT><CODE>
! 2304: <A NAME="rip-iface-ecmp-weight"></A> ecmp weight <I>number</I></CODE><DD><P>When ECMP (multipath) routes are allowed, this value specifies a
! 2305: relative weight used for nexthops going through the iface. Valid
! 2306: values are 1-256. Default value is 1.
! 2307: <P>
! 2308: <DT><CODE>
! 2309: <A NAME="rip-iface-auth"></A> authentication none|plaintext|cryptographic</CODE><DD><P>Selects authentication method to be used. <CODE>none</CODE> means that packets
! 2310: are not authenticated at all, <CODE>plaintext</CODE> means that a plaintext
! 2311: password is embedded into each packet, and <CODE>cryptographic</CODE> means that
! 2312: packets are authenticated using some cryptographic hash function
! 2313: selected by option <CODE>algorithm</CODE> for each key. The default
! 2314: cryptographic algorithm for RIP keys is Keyed-MD5. If you set
! 2315: authentication to not-none, it is a good idea to add <CODE>password</CODE>
! 2316: section. Default: none.
! 2317: <P>
! 2318: <DT><CODE>
! 2319: <A NAME="rip-iface-pass"></A> password "<I>text</I>"</CODE><DD><P>Specifies a password used for authentication. See
! 2320: <A HREF="bird-3.html#proto-pass">password</A> common option for detailed description.
! 2321: <P>
! 2322: <DT><CODE>
! 2323: <A NAME="rip-iface-ttl-security"></A> ttl security [<I>switch</I> | tx only]</CODE><DD><P>TTL security is a feature that protects routing protocols from remote
! 2324: spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
! 2325: destined to neighbors. Because TTL is decremented when packets are
! 2326: forwarded, it is non-trivial to spoof packets with TTL 255 from remote
! 2327: locations.
! 2328: <P>If this option is enabled, the router will send RIP packets with TTL 255
! 2329: and drop received packets with TTL less than 255. If this option si set
! 2330: to <CODE>tx only</CODE>, TTL 255 is used for sent packets, but is not checked
! 2331: for received packets. Such setting does not offer protection, but offers
! 2332: compatibility with neighbors regardless of whether they use ttl
! 2333: security.
! 2334: <P>For RIPng, TTL security is a standard behavior (required by <A HREF="http://www.rfc-editor.org/info/rfc2080">RFC 2080</A>) and therefore default value is yes. For IPv4 RIP, default
! 2335: value is no.
! 2336: <P>
! 2337: <DT><CODE>
! 2338: <A NAME="rip-iface-tx-class"></A> tx class|dscp|priority <I>number</I></CODE><DD><P>These options specify the ToS/DiffServ/Traffic class/Priority of the
! 2339: outgoing RIP packets. See
! 2340: <A HREF="bird-3.html#proto-tx-class">tx class</A> common
! 2341: option for detailed description.
! 2342: <P>
! 2343: <DT><CODE>
! 2344: <A NAME="rip-iface-rx-buffer"></A> rx buffer <I>number</I></CODE><DD><P>This option specifies the size of buffers used for packet processing.
! 2345: The buffer size should be bigger than maximal size of received packets.
! 2346: The default value is 532 for IPv4 RIP and interface MTU value for RIPng.
! 2347: <P>
! 2348: <DT><CODE>
! 2349: <A NAME="rip-iface-tx-length"></A> tx length <I>number</I></CODE><DD><P>This option specifies the maximum length of generated RIP packets. To
! 2350: avoid IP fragmentation, it should not exceed the interface MTU value.
! 2351: The default value is 532 for IPv4 RIP and interface MTU value for RIPng.
! 2352: <P>
! 2353: <DT><CODE>
! 2354: <A NAME="rip-iface-check-link"></A> check link <I>switch</I></CODE><DD><P>If set, the hardware link state (as reported by OS) is taken into
! 2355: consideration. When the link disappears (e.g. an ethernet cable is
! 2356: unplugged), neighbors are immediately considered unreachable and all
! 2357: routes received from them are withdrawn. It is possible that some
! 2358: hardware drivers or platforms do not implement this feature.
! 2359: Default: no.
! 2360: </DL>
! 2361: <P>
! 2362: <H3><A NAME="rip-attr"></A> Attributes</H3>
! 2363:
! 2364: <P>RIP defines two route attributes:
! 2365: <P>
! 2366: <DL>
! 2367: <DT><CODE>
! 2368: <A NAME="rta-rip-metric"></A> int rip_metric/</CODE><DD><P>RIP metric of the route (ranging from 0 to <CODE>infinity</CODE>). When routes
! 2369: from different RIP instances are available and all of them have the same
! 2370: preference, BIRD prefers the route with lowest <CODE>rip_metric</CODE>. When a
! 2371: non-RIP route is exported to RIP, the default metric is 1.
! 2372: <P>
! 2373: <DT><CODE>
! 2374: <A NAME="rta-rip-tag"></A> int rip_tag/</CODE><DD><P>RIP route tag: a 16-bit number which can be used to carry additional
! 2375: information with the route (for example, an originating AS number in
! 2376: case of external routes). When a non-RIP route is exported to RIP, the
! 2377: default tag is 0.
! 2378: </DL>
! 2379: <P>
! 2380: <H3><A NAME="rip-exam"></A> Example</H3>
! 2381:
! 2382: <P>
! 2383: <HR>
! 2384: <PRE>
! 2385: protocol rip {
! 2386: debug all;
! 2387: port 1520;
! 2388: period 12;
! 2389: garbage time 60;
! 2390: interface "eth0" { metric 3; mode multicast; };
! 2391: interface "eth*" { metric 2; mode broadcast; };
! 2392: authentication cryptographic;
! 2393: password "secret-shared-key" { algorithm hmac sha256; };
! 2394: import filter { print "importing"; accept; };
! 2395: export filter { print "exporting"; accept; };
! 2396: }
! 2397: </PRE>
! 2398: <HR>
! 2399: <P>
! 2400: <P>
! 2401: <H2><A NAME="static"></A> <A NAME="ss6.11">6.11</A> <A HREF="bird.html#toc6.11">Static</A>
! 2402: </H2>
! 2403:
! 2404: <P>The Static protocol doesn't communicate with other routers in the network,
! 2405: but instead it allows you to define routes manually. This is often used for
! 2406: specifying how to forward packets to parts of the network which don't use
! 2407: dynamic routing at all and also for defining sink routes (i.e., those telling to
! 2408: return packets as undeliverable if they are in your IP block, you don't have any
! 2409: specific destination for them and you don't want to send them out through the
! 2410: default route to prevent routing loops).
! 2411: <P>
! 2412: <P>There are five types of static routes: `classical' routes telling to forward
! 2413: packets to a neighboring router, multipath routes specifying several (possibly
! 2414: weighted) neighboring routers, device routes specifying forwarding to hosts on a
! 2415: directly connected network, recursive routes computing their nexthops by doing
! 2416: route table lookups for a given IP, and special routes (sink, blackhole etc.)
! 2417: which specify a special action to be done instead of forwarding the packet.
! 2418: <P>
! 2419: <P>When the particular destination is not available (the interface is down or
! 2420: the next hop of the route is not a neighbor at the moment), Static just
! 2421: uninstalls the route from the table it is connected to and adds it again as soon
! 2422: as the destination becomes adjacent again.
! 2423: <P>
! 2424: <P>There are three classes of definitions in Static protocol configuration --
! 2425: global options, static route definitions, and per-route options. Usually, the
! 2426: definition of the protocol contains mainly a list of static routes.
! 2427: <P>
! 2428: <P>Global options:
! 2429: <P>
! 2430: <DL>
! 2431: <DT><CODE>
! 2432: <A NAME="static-check-link"></A> check link <I>switch</I></CODE><DD><P>If set, hardware link states of network interfaces are taken into
! 2433: consideration. When link disappears (e.g. ethernet cable is unplugged),
! 2434: static routes directing to that interface are removed. It is possible
! 2435: that some hardware drivers or platforms do not implement this feature.
! 2436: Default: off.
! 2437: <P>
! 2438: <DT><CODE>
! 2439: <A NAME="static-igp-table"></A> igp table <I>name</I></CODE><DD><P>Specifies a table that is used for route table lookups of recursive
! 2440: routes. Default: the same table as the protocol is connected to.
! 2441: </DL>
! 2442: <P>
! 2443: <P>Route definitions (each may also contain a block of per-route options):
! 2444: <P>
! 2445: <DL>
! 2446: <DT><CODE>
! 2447: <A NAME="static-route-via-ip"></A> route <I>prefix</I> via <I>ip</I></CODE><DD><P>Static route through a neighboring router. For link-local next hops,
! 2448: interface can be specified as a part of the address (e.g.,
! 2449: <CODE>via fe80::1234%eth0</CODE>).
! 2450: <P>
! 2451: <DT><CODE>
! 2452: <A NAME="static-route-via-mpath"></A> route <I>prefix</I> multipath via <I>ip</I> [weight <I>num</I>] [bfd <I>switch</I>] [via <I>...</I>]</CODE><DD><P>Static multipath route. Contains several nexthops (gateways), possibly
! 2453: with their weights.
! 2454: <P>
! 2455: <DT><CODE>
! 2456: <A NAME="static-route-via-iface"></A> route <I>prefix</I> via <I>"interface"</I></CODE><DD><P>Static device route through an interface to hosts on a directly
! 2457: connected network.
! 2458: <P>
! 2459: <DT><CODE>
! 2460: <A NAME="static-route-recursive"></A> route <I>prefix</I> recursive <I>ip</I></CODE><DD><P>Static recursive route, its nexthop depends on a route table lookup for
! 2461: given IP address.
! 2462: <P>
! 2463: <DT><CODE>
! 2464: <A NAME="static-route-drop"></A> route <I>prefix</I> blackhole|unreachable|prohibit</CODE><DD><P>Special routes specifying to silently drop the packet, return it as
! 2465: unreachable or return it as administratively prohibited. First two
! 2466: targets are also known as <CODE>drop</CODE> and <CODE>reject</CODE>.
! 2467: </DL>
! 2468: <P>
! 2469: <P>Per-route options:
! 2470: <P>
! 2471: <DL>
! 2472: <DT><CODE>
! 2473: <A NAME="static-route-bfd"></A> bfd <I>switch</I></CODE><DD><P>The Static protocol could use BFD protocol for next hop liveness
! 2474: detection. If enabled, a BFD session to the route next hop is created
! 2475: and the static route is BFD-controlled -- the static route is announced
! 2476: only if the next hop liveness is confirmed by BFD. If the BFD session
! 2477: fails, the static route is removed. Note that this is a bit different
! 2478: compared to other protocols, which may use BFD as an advisory mechanism
! 2479: for fast failure detection but ignores it if a BFD session is not even
! 2480: established.
! 2481: <P>This option can be used for static routes with a direct next hop, or
! 2482: also for for individual next hops in a static multipath route (see
! 2483: above). Note that BFD protocol also has to be configured, see
! 2484: <A HREF="#bfd">BFD</A> section for details. Default value is no.
! 2485: <P>
! 2486: <DT><CODE>
! 2487: <A NAME="static-route-filter"></A> <I>filter expression</I></CODE><DD><P>This is a special option that allows filter expressions to be configured
! 2488: on per-route basis. Can be used multiple times. These expressions are
! 2489: evaluated when the route is originated, similarly to the import filter
! 2490: of the static protocol. This is especially useful for configuring route
! 2491: attributes, e.g., <CODE>ospf_metric1 = 100;</CODE> for a route that will be
! 2492: exported to the OSPF protocol.
! 2493: </DL>
! 2494: <P>
! 2495: <P>Static routes have no specific attributes.
! 2496: <P>
! 2497: <P>Example static config might look like this:
! 2498: <P>
! 2499: <P>
! 2500: <HR>
! 2501: <PRE>
! 2502: protocol static {
! 2503: table testable; # Connect to a non-default routing table
! 2504: check link; # Advertise routes only if link is up
! 2505: route 0.0.0.0/0 via 198.51.100.130; # Default route
! 2506: route 10.0.0.0/8 multipath # Multipath route
! 2507: via 198.51.100.10 weight 2
! 2508: via 198.51.100.20 bfd # BFD-controlled next hop
! 2509: via 192.0.2.1;
! 2510: route 203.0.113.0/24 unreachable; # Sink route
! 2511: route 10.2.0.0/24 via "arc0"; # Secondary network
! 2512: route 192.168.10.0/24 via 198.51.100.100 {
! 2513: ospf_metric1 = 20; # Set extended attribute
! 2514: }
! 2515: route 192.168.10.0/24 via 198.51.100.100 {
! 2516: ospf_metric2 = 100; # Set extended attribute
! 2517: ospf_tag = 2; # Set extended attribute
! 2518: bfd; # BFD-controlled route
! 2519: }
! 2520: }
! 2521: </PRE>
! 2522: <HR>
! 2523: <P>
! 2524: <P>
! 2525: <HR>
! 2526: <A HREF="bird-7.html">Next</A>
! 2527: <A HREF="bird-5.html">Previous</A>
! 2528: <A HREF="bird.html#toc6">Contents</A>
! 2529: </BODY>
! 2530: </HTML>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to bird-6.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc