Annotation of embedaddon/bird/doc/prog-5.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 Programmer's Documentation: Protocols</TITLE>
! 6: <LINK HREF="prog-6.html" REL=next>
! 7: <LINK HREF="prog-4.html" REL=previous>
! 8: <LINK HREF="prog.html#toc5" REL=contents>
! 9: </HEAD>
! 10: <BODY>
! 11: <A HREF="prog-6.html">Next</A>
! 12: <A HREF="prog-4.html">Previous</A>
! 13: <A HREF="prog.html#toc5">Contents</A>
! 14: <HR>
! 15: <H2><A NAME="s5">5.</A> <A HREF="prog.html#toc5">Protocols</A></H2>
! 16:
! 17: <H2><A NAME="ss5.1">5.1</A> <A HREF="prog.html#toc5.1">The Babel protocol</A>
! 18: </H2>
! 19:
! 20: <P>
! 21: <P>Babel (RFC6126) is a loop-avoiding distance-vector routing protocol that is
! 22: robust and efficient both in ordinary wired networks and in wireless mesh
! 23: networks.
! 24: <P>The Babel protocol keeps state for each neighbour in a <I>babel_neighbor</I>
! 25: struct, tracking received Hello and I Heard You (IHU) messages. A
! 26: <I>babel_interface</I> struct keeps hello and update times for each interface, and
! 27: a separate hello seqno is maintained for each interface.
! 28: <P>For each prefix, Babel keeps track of both the possible routes (with next hop
! 29: and router IDs), as well as the feasibility distance for each prefix and
! 30: router id. The prefix itself is tracked in a <I>babel_entry</I> struct, while the
! 31: possible routes for the prefix are tracked as <I>babel_route</I> entries and the
! 32: feasibility distance is maintained through <I>babel_source</I> structures.
! 33: <P>The main route selection is done in <B>babel_select_route()</B>. This is called when
! 34: an entry is updated by receiving updates from the network or when modified by
! 35: internal timers. It performs feasibility checks on the available routes for
! 36: the prefix and selects the one with the lowest metric to be announced to the
! 37: core.
! 38: <P>
! 39: <P><HR><H3>Function</H3>
! 40: <P><I>void</I>
! 41: <B>babel_announce_rte</B>
! 42: (<I>struct babel_proto *</I> <B>p</B>, <I>struct babel_entry *</I> <B>e</B>) -- announce selected route to the core
! 43: <P>
! 44: <H3>Arguments</H3>
! 45: <P>
! 46: <DL>
! 47: <DT><I>struct babel_proto *</I> <B>p</B><DD><P>Babel protocol instance
! 48: <DT><I>struct babel_entry *</I> <B>e</B><DD><P>Babel route entry to announce
! 49: </DL>
! 50: <H3>Description</H3>
! 51: <P>This function announces a Babel entry to the core if it has a selected
! 52: incoming path, and retracts it otherwise. If the selected entry has infinite
! 53: metric, the route is announced as unreachable.
! 54:
! 55:
! 56: <HR><H3>Function</H3>
! 57: <P><I>void</I>
! 58: <B>babel_select_route</B>
! 59: (<I>struct babel_entry *</I> <B>e</B>) -- select best route for given route entry
! 60: <P>
! 61: <H3>Arguments</H3>
! 62: <P>
! 63: <DL>
! 64: <DT><I>struct babel_entry *</I> <B>e</B><DD><P>Babel entry to select the best route for
! 65: </DL>
! 66: <H3>Description</H3>
! 67: <P>Select the best feasible route for a given prefix among the routes received
! 68: from peers, and propagate it to the nest. This just selects the feasible
! 69: route with the lowest metric.
! 70: <P>If no feasible route is available for a prefix that previously had a route
! 71: selected, a seqno request is sent to try to get a valid route. In the
! 72: meantime, the route is marked as infeasible in the nest (to blackhole packets
! 73: going to it, as per the RFC).
! 74: <P>If no feasible route is available, and no previous route is selected, the
! 75: route is removed from the nest entirely.
! 76:
! 77:
! 78: <HR><H3>Function</H3>
! 79: <P><I>void</I>
! 80: <B>babel_send_update</B>
! 81: (<I>struct babel_iface *</I> <B>ifa</B>, <I>bird_clock_t</I> <B>changed</B>) -- send route table updates
! 82: <P>
! 83: <H3>Arguments</H3>
! 84: <P>
! 85: <DL>
! 86: <DT><I>struct babel_iface *</I> <B>ifa</B><DD><P>Interface to transmit on
! 87: <DT><I>bird_clock_t</I> <B>changed</B><DD><P>Only send entries changed since this time
! 88: </DL>
! 89: <H3>Description</H3>
! 90: <P>This function produces update TLVs for all entries changed since the time
! 91: indicated by the <I>changed</I> parameter and queues them for transmission on the
! 92: selected interface. During the process, the feasibility distance for each
! 93: transmitted entry is updated.
! 94:
! 95:
! 96: <HR><H3>Function</H3>
! 97: <P><I>void</I>
! 98: <B>babel_handle_update</B>
! 99: (<I>union babel_msg *</I> <B>m</B>, <I>struct babel_iface *</I> <B>ifa</B>) -- handle incoming route updates
! 100: <P>
! 101: <H3>Arguments</H3>
! 102: <P>
! 103: <DL>
! 104: <DT><I>union babel_msg *</I> <B>m</B><DD><P>Incoming update TLV
! 105: <DT><I>struct babel_iface *</I> <B>ifa</B><DD><P>Interface the update was received on
! 106: </DL>
! 107: <H3>Description</H3>
! 108: <P>This function is called as a handler for update TLVs and handles the updating
! 109: and maintenance of route entries in Babel's internal routing cache. The
! 110: handling follows the actions described in the Babel RFC, and at the end of
! 111: each update handling, <B>babel_select_route()</B> is called on the affected entry to
! 112: optionally update the selected routes and propagate them to the core.
! 113:
! 114:
! 115: <HR><H3>Function</H3>
! 116: <P><I>void</I>
! 117: <B>babel_iface_timer</B>
! 118: (<I>timer *</I> <B>t</B>) -- Babel interface timer handler
! 119: <P>
! 120: <H3>Arguments</H3>
! 121: <P>
! 122: <DL>
! 123: <DT><I>timer *</I> <B>t</B><DD><P>Timer
! 124: </DL>
! 125: <H3>Description</H3>
! 126: <P>This function is called by the per-interface timer and triggers sending of
! 127: periodic Hello's and both triggered and periodic updates. Periodic Hello's
! 128: and updates are simply handled by setting the next_{hello,regular} variables
! 129: on the interface, and triggering an update (and resetting the variable)
! 130: whenever 'now' exceeds that value.
! 131: <P>For triggered updates, <B>babel_trigger_iface_update()</B> will set the
! 132: want_triggered field on the interface to a timestamp value. If this is set
! 133: (and the next_triggered time has passed; this is a rate limiting mechanism),
! 134: <B>babel_send_update()</B> will be called with this timestamp as the second
! 135: parameter. This causes updates to be send consisting of only the routes that
! 136: have changed since the time saved in want_triggered.
! 137: <P>Mostly when an update is triggered, the route being modified will be set to
! 138: the value of 'now' at the time of the trigger; the >= comparison for
! 139: selecting which routes to send in the update will make sure this is included.
! 140:
! 141:
! 142: <HR><H3>Function</H3>
! 143: <P><I>void</I>
! 144: <B>babel_timer</B>
! 145: (<I>timer *</I> <B>t</B>) -- global timer hook
! 146: <P>
! 147: <H3>Arguments</H3>
! 148: <P>
! 149: <DL>
! 150: <DT><I>timer *</I> <B>t</B><DD><P>Timer
! 151: </DL>
! 152: <H3>Description</H3>
! 153: <P>This function is called by the global protocol instance timer and handles
! 154: expiration of routes and neighbours as well as pruning of the seqno request
! 155: cache.
! 156:
! 157:
! 158: <HR><H3>Function</H3>
! 159: <P><I>uint</I>
! 160: <B>babel_write_queue</B>
! 161: (<I>struct babel_iface *</I> <B>ifa</B>, <I>list *</I> <B>queue</B>) -- Write a TLV queue to a transmission buffer
! 162: <P>
! 163: <H3>Arguments</H3>
! 164: <P>
! 165: <DL>
! 166: <DT><I>struct babel_iface *</I> <B>ifa</B><DD><P>Interface holding the transmission buffer
! 167: <DT><I>list *</I> <B>queue</B><DD><P>TLV queue to write (containing internal-format TLVs)
! 168: </DL>
! 169: <H3>Description</H3>
! 170: <P>This function writes a packet to the interface transmission buffer with as
! 171: many TLVs from the <I>queue</I> as will fit in the buffer. It returns the number of
! 172: bytes written (NOT counting the packet header). The function is called by
! 173: <B>babel_send_queue()</B> and <B>babel_send_unicast()</B> to construct packets for
! 174: transmission, and uses per-TLV helper functions to convert the
! 175: internal-format TLVs to their wire representations.
! 176: <P>The TLVs in the queue are freed after they are written to the buffer.
! 177:
! 178:
! 179: <HR><H3>Function</H3>
! 180: <P><I>void</I>
! 181: <B>babel_send_unicast</B>
! 182: (<I>union babel_msg *</I> <B>msg</B>, <I>struct babel_iface *</I> <B>ifa</B>, <I>ip_addr</I> <B>dest</B>) -- send a single TLV via unicast to a destination
! 183: <P>
! 184: <H3>Arguments</H3>
! 185: <P>
! 186: <DL>
! 187: <DT><I>union babel_msg *</I> <B>msg</B><DD><P>TLV to send
! 188: <DT><I>struct babel_iface *</I> <B>ifa</B><DD><P>Interface to send via
! 189: <DT><I>ip_addr</I> <B>dest</B><DD><P>Destination of the TLV
! 190: </DL>
! 191: <H3>Description</H3>
! 192: <P>This function is used to send a single TLV via unicast to a designated
! 193: receiver. This is used for replying to certain incoming requests, and for
! 194: sending unicast requests to refresh routes before they expire.
! 195:
! 196:
! 197: <HR><H3>Function</H3>
! 198: <P><I>void</I>
! 199: <B>babel_enqueue</B>
! 200: (<I>union babel_msg *</I> <B>msg</B>, <I>struct babel_iface *</I> <B>ifa</B>) -- enqueue a TLV for transmission on an interface
! 201: <P>
! 202: <H3>Arguments</H3>
! 203: <P>
! 204: <DL>
! 205: <DT><I>union babel_msg *</I> <B>msg</B><DD><P>TLV to enqueue (in internal TLV format)
! 206: <DT><I>struct babel_iface *</I> <B>ifa</B><DD><P>Interface to enqueue to
! 207: </DL>
! 208: <H3>Description</H3>
! 209: <P>This function is called to enqueue a TLV for subsequent transmission on an
! 210: interface. The transmission event is triggered whenever a TLV is enqueued;
! 211: this ensures that TLVs will be transmitted in a timely manner, but that TLVs
! 212: which are enqueued in rapid succession can be transmitted together in one
! 213: packet.
! 214:
! 215:
! 216: <HR><H3>Function</H3>
! 217: <P><I>void</I>
! 218: <B>babel_process_packet</B>
! 219: (<I>struct babel_pkt_header *</I> <B>pkt</B>, <I>int</I> <B>len</B>, <I>ip_addr</I> <B>saddr</B>, <I>struct babel_iface *</I> <B>ifa</B>) -- process incoming data packet
! 220: <P>
! 221: <H3>Arguments</H3>
! 222: <P>
! 223: <DL>
! 224: <DT><I>struct babel_pkt_header *</I> <B>pkt</B><DD><P>Pointer to the packet data
! 225: <DT><I>int</I> <B>len</B><DD><P>Length of received packet
! 226: <DT><I>ip_addr</I> <B>saddr</B><DD><P>Address of packet sender
! 227: <DT><I>struct babel_iface *</I> <B>ifa</B><DD><P>Interface packet was received on.
! 228: </DL>
! 229: <H3>Description</H3>
! 230: <P>This function is the main processing hook of incoming Babel packets. It
! 231: checks that the packet header is well-formed, then processes the TLVs
! 232: contained in the packet. This is done in two passes: First all TLVs are
! 233: parsed into the internal TLV format. If a TLV parser fails, processing of the
! 234: rest of the packet is aborted.
! 235: <P>After the parsing step, the TLV handlers are called for each parsed TLV in
! 236: order.
! 237:
! 238: <H2><A NAME="ss5.2">5.2</A> <A HREF="prog.html#toc5.2">Bidirectional Forwarding Detection</A>
! 239: </H2>
! 240:
! 241: <P>
! 242: <P>The BFD protocol is implemented in three files: <CODE>bfd.c</CODE> containing the
! 243: protocol logic and the protocol glue with BIRD core, <CODE>packets.c</CODE> handling BFD
! 244: packet processing, RX, TX and protocol sockets. <CODE>io.c</CODE> then contains generic
! 245: code for the event loop, threads and event sources (sockets, microsecond
! 246: timers). This generic code will be merged to the main BIRD I/O code in the
! 247: future.
! 248: <P>The BFD implementation uses a separate thread with an internal event loop for
! 249: handling the protocol logic, which requires high-res and low-latency timing,
! 250: so it is not affected by the rest of BIRD, which has several low-granularity
! 251: hooks in the main loop, uses second-based timers and cannot offer good
! 252: latency. The core of BFD protocol (the code related to BFD sessions,
! 253: interfaces and packets) runs in the BFD thread, while the rest (the code
! 254: related to BFD requests, BFD neighbors and the protocol glue) runs in the
! 255: main thread.
! 256: <P>BFD sessions are represented by structure <I>bfd_session</I> that contains a state
! 257: related to the session and two timers (TX timer for periodic packets and hold
! 258: timer for session timeout). These sessions are allocated from <B>session_slab</B>
! 259: and are accessible by two hash tables, <B>session_hash_id</B> (by session ID) and
! 260: <B>session_hash_ip</B> (by IP addresses of neighbors). Slab and both hashes are in
! 261: the main protocol structure <I>bfd_proto</I>. The protocol logic related to BFD
! 262: sessions is implemented in internal functions bfd_session_*(), which are
! 263: expected to be called from the context of BFD thread, and external functions
! 264: <B>bfd_add_session()</B>, <B>bfd_remove_session()</B> and <B>bfd_reconfigure_session()</B>, which
! 265: form an interface to the BFD core for the rest and are expected to be called
! 266: from the context of main thread.
! 267: <P>Each BFD session has an associated BFD interface, represented by structure
! 268: <I>bfd_iface</I>. A BFD interface contains a socket used for TX (the one for RX is
! 269: shared in <I>bfd_proto</I>), an interface configuration and reference counter.
! 270: Compared to interface structures of other protocols, these structures are not
! 271: created and removed based on interface notification events, but according to
! 272: the needs of BFD sessions. When a new session is created, it requests a
! 273: proper BFD interface by function <B>bfd_get_iface()</B>, which either finds an
! 274: existing one in <I>iface_list</I> (from <I>bfd_proto</I>) or allocates a new one. When a
! 275: session is removed, an associated iface is discharged by <B>bfd_free_iface()</B>.
! 276: <P>BFD requests are the external API for the other protocols. When a protocol
! 277: wants a BFD session, it calls <B>bfd_request_session()</B>, which creates a
! 278: structure <I>bfd_request</I> containing approprite information and an notify hook.
! 279: This structure is a resource associated with the caller's resource pool. When
! 280: a BFD protocol is available, a BFD request is submitted to the protocol, an
! 281: appropriate BFD session is found or created and the request is attached to
! 282: the session. When a session changes state, all attached requests (and related
! 283: protocols) are notified. Note that BFD requests do not depend on BFD protocol
! 284: running. When the BFD protocol is stopped or removed (or not available from
! 285: beginning), related BFD requests are stored in <B>bfd_wait_list</B>, where waits
! 286: for a new protocol.
! 287: <P>BFD neighbors are just a way to statically configure BFD sessions without
! 288: requests from other protocol. Structures <I>bfd_neighbor</I> are part of BFD
! 289: configuration (like static routes in the static protocol). BFD neighbors are
! 290: handled by BFD protocol like it is a BFD client -- when a BFD neighbor is
! 291: ready, the protocol just creates a BFD request like any other protocol.
! 292: <P>The protocol uses a new generic event loop (structure <I>birdloop</I>) from <CODE>io.c</CODE>,
! 293: which supports sockets, timers and events like the main loop. Timers
! 294: (structure <I>timer2</I>) are new microsecond based timers, while sockets and
! 295: events are the same. A birdloop is associated with a thread (field <B>thread</B>)
! 296: in which event hooks are executed. Most functions for setting event sources
! 297: (like <B>sk_start()</B> or <B>tm2_start()</B>) must be called from the context of that
! 298: thread. Birdloop allows to temporarily acquire the context of that thread for
! 299: the main thread by calling <B>birdloop_enter()</B> and then <B>birdloop_leave()</B>, which
! 300: also ensures mutual exclusion with all event hooks. Note that resources
! 301: associated with a birdloop (like timers) should be attached to the
! 302: independent resource pool, detached from the main resource tree.
! 303: <P>There are two kinds of interaction between the BFD core (running in the BFD
! 304: thread) and the rest of BFD (running in the main thread). The first kind are
! 305: configuration calls from main thread to the BFD thread (like <B>bfd_add_session()</B>).
! 306: These calls are synchronous and use <B>birdloop_enter()</B> mechanism for mutual
! 307: exclusion. The second kind is a notification about session changes from the
! 308: BFD thread to the main thread. This is done in an asynchronous way, sesions
! 309: with pending notifications are linked (in the BFD thread) to <B>notify_list</B> in
! 310: <I>bfd_proto</I>, and then <B>bfd_notify_hook()</B> in the main thread is activated using
! 311: <B>bfd_notify_kick()</B> and a pipe. The hook then processes scheduled sessions and
! 312: calls hooks from associated BFD requests. This <B>notify_list</B> (and state fields
! 313: in structure <I>bfd_session</I>) is protected by a spinlock in <I>bfd_proto</I> and
! 314: functions <B>bfd_lock_sessions()</B> / <B>bfd_unlock_sessions()</B>.
! 315: <P>There are few data races (accessing <B>p</B>->p.debug from <B>TRACE()</B> from the BFD
! 316: thread and accessing some some private fields of <I>bfd_session</I> from
! 317: <B>bfd_show_sessions()</B> from the main thread, but these are harmless (i hope).
! 318: <P>TODO: document functions and access restrictions for fields in BFD structures.
! 319: <P>Supported standards:
! 320: - RFC 5880 - main BFD standard
! 321: - RFC 5881 - BFD for IP links
! 322: - RFC 5882 - generic application of BFD
! 323: - RFC 5883 - BFD for multihop paths
! 324: <P>
! 325: <P>
! 326: <H2><A NAME="ss5.3">5.3</A> <A HREF="prog.html#toc5.3">Border Gateway Protocol</A>
! 327: </H2>
! 328:
! 329: <P>
! 330: <P>The BGP protocol is implemented in three parts: <CODE>bgp.c</CODE> which takes care of the
! 331: connection and most of the interface with BIRD core, <CODE>packets.c</CODE> handling
! 332: both incoming and outgoing BGP packets and <CODE>attrs.c</CODE> containing functions for
! 333: manipulation with BGP attribute lists.
! 334: <P>As opposed to the other existing routing daemons, BIRD has a sophisticated core
! 335: architecture which is able to keep all the information needed by BGP in the
! 336: primary routing table, therefore no complex data structures like a central
! 337: BGP table are needed. This increases memory footprint of a BGP router with
! 338: many connections, but not too much and, which is more important, it makes
! 339: BGP much easier to implement.
! 340: <P>Each instance of BGP (corresponding to a single BGP peer) is described by a <I>bgp_proto</I>
! 341: structure to which are attached individual connections represented by <I>bgp_connection</I>
! 342: (usually, there exists only one connection, but during BGP session setup, there
! 343: can be more of them). The connections are handled according to the BGP state machine
! 344: defined in the RFC with all the timers and all the parameters configurable.
! 345: <P>In incoming direction, we listen on the connection's socket and each time we receive
! 346: some input, we pass it to <B>bgp_rx()</B>. It decodes packet headers and the markers and
! 347: passes complete packets to <B>bgp_rx_packet()</B> which distributes the packet according
! 348: to its type.
! 349: <P>In outgoing direction, we gather all the routing updates and sort them to buckets
! 350: (<I>bgp_bucket</I>) according to their attributes (we keep a hash table for fast comparison
! 351: of <I>rta</I>'s and a <I>fib</I> which helps us to find if we already have another route for
! 352: the same destination queued for sending, so that we can replace it with the new one
! 353: immediately instead of sending both updates). There also exists a special bucket holding
! 354: all the route withdrawals which cannot be queued anywhere else as they don't have any
! 355: attributes. If we have any packet to send (due to either new routes or the connection
! 356: tracking code wanting to send a Open, Keepalive or Notification message), we call
! 357: <B>bgp_schedule_packet()</B> which sets the corresponding bit in a <B>packet_to_send</B>
! 358: bit field in <I>bgp_conn</I> and as soon as the transmit socket buffer becomes empty,
! 359: we call <B>bgp_fire_tx()</B>. It inspects state of all the packet type bits and calls
! 360: the corresponding <B>bgp_create_xx()</B> functions, eventually rescheduling the same packet
! 361: type if we have more data of the same type to send.
! 362: <P>The processing of attributes consists of two functions: <B>bgp_decode_attrs()</B> for checking
! 363: of the attribute blocks and translating them to the language of BIRD's extended attributes
! 364: and <B>bgp_encode_attrs()</B> which does the converse. Both functions are built around a
! 365: <B>bgp_attr_table</B> array describing all important characteristics of all known attributes.
! 366: Unknown transitive attributes are attached to the route as <I>EAF_TYPE_OPAQUE</I> byte streams.
! 367: <P>BGP protocol implements graceful restart in both restarting (local restart)
! 368: and receiving (neighbor restart) roles. The first is handled mostly by the
! 369: graceful restart code in the nest, BGP protocol just handles capabilities,
! 370: sets <B>gr_wait</B> and locks graceful restart until end-of-RIB mark is received.
! 371: The second is implemented by internal restart of the BGP state to <I>BS_IDLE</I>
! 372: and protocol state to <I>PS_START</I>, but keeping the protocol up from the core
! 373: point of view and therefore maintaining received routes. Routing table
! 374: refresh cycle (<B>rt_refresh_begin()</B>, <B>rt_refresh_end()</B>) is used for removing
! 375: stale routes after reestablishment of BGP session during graceful restart.
! 376: <P>
! 377: <P><HR><H3>Function</H3>
! 378: <P><I>int</I>
! 379: <B>bgp_open</B>
! 380: (<I>struct bgp_proto *</I> <B>p</B>) -- open a BGP instance
! 381: <P>
! 382: <H3>Arguments</H3>
! 383: <P>
! 384: <DL>
! 385: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 386: </DL>
! 387: <H3>Description</H3>
! 388: <P>This function allocates and configures shared BGP resources.
! 389: Should be called as the last step during initialization
! 390: (when lock is acquired and neighbor is ready).
! 391: When error, state changed to PS_DOWN, -1 is returned and caller
! 392: should return immediately.
! 393:
! 394:
! 395: <HR><H3>Function</H3>
! 396: <P><I>void</I>
! 397: <B>bgp_close</B>
! 398: (<I>struct bgp_proto *</I> <B>p</B>, <I>int</I> <B>apply_md5</B>) -- close a BGP instance
! 399: <P>
! 400: <H3>Arguments</H3>
! 401: <P>
! 402: <DL>
! 403: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 404: <DT><I>int</I> <B>apply_md5</B><DD><P>0 to disable unsetting MD5 auth
! 405: </DL>
! 406: <H3>Description</H3>
! 407: <P>This function frees and deconfigures shared BGP resources.
! 408: <B>apply_md5</B> is set to 0 when bgp_close is called as a cleanup
! 409: from failed <B>bgp_open()</B>.
! 410:
! 411:
! 412: <HR><H3>Function</H3>
! 413: <P><I>void</I>
! 414: <B>bgp_start_timer</B>
! 415: (<I>timer *</I> <B>t</B>, <I>int</I> <B>value</B>) -- start a BGP timer
! 416: <P>
! 417: <H3>Arguments</H3>
! 418: <P>
! 419: <DL>
! 420: <DT><I>timer *</I> <B>t</B><DD><P>timer
! 421: <DT><I>int</I> <B>value</B><DD><P>time to fire (0 to disable the timer)
! 422: </DL>
! 423: <H3>Description</H3>
! 424: <P>This functions calls <B>tm_start()</B> on <B>t</B> with time <B>value</B> and the
! 425: amount of randomization suggested by the BGP standard. Please use
! 426: it for all BGP timers.
! 427:
! 428:
! 429: <HR><H3>Function</H3>
! 430: <P><I>void</I>
! 431: <B>bgp_close_conn</B>
! 432: (<I>struct bgp_conn *</I> <B>conn</B>) -- close a BGP connection
! 433: <P>
! 434: <H3>Arguments</H3>
! 435: <P>
! 436: <DL>
! 437: <DT><I>struct bgp_conn *</I> <B>conn</B><DD><P>connection to close
! 438: </DL>
! 439: <H3>Description</H3>
! 440: <P>This function takes a connection described by the <I>bgp_conn</I> structure,
! 441: closes its socket and frees all resources associated with it.
! 442:
! 443:
! 444: <HR><H3>Function</H3>
! 445: <P><I>void</I>
! 446: <B>bgp_update_startup_delay</B>
! 447: (<I>struct bgp_proto *</I> <B>p</B>) -- update a startup delay
! 448: <P>
! 449: <H3>Arguments</H3>
! 450: <P>
! 451: <DL>
! 452: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 453: </DL>
! 454: <H3>Description</H3>
! 455: <P>This function updates a startup delay that is used to postpone next BGP connect.
! 456: It also handles disable_after_error and might stop BGP instance when error
! 457: happened and disable_after_error is on.
! 458: <P>It should be called when BGP protocol error happened.
! 459:
! 460:
! 461: <HR><H3>Function</H3>
! 462: <P><I>void</I>
! 463: <B>bgp_handle_graceful_restart</B>
! 464: (<I>struct bgp_proto *</I> <B>p</B>) -- handle detected BGP graceful restart
! 465: <P>
! 466: <H3>Arguments</H3>
! 467: <P>
! 468: <DL>
! 469: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 470: </DL>
! 471: <H3>Description</H3>
! 472: <P>This function is called when a BGP graceful restart of the neighbor is
! 473: detected (when the TCP connection fails or when a new TCP connection
! 474: appears). The function activates processing of the restart - starts routing
! 475: table refresh cycle and activates BGP restart timer. The protocol state goes
! 476: back to <I>PS_START</I>, but changing BGP state back to <I>BS_IDLE</I> is left for the
! 477: caller.
! 478:
! 479:
! 480: <HR><H3>Function</H3>
! 481: <P><I>void</I>
! 482: <B>bgp_graceful_restart_done</B>
! 483: (<I>struct bgp_proto *</I> <B>p</B>) -- finish active BGP graceful restart
! 484: <P>
! 485: <H3>Arguments</H3>
! 486: <P>
! 487: <DL>
! 488: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 489: </DL>
! 490: <H3>Description</H3>
! 491: <P>This function is called when the active BGP graceful restart of the neighbor
! 492: should be finished - either successfully (the neighbor sends all paths and
! 493: reports end-of-RIB on the new session) or unsuccessfully (the neighbor does
! 494: not support BGP graceful restart on the new session). The function ends
! 495: routing table refresh cycle and stops BGP restart timer.
! 496:
! 497:
! 498: <HR><H3>Function</H3>
! 499: <P><I>void</I>
! 500: <B>bgp_graceful_restart_timeout</B>
! 501: (<I>timer *</I> <B>t</B>) -- timeout of graceful restart 'restart timer'
! 502: <P>
! 503: <H3>Arguments</H3>
! 504: <P>
! 505: <DL>
! 506: <DT><I>timer *</I> <B>t</B><DD><P>timer
! 507: </DL>
! 508: <H3>Description</H3>
! 509: <P>This function is a timeout hook for <B>gr_timer</B>, implementing BGP restart time
! 510: limit for reestablisment of the BGP session after the graceful restart. When
! 511: fired, we just proceed with the usual protocol restart.
! 512:
! 513:
! 514: <HR><H3>Function</H3>
! 515: <P><I>void</I>
! 516: <B>bgp_refresh_begin</B>
! 517: (<I>struct bgp_proto *</I> <B>p</B>) -- start incoming enhanced route refresh sequence
! 518: <P>
! 519: <H3>Arguments</H3>
! 520: <P>
! 521: <DL>
! 522: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 523: </DL>
! 524: <H3>Description</H3>
! 525: <P>This function is called when an incoming enhanced route refresh sequence is
! 526: started by the neighbor, demarcated by the BoRR packet. The function updates
! 527: the load state and starts the routing table refresh cycle. Note that graceful
! 528: restart also uses routing table refresh cycle, but RFC 7313 and load states
! 529: ensure that these two sequences do not overlap.
! 530:
! 531:
! 532: <HR><H3>Function</H3>
! 533: <P><I>void</I>
! 534: <B>bgp_refresh_end</B>
! 535: (<I>struct bgp_proto *</I> <B>p</B>) -- finish incoming enhanced route refresh sequence
! 536: <P>
! 537: <H3>Arguments</H3>
! 538: <P>
! 539: <DL>
! 540: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 541: </DL>
! 542: <H3>Description</H3>
! 543: <P>This function is called when an incoming enhanced route refresh sequence is
! 544: finished by the neighbor, demarcated by the EoRR packet. The function updates
! 545: the load state and ends the routing table refresh cycle. Routes not received
! 546: during the sequence are removed by the nest.
! 547:
! 548:
! 549: <HR><H3>Function</H3>
! 550: <P><I>void</I>
! 551: <B>bgp_connect</B>
! 552: (<I>struct bgp_proto *</I> <B>p</B>) -- initiate an outgoing connection
! 553: <P>
! 554: <H3>Arguments</H3>
! 555: <P>
! 556: <DL>
! 557: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 558: </DL>
! 559: <H3>Description</H3>
! 560: <P>The <B>bgp_connect()</B> function creates a new <I>bgp_conn</I> and initiates
! 561: a TCP connection to the peer. The rest of connection setup is governed
! 562: by the BGP state machine as described in the standard.
! 563:
! 564:
! 565: <HR><H3>Function</H3>
! 566: <P><I>struct bgp_proto *</I>
! 567: <B>bgp_find_proto</B>
! 568: (<I>sock *</I> <B>sk</B>) -- find existing proto for incoming connection
! 569: <P>
! 570: <H3>Arguments</H3>
! 571: <P>
! 572: <DL>
! 573: <DT><I>sock *</I> <B>sk</B><DD><P>TCP socket
! 574: </DL>
! 575:
! 576:
! 577: <HR><H3>Function</H3>
! 578: <P><I>int</I>
! 579: <B>bgp_incoming_connection</B>
! 580: (<I>sock *</I> <B>sk</B>, <I>uint dummy</I> <B>UNUSED</B>) -- handle an incoming connection
! 581: <P>
! 582: <H3>Arguments</H3>
! 583: <P>
! 584: <DL>
! 585: <DT><I>sock *</I> <B>sk</B><DD><P>TCP socket
! 586: <DT><I>uint dummy</I> <B>UNUSED</B><DD><P>-- undescribed --
! 587: </DL>
! 588: <H3>Description</H3>
! 589: <P>This function serves as a socket hook for accepting of new BGP
! 590: connections. It searches a BGP instance corresponding to the peer
! 591: which has connected and if such an instance exists, it creates a
! 592: <I>bgp_conn</I> structure, attaches it to the instance and either sends
! 593: an Open message or (if there already is an active connection) it
! 594: closes the new connection by sending a Notification message.
! 595:
! 596:
! 597: <HR><H3>Function</H3>
! 598: <P><I>void</I>
! 599: <B>bgp_error</B>
! 600: (<I>struct bgp_conn *</I> <B>c</B>, <I>unsigned</I> <B>code</B>, <I>unsigned</I> <B>subcode</B>, <I>byte *</I> <B>data</B>, <I>int</I> <B>len</B>) -- report a protocol error
! 601: <P>
! 602: <H3>Arguments</H3>
! 603: <P>
! 604: <DL>
! 605: <DT><I>struct bgp_conn *</I> <B>c</B><DD><P>connection
! 606: <DT><I>unsigned</I> <B>code</B><DD><P>error code (according to the RFC)
! 607: <DT><I>unsigned</I> <B>subcode</B><DD><P>error sub-code
! 608: <DT><I>byte *</I> <B>data</B><DD><P>data to be passed in the Notification message
! 609: <DT><I>int</I> <B>len</B><DD><P>length of the data
! 610: </DL>
! 611: <H3>Description</H3>
! 612: <P><B>bgp_error()</B> sends a notification packet to tell the other side that a protocol
! 613: error has occurred (including the data considered erroneous if possible) and
! 614: closes the connection.
! 615:
! 616:
! 617: <HR><H3>Function</H3>
! 618: <P><I>void</I>
! 619: <B>bgp_store_error</B>
! 620: (<I>struct bgp_proto *</I> <B>p</B>, <I>struct bgp_conn *</I> <B>c</B>, <I>u8</I> <B>class</B>, <I>u32</I> <B>code</B>) -- store last error for status report
! 621: <P>
! 622: <H3>Arguments</H3>
! 623: <P>
! 624: <DL>
! 625: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 626: <DT><I>struct bgp_conn *</I> <B>c</B><DD><P>connection
! 627: <DT><I>u8</I> <B>class</B><DD><P>error class (BE_xxx constants)
! 628: <DT><I>u32</I> <B>code</B><DD><P>error code (class specific)
! 629: </DL>
! 630: <H3>Description</H3>
! 631: <P><B>bgp_store_error()</B> decides whether given error is interesting enough
! 632: and store that error to last_error variables of <B>p</B>
! 633:
! 634:
! 635: <HR><H3>Function</H3>
! 636: <P><I>int</I>
! 637: <B>bgp_fire_tx</B>
! 638: (<I>struct bgp_conn *</I> <B>conn</B>) -- transmit packets
! 639: <P>
! 640: <H3>Arguments</H3>
! 641: <P>
! 642: <DL>
! 643: <DT><I>struct bgp_conn *</I> <B>conn</B><DD><P>connection
! 644: </DL>
! 645: <H3>Description</H3>
! 646: <P>Whenever the transmit buffers of the underlying TCP connection
! 647: are free and we have any packets queued for sending, the socket functions
! 648: call <B>bgp_fire_tx()</B> which takes care of selecting the highest priority packet
! 649: queued (Notification > Keepalive > Open > Update), assembling its header
! 650: and body and sending it to the connection.
! 651:
! 652:
! 653: <HR><H3>Function</H3>
! 654: <P><I>void</I>
! 655: <B>bgp_schedule_packet</B>
! 656: (<I>struct bgp_conn *</I> <B>conn</B>, <I>int</I> <B>type</B>) -- schedule a packet for transmission
! 657: <P>
! 658: <H3>Arguments</H3>
! 659: <P>
! 660: <DL>
! 661: <DT><I>struct bgp_conn *</I> <B>conn</B><DD><P>connection
! 662: <DT><I>int</I> <B>type</B><DD><P>packet type
! 663: </DL>
! 664: <H3>Description</H3>
! 665: <P>Schedule a packet of type <B>type</B> to be sent as soon as possible.
! 666:
! 667:
! 668: <HR><H3>Function</H3>
! 669: <P><I>const char *</I>
! 670: <B>bgp_error_dsc</B>
! 671: (<I>unsigned</I> <B>code</B>, <I>unsigned</I> <B>subcode</B>) -- return BGP error description
! 672: <P>
! 673: <H3>Arguments</H3>
! 674: <P>
! 675: <DL>
! 676: <DT><I>unsigned</I> <B>code</B><DD><P>BGP error code
! 677: <DT><I>unsigned</I> <B>subcode</B><DD><P>BGP error subcode
! 678: </DL>
! 679: <H3>Description</H3>
! 680: <P><B>bgp_error_dsc()</B> returns error description for BGP errors
! 681: which might be static string or given temporary buffer.
! 682:
! 683:
! 684: <HR><H3>Function</H3>
! 685: <P><I>void</I>
! 686: <B>bgp_rx_packet</B>
! 687: (<I>struct bgp_conn *</I> <B>conn</B>, <I>byte *</I> <B>pkt</B>, <I>unsigned</I> <B>len</B>) -- handle a received packet
! 688: <P>
! 689: <H3>Arguments</H3>
! 690: <P>
! 691: <DL>
! 692: <DT><I>struct bgp_conn *</I> <B>conn</B><DD><P>BGP connection
! 693: <DT><I>byte *</I> <B>pkt</B><DD><P>start of the packet
! 694: <DT><I>unsigned</I> <B>len</B><DD><P>packet size
! 695: </DL>
! 696: <H3>Description</H3>
! 697: <P><B>bgp_rx_packet()</B> takes a newly received packet and calls the corresponding
! 698: packet handler according to the packet type.
! 699:
! 700:
! 701: <HR><H3>Function</H3>
! 702: <P><I>int</I>
! 703: <B>bgp_rx</B>
! 704: (<I>sock *</I> <B>sk</B>, <I>uint</I> <B>size</B>) -- handle received data
! 705: <P>
! 706: <H3>Arguments</H3>
! 707: <P>
! 708: <DL>
! 709: <DT><I>sock *</I> <B>sk</B><DD><P>socket
! 710: <DT><I>uint</I> <B>size</B><DD><P>amount of data received
! 711: </DL>
! 712: <H3>Description</H3>
! 713: <P><B>bgp_rx()</B> is called by the socket layer whenever new data arrive from
! 714: the underlying TCP connection. It assembles the data fragments to packets,
! 715: checks their headers and framing and passes complete packets to
! 716: <B>bgp_rx_packet()</B>.
! 717:
! 718:
! 719: <HR><H3>Function</H3>
! 720: <P><I>uint</I>
! 721: <B>bgp_encode_attrs</B>
! 722: (<I>struct bgp_proto *</I> <B>p</B>, <I>byte *</I> <B>w</B>, <I>ea_list *</I> <B>attrs</B>, <I>int</I> <B>remains</B>) -- encode BGP attributes
! 723: <P>
! 724: <H3>Arguments</H3>
! 725: <P>
! 726: <DL>
! 727: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance
! 728: <DT><I>byte *</I> <B>w</B><DD><P>buffer
! 729: <DT><I>ea_list *</I> <B>attrs</B><DD><P>a list of extended attributes
! 730: <DT><I>int</I> <B>remains</B><DD><P>remaining space in the buffer
! 731: </DL>
! 732: <H3>Description</H3>
! 733: <P>The <B>bgp_encode_attrs()</B> function takes a list of extended attributes
! 734: and converts it to its BGP representation (a part of an Update message).
! 735: <H3>Result</H3>
! 736: <P>Length of the attribute block generated or -1 if not enough space.
! 737:
! 738:
! 739: <HR><H3>Function</H3>
! 740: <P><I>struct rta *</I>
! 741: <B>bgp_decode_attrs</B>
! 742: (<I>struct bgp_conn *</I> <B>conn</B>, <I>byte *</I> <B>attr</B>, <I>uint</I> <B>len</B>, <I>struct linpool *</I> <B>pool</B>, <I>int</I> <B>mandatory</B>) -- check and decode BGP attributes
! 743: <P>
! 744: <H3>Arguments</H3>
! 745: <P>
! 746: <DL>
! 747: <DT><I>struct bgp_conn *</I> <B>conn</B><DD><P>connection
! 748: <DT><I>byte *</I> <B>attr</B><DD><P>start of attribute block
! 749: <DT><I>uint</I> <B>len</B><DD><P>length of attribute block
! 750: <DT><I>struct linpool *</I> <B>pool</B><DD><P>linear pool to make all the allocations in
! 751: <DT><I>int</I> <B>mandatory</B><DD><P>1 iff presence of mandatory attributes has to be checked
! 752: </DL>
! 753: <H3>Description</H3>
! 754: <P>This function takes a BGP attribute block (a part of an Update message), checks
! 755: its consistency and converts it to a list of BIRD route attributes represented
! 756: by a <I>rta</I>.
! 757:
! 758: <H2><A NAME="ss5.4">5.4</A> <A HREF="prog.html#toc5.4">Open Shortest Path First (OSPF)</A>
! 759: </H2>
! 760:
! 761: <P>
! 762: <P>The OSPF protocol is quite complicated and its complex implemenation is split
! 763: to many files. In <CODE>ospf.c</CODE>, you will find mainly the interface for
! 764: communication with the core (e.g., reconfiguration hooks, shutdown and
! 765: initialisation and so on). File <CODE>iface.c</CODE> contains the interface state
! 766: machine and functions for allocation and deallocation of OSPF's interface
! 767: data structures. Source <CODE>neighbor.c</CODE> includes the neighbor state machine and
! 768: functions for election of Designated Router and Backup Designated router. In
! 769: <CODE>packet.c</CODE>, you will find various functions for sending and receiving generic
! 770: OSPF packets. There are also routines for authentication and checksumming.
! 771: In <CODE>hello.c</CODE>, there are routines for sending and receiving of hello packets
! 772: as well as functions for maintaining wait times and the inactivity timer.
! 773: Files <CODE>lsreq.c</CODE>, <CODE>lsack.c</CODE>, <CODE>dbdes.c</CODE> contain functions for sending and
! 774: receiving of link-state requests, link-state acknowledgements and database
! 775: descriptions respectively. In <CODE>lsupd.c</CODE>, there are functions for sending and
! 776: receiving of link-state updates and also the flooding algorithm. Source
! 777: <CODE>topology.c</CODE> is a place where routines for searching LSAs in the link-state
! 778: database, adding and deleting them reside, there also are functions for
! 779: originating of various types of LSAs (router LSA, net LSA, external LSA).
! 780: File <CODE>rt.c</CODE> contains routines for calculating the routing table. <CODE>lsalib.c</CODE>
! 781: is a set of various functions for working with the LSAs (endianity
! 782: conversions, calculation of checksum etc.).
! 783: <P>One instance of the protocol is able to hold LSA databases for multiple OSPF
! 784: areas, to exchange routing information between multiple neighbors and to
! 785: calculate the routing tables. The core structure is <I>ospf_proto</I> to which
! 786: multiple <I>ospf_area</I> and <I>ospf_iface</I> structures are connected. <I>ospf_proto</I> is
! 787: also connected to <I>top_hash_graph</I> which is a dynamic hashing structure that
! 788: describes the link-state database. It allows fast search, addition and
! 789: deletion. Each LSA is kept in two pieces: header and body. Both of them are
! 790: kept in the endianity of the CPU.
! 791: <P>In OSPFv2 specification, it is implied that there is one IP prefix for each
! 792: physical network/interface (unless it is an ptp link). But in modern systems,
! 793: there might be more independent IP prefixes associated with an interface. To
! 794: handle this situation, we have one <I>ospf_iface</I> for each active IP prefix
! 795: (instead for each active iface); This behaves like virtual interface for the
! 796: purpose of OSPF. If we receive packet, we associate it with a proper virtual
! 797: interface mainly according to its source address.
! 798: <P>OSPF keeps one socket per <I>ospf_iface</I>. This allows us (compared to one socket
! 799: approach) to evade problems with a limit of multicast groups per socket and
! 800: with sending multicast packets to appropriate interface in a portable way.
! 801: The socket is associated with underlying physical iface and should not
! 802: receive packets received on other ifaces (unfortunately, this is not true on
! 803: BSD). Generally, one packet can be received by more sockets (for example, if
! 804: there are more <I>ospf_iface</I> on one physical iface), therefore we explicitly
! 805: filter received packets according to src/dst IP address and received iface.
! 806: <P>Vlinks are implemented using particularly degenerate form of <I>ospf_iface</I>,
! 807: which has several exceptions: it does not have its iface or socket (it copies
! 808: these from 'parent' <I>ospf_iface</I>) and it is present in iface list even when
! 809: down (it is not freed in <B>ospf_iface_down()</B>).
! 810: <P>The heart beat of ospf is <B>ospf_disp()</B>. It is called at regular intervals
! 811: (<I>ospf_proto</I>->tick). It is responsible for aging and flushing of LSAs in the
! 812: database, updating topology information in LSAs and for routing table
! 813: calculation.
! 814: <P>To every <I>ospf_iface</I>, we connect one or more <I>ospf_neighbor</I>'s -- a structure
! 815: containing many timers and queues for building adjacency and for exchange of
! 816: routing messages.
! 817: <P>BIRD's OSPF implementation respects RFC2328 in every detail, but some of
! 818: internal algorithms do differ. The RFC recommends making a snapshot of the
! 819: link-state database when a new adjacency is forming and sending the database
! 820: description packets based on the information in this snapshot. The database
! 821: can be quite large in some networks, so rather we walk through a <I>slist</I>
! 822: structure which allows us to continue even if the actual LSA we were working
! 823: with is deleted. New LSAs are added at the tail of this <I>slist</I>.
! 824: <P>We also do not keep a separate OSPF routing table, because the core helps us
! 825: by being able to recognize when a route is updated to an identical one and it
! 826: suppresses the update automatically. Due to this, we can flush all the routes
! 827: we have recalculated and also those we have deleted to the core's routing
! 828: table and the core will take care of the rest. This simplifies the process
! 829: and conserves memory.
! 830: <P>Supported standards:
! 831: - RFC 2328 - main OSPFv2 standard
! 832: - RFC 5340 - main OSPFv3 standard
! 833: - RFC 3101 - OSPFv2 NSSA areas
! 834: - RFC 6549 - OSPFv2 multi-instance extensions
! 835: - RFC 6987 - OSPF stub router advertisement
! 836: <P>
! 837: <P><HR><H3>Function</H3>
! 838: <P><I>void</I>
! 839: <B>ospf_disp</B>
! 840: (<I>timer *</I> <B>timer</B>) -- invokes routing table calculation, aging and also <B>area_disp()</B>
! 841: <P>
! 842: <H3>Arguments</H3>
! 843: <P>
! 844: <DL>
! 845: <DT><I>timer *</I> <B>timer</B><DD><P>timer usually called every <B>ospf_proto</B>->tick second, <B>timer</B>->data
! 846: point to <B>ospf_proto</B>
! 847: </DL>
! 848:
! 849:
! 850: <HR><H3>Function</H3>
! 851: <P><I>int</I>
! 852: <B>ospf_import_control</B>
! 853: (<I>struct proto *</I> <B>P</B>, <I>rte **</I> <B>new</B>, <I>ea_list **</I> <B>attrs</B>, <I>struct linpool *</I> <B>pool</B>) -- accept or reject new route from nest's routing table
! 854: <P>
! 855: <H3>Arguments</H3>
! 856: <P>
! 857: <DL>
! 858: <DT><I>struct proto *</I> <B>P</B><DD><P>OSPF protocol instance
! 859: <DT><I>rte **</I> <B>new</B><DD><P>the new route
! 860: <DT><I>ea_list **</I> <B>attrs</B><DD><P>list of attributes
! 861: <DT><I>struct linpool *</I> <B>pool</B><DD><P>pool for allocation of attributes
! 862: </DL>
! 863: <H3>Description</H3>
! 864: <P>Its quite simple. It does not accept our own routes and leaves the decision on
! 865: import to the filters.
! 866:
! 867:
! 868: <HR><H3>Function</H3>
! 869: <P><I>int</I>
! 870: <B>ospf_shutdown</B>
! 871: (<I>struct proto *</I> <B>P</B>) -- Finish of OSPF instance
! 872: <P>
! 873: <H3>Arguments</H3>
! 874: <P>
! 875: <DL>
! 876: <DT><I>struct proto *</I> <B>P</B><DD><P>OSPF protocol instance
! 877: </DL>
! 878: <H3>Description</H3>
! 879: <P>RFC does not define any action that should be taken before router
! 880: shutdown. To make my neighbors react as fast as possible, I send
! 881: them hello packet with empty neighbor list. They should start
! 882: their neighbor state machine with event <I>NEIGHBOR_1WAY</I>.
! 883:
! 884:
! 885: <HR><H3>Function</H3>
! 886: <P><I>int</I>
! 887: <B>ospf_reconfigure</B>
! 888: (<I>struct proto *</I> <B>P</B>, <I>struct proto_config *</I> <B>c</B>) -- reconfiguration hook
! 889: <P>
! 890: <H3>Arguments</H3>
! 891: <P>
! 892: <DL>
! 893: <DT><I>struct proto *</I> <B>P</B><DD><P>current instance of protocol (with old configuration)
! 894: <DT><I>struct proto_config *</I> <B>c</B><DD><P>new configuration requested by user
! 895: </DL>
! 896: <H3>Description</H3>
! 897: <P>This hook tries to be a little bit intelligent. Instance of OSPF
! 898: will survive change of many constants like hello interval,
! 899: password change, addition or deletion of some neighbor on
! 900: nonbroadcast network, cost of interface, etc.
! 901:
! 902:
! 903: <HR><H3>Function</H3>
! 904: <P><I>struct top_hash_entry *</I>
! 905: <B>ospf_install_lsa</B>
! 906: (<I>struct ospf_proto *</I> <B>p</B>, <I>struct ospf_lsa_header *</I> <B>lsa</B>, <I>u32</I> <B>type</B>, <I>u32</I> <B>domain</B>, <I>void *</I> <B>body</B>) -- install new LSA into database
! 907: <P>
! 908: <H3>Arguments</H3>
! 909: <P>
! 910: <DL>
! 911: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
! 912: <DT><I>struct ospf_lsa_header *</I> <B>lsa</B><DD><P>LSA header
! 913: <DT><I>u32</I> <B>type</B><DD><P>type of LSA
! 914: <DT><I>u32</I> <B>domain</B><DD><P>domain of LSA
! 915: <DT><I>void *</I> <B>body</B><DD><P>pointer to LSA body
! 916: </DL>
! 917: <H3>Description</H3>
! 918: <P>This function ensures installing new LSA received in LS update into LSA
! 919: database. Old instance is replaced. Several actions are taken to detect if
! 920: new routing table calculation is necessary. This is described in 13.2 of RFC
! 921: 2328. This function is for received LSA only, locally originated LSAs are
! 922: installed by <B>ospf_originate_lsa()</B>.
! 923: <P>The LSA body in <B>body</B> is expected to be mb_allocated by the caller and its
! 924: ownership is transferred to the LSA entry structure.
! 925:
! 926:
! 927: <HR><H3>Function</H3>
! 928: <P><I>void</I>
! 929: <B>ospf_advance_lsa</B>
! 930: (<I>struct ospf_proto *</I> <B>p</B>, <I>struct top_hash_entry *</I> <B>en</B>, <I>struct ospf_lsa_header *</I> <B>lsa</B>, <I>u32</I> <B>type</B>, <I>u32</I> <B>domain</B>, <I>void *</I> <B>body</B>) -- handle received unexpected self-originated LSA
! 931: <P>
! 932: <H3>Arguments</H3>
! 933: <P>
! 934: <DL>
! 935: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
! 936: <DT><I>struct top_hash_entry *</I> <B>en</B><DD><P>current LSA entry or NULL
! 937: <DT><I>struct ospf_lsa_header *</I> <B>lsa</B><DD><P>new LSA header
! 938: <DT><I>u32</I> <B>type</B><DD><P>type of LSA
! 939: <DT><I>u32</I> <B>domain</B><DD><P>domain of LSA
! 940: <DT><I>void *</I> <B>body</B><DD><P>pointer to LSA body
! 941: </DL>
! 942: <H3>Description</H3>
! 943: <P>This function handles received unexpected self-originated LSA (<B>lsa</B>, <B>body</B>)
! 944: by either advancing sequence number of the local LSA instance (<B>en</B>) and
! 945: propagating it, or installing the received LSA and immediately flushing it
! 946: (if there is no local LSA; i.e., <B>en</B> is NULL or MaxAge).
! 947: <P>The LSA body in <B>body</B> is expected to be mb_allocated by the caller and its
! 948: ownership is transferred to the LSA entry structure or it is freed.
! 949:
! 950:
! 951: <HR><H3>Function</H3>
! 952: <P><I>struct top_hash_entry *</I>
! 953: <B>ospf_originate_lsa</B>
! 954: (<I>struct ospf_proto *</I> <B>p</B>, <I>struct ospf_new_lsa *</I> <B>lsa</B>) -- originate new LSA
! 955: <P>
! 956: <H3>Arguments</H3>
! 957: <P>
! 958: <DL>
! 959: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
! 960: <DT><I>struct ospf_new_lsa *</I> <B>lsa</B><DD><P>New LSA specification
! 961: </DL>
! 962: <H3>Description</H3>
! 963: <P>This function prepares a new LSA, installs it into the LSA database and
! 964: floods it. If the new LSA cannot be originated now (because the old instance
! 965: was originated within MinLSInterval, or because the LSA seqnum is currently
! 966: wrapping), the origination is instead scheduled for later. If the new LSA is
! 967: equivalent to the current LSA, the origination is skipped. In all cases, the
! 968: corresponding LSA entry is returned. The new LSA is based on the LSA
! 969: specification (<B>lsa</B>) and the LSA body from lsab buffer of <B>p</B>, which is
! 970: emptied after the call. The opposite of this function is <B>ospf_flush_lsa()</B>.
! 971:
! 972:
! 973: <HR><H3>Function</H3>
! 974: <P><I>void</I>
! 975: <B>ospf_flush_lsa</B>
! 976: (<I>struct ospf_proto *</I> <B>p</B>, <I>struct top_hash_entry *</I> <B>en</B>) -- flush LSA from OSPF domain
! 977: <P>
! 978: <H3>Arguments</H3>
! 979: <P>
! 980: <DL>
! 981: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
! 982: <DT><I>struct top_hash_entry *</I> <B>en</B><DD><P>LSA entry to flush
! 983: </DL>
! 984: <H3>Description</H3>
! 985: <P>This function flushes <B>en</B> from the OSPF domain by setting its age to
! 986: <I>LSA_MAXAGE</I> and flooding it. That also triggers subsequent events in LSA
! 987: lifecycle leading to removal of the LSA from the LSA database (e.g. the LSA
! 988: content is freed when flushing is acknowledged by neighbors). The function
! 989: does nothing if the LSA is already being flushed. LSA entries are not
! 990: immediately removed when being flushed, the caller may assume that <B>en</B> still
! 991: exists after the call. The function is the opposite of <B>ospf_originate_lsa()</B>
! 992: and is supposed to do the right thing even in cases of postponed
! 993: origination.
! 994:
! 995:
! 996: <HR><H3>Function</H3>
! 997: <P><I>void</I>
! 998: <B>ospf_update_lsadb</B>
! 999: (<I>struct ospf_proto *</I> <B>p</B>) -- update LSA database
! 1000: <P>
! 1001: <H3>Arguments</H3>
! 1002: <P>
! 1003: <DL>
! 1004: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
! 1005: </DL>
! 1006: <H3>Description</H3>
! 1007: <P>This function is periodicaly invoked from <B>ospf_disp()</B>. It does some periodic
! 1008: or postponed processing related to LSA entries. It originates postponed LSAs
! 1009: scheduled by <B>ospf_originate_lsa()</B>, It continues in flushing processes started
! 1010: by <B>ospf_flush_lsa()</B>. It also periodically refreshs locally originated LSAs --
! 1011: when the current instance is older <I>LSREFRESHTIME</I>, a new instance is originated.
! 1012: Finally, it also ages stored LSAs and flushes ones that reached <I>LSA_MAXAGE</I>.
! 1013: <P>The RFC 2328 says that a router should periodically check checksums of all
! 1014: stored LSAs to detect hardware problems. This is not implemented.
! 1015:
! 1016:
! 1017: <HR><H3>Function</H3>
! 1018: <P><I>void</I>
! 1019: <B>ospf_originate_ext_lsa</B>
! 1020: (<I>struct ospf_proto *</I> <B>p</B>, <I>struct ospf_area *</I> <B>oa</B>, <I>ort *</I> <B>nf</B>, <I>u8</I> <B>mode</B>, <I>u32</I> <B>metric</B>, <I>u32</I> <B>ebit</B>, <I>ip_addr</I> <B>fwaddr</B>, <I>u32</I> <B>tag</B>, <I>int</I> <B>pbit</B>) -- new route received from nest and filters
! 1021: <P>
! 1022: <H3>Arguments</H3>
! 1023: <P>
! 1024: <DL>
! 1025: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
! 1026: <DT><I>struct ospf_area *</I> <B>oa</B><DD><P>ospf_area for which LSA is originated
! 1027: <DT><I>ort *</I> <B>nf</B><DD><P>network prefix and mask
! 1028: <DT><I>u8</I> <B>mode</B><DD><P>the mode of the LSA (LSA_M_EXPORT or LSA_M_RTCALC)
! 1029: <DT><I>u32</I> <B>metric</B><DD><P>the metric of a route
! 1030: <DT><I>u32</I> <B>ebit</B><DD><P>E-bit for route metric (bool)
! 1031: <DT><I>ip_addr</I> <B>fwaddr</B><DD><P>the forwarding address
! 1032: <DT><I>u32</I> <B>tag</B><DD><P>the route tag
! 1033: <DT><I>int</I> <B>pbit</B><DD><P>P-bit for NSSA LSAs (bool), ignored for external LSAs
! 1034: </DL>
! 1035: <H3>Description</H3>
! 1036: <P>If I receive a message that new route is installed, I try to originate an
! 1037: external LSA. If <B>oa</B> is an NSSA area, NSSA-LSA is originated instead.
! 1038: <B>oa</B> should not be a stub area. <B>src</B> does not specify whether the LSA
! 1039: is external or NSSA, but it specifies the source of origination -
! 1040: the export from <B>ospf_rt_notify()</B>, or the NSSA-EXT translation.
! 1041:
! 1042:
! 1043: <HR><H3>Function</H3>
! 1044: <P><I>struct top_graph *</I>
! 1045: <B>ospf_top_new</B>
! 1046: (<I>struct ospf_proto *p UNUSED4</I> <B>UNUSED6</B>, <I>pool *</I> <B>pool</B>) -- allocated new topology database
! 1047: <P>
! 1048: <H3>Arguments</H3>
! 1049: <P>
! 1050: <DL>
! 1051: <DT><I>struct ospf_proto *p UNUSED4</I> <B>UNUSED6</B><DD><P>-- undescribed --
! 1052: <DT><I>pool *</I> <B>pool</B><DD><P>pool for allocation
! 1053: </DL>
! 1054: <H3>Description</H3>
! 1055: <P>This dynamically hashed structure is used for keeping LSAs. Mainly it is used
! 1056: for the LSA database of the OSPF protocol, but also for LSA retransmission
! 1057: and request lists of OSPF neighbors.
! 1058:
! 1059:
! 1060: <HR><H3>Function</H3>
! 1061: <P><I>void</I>
! 1062: <B>ospf_neigh_chstate</B>
! 1063: (<I>struct ospf_neighbor *</I> <B>n</B>, <I>u8</I> <B>state</B>) -- handles changes related to new or lod state of neighbor
! 1064: <P>
! 1065: <H3>Arguments</H3>
! 1066: <P>
! 1067: <DL>
! 1068: <DT><I>struct ospf_neighbor *</I> <B>n</B><DD><P>OSPF neighbor
! 1069: <DT><I>u8</I> <B>state</B><DD><P>new state
! 1070: </DL>
! 1071: <H3>Description</H3>
! 1072: <P>Many actions have to be taken acording to a change of state of a neighbor. It
! 1073: starts rxmt timers, call interface state machine etc.
! 1074:
! 1075:
! 1076: <HR><H3>Function</H3>
! 1077: <P><I>void</I>
! 1078: <B>ospf_neigh_sm</B>
! 1079: (<I>struct ospf_neighbor *</I> <B>n</B>, <I>int</I> <B>event</B>) -- ospf neighbor state machine
! 1080: <P>
! 1081: <H3>Arguments</H3>
! 1082: <P>
! 1083: <DL>
! 1084: <DT><I>struct ospf_neighbor *</I> <B>n</B><DD><P>neighor
! 1085: <DT><I>int</I> <B>event</B><DD><P>actual event
! 1086: </DL>
! 1087: <H3>Description</H3>
! 1088: <P>This part implements the neighbor state machine as described in 10.3 of
! 1089: RFC 2328. The only difference is that state <I>NEIGHBOR_ATTEMPT</I> is not
! 1090: used. We discover neighbors on nonbroadcast networks in the
! 1091: same way as on broadcast networks. The only difference is in
! 1092: sending hello packets. These are sent to IPs listed in
! 1093: <B>ospf_iface</B>->nbma_list .
! 1094:
! 1095:
! 1096: <HR><H3>Function</H3>
! 1097: <P><I>void</I>
! 1098: <B>ospf_dr_election</B>
! 1099: (<I>struct ospf_iface *</I> <B>ifa</B>) -- (Backup) Designed Router election
! 1100: <P>
! 1101: <H3>Arguments</H3>
! 1102: <P>
! 1103: <DL>
! 1104: <DT><I>struct ospf_iface *</I> <B>ifa</B><DD><P>actual interface
! 1105: </DL>
! 1106: <H3>Description</H3>
! 1107: <P>When the wait timer fires, it is time to elect (Backup) Designated Router.
! 1108: Structure describing me is added to this list so every electing router has
! 1109: the same list. Backup Designated Router is elected before Designated
! 1110: Router. This process is described in 9.4 of RFC 2328. The function is
! 1111: supposed to be called only from <B>ospf_iface_sm()</B> as a part of the interface
! 1112: state machine.
! 1113:
! 1114:
! 1115: <HR><H3>Function</H3>
! 1116: <P><I>void</I>
! 1117: <B>ospf_iface_chstate</B>
! 1118: (<I>struct ospf_iface *</I> <B>ifa</B>, <I>u8</I> <B>state</B>) -- handle changes of interface state
! 1119: <P>
! 1120: <H3>Arguments</H3>
! 1121: <P>
! 1122: <DL>
! 1123: <DT><I>struct ospf_iface *</I> <B>ifa</B><DD><P>OSPF interface
! 1124: <DT><I>u8</I> <B>state</B><DD><P>new state
! 1125: </DL>
! 1126: <H3>Description</H3>
! 1127: <P>Many actions must be taken according to interface state changes. New network
! 1128: LSAs must be originated, flushed, new multicast sockets to listen for messages for
! 1129: <I>ALLDROUTERS</I> have to be opened, etc.
! 1130:
! 1131:
! 1132: <HR><H3>Function</H3>
! 1133: <P><I>void</I>
! 1134: <B>ospf_iface_sm</B>
! 1135: (<I>struct ospf_iface *</I> <B>ifa</B>, <I>int</I> <B>event</B>) -- OSPF interface state machine
! 1136: <P>
! 1137: <H3>Arguments</H3>
! 1138: <P>
! 1139: <DL>
! 1140: <DT><I>struct ospf_iface *</I> <B>ifa</B><DD><P>OSPF interface
! 1141: <DT><I>int</I> <B>event</B><DD><P>event comming to state machine
! 1142: </DL>
! 1143: <H3>Description</H3>
! 1144: <P>This fully respects 9.3 of RFC 2328 except we have slightly
! 1145: different handling of <I>DOWN</I> and <I>LOOP</I> state. We remove intefaces
! 1146: that are <I>DOWN</I>. <I>DOWN</I> state is used when an interface is waiting
! 1147: for a lock. <I>LOOP</I> state is used when an interface does not have a
! 1148: link.
! 1149:
! 1150:
! 1151: <HR><H3>Function</H3>
! 1152: <P><I>int</I>
! 1153: <B>ospf_rx_hook</B>
! 1154: (<I>sock *</I> <B>sk</B>, <I>uint</I> <B>len</B>)
! 1155: <H3>Arguments</H3>
! 1156: <P>
! 1157: <DL>
! 1158: <DT><I>sock *</I> <B>sk</B><DD><P>socket we received the packet.
! 1159: <DT><I>uint</I> <B>len</B><DD><P>size of the packet
! 1160: </DL>
! 1161: <H3>Description</H3>
! 1162: <P>This is the entry point for messages from neighbors. Many checks (like
! 1163: authentication, checksums, size) are done before the packet is passed to
! 1164: non generic functions.
! 1165:
! 1166:
! 1167: <HR><H3>Function</H3>
! 1168: <P><I>int</I>
! 1169: <B>lsa_validate</B>
! 1170: (<I>struct ospf_lsa_header *</I> <B>lsa</B>, <I>u32</I> <B>lsa_type</B>, <I>int</I> <B>ospf2</B>, <I>void *</I> <B>body</B>) -- check whether given LSA is valid
! 1171: <P>
! 1172: <H3>Arguments</H3>
! 1173: <P>
! 1174: <DL>
! 1175: <DT><I>struct ospf_lsa_header *</I> <B>lsa</B><DD><P>LSA header
! 1176: <DT><I>u32</I> <B>lsa_type</B><DD><P>one of <I>LSA_T_xxx</I>
! 1177: <DT><I>int</I> <B>ospf2</B><DD><P><I>true</I> means OSPF version 2, <I>false</I> means OSPF version 3
! 1178: <DT><I>void *</I> <B>body</B><DD><P>pointer to LSA body
! 1179: </DL>
! 1180: <H3>Description</H3>
! 1181: <P>Checks internal structure of given LSA body (minimal length,
! 1182: consistency). Returns true if valid.
! 1183:
! 1184:
! 1185: <HR><H3>Function</H3>
! 1186: <P><I>void</I>
! 1187: <B>ospf_send_dbdes</B>
! 1188: (<I>struct ospf_proto *</I> <B>p</B>, <I>struct ospf_neighbor *</I> <B>n</B>) -- transmit database description packet
! 1189: <P>
! 1190: <H3>Arguments</H3>
! 1191: <P>
! 1192: <DL>
! 1193: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
! 1194: <DT><I>struct ospf_neighbor *</I> <B>n</B><DD><P>neighbor
! 1195: </DL>
! 1196: <H3>Description</H3>
! 1197: <P>Sending of a database description packet is described in 10.8 of RFC 2328.
! 1198: Reception of each packet is acknowledged in the sequence number of another.
! 1199: When I send a packet to a neighbor I keep a copy in a buffer. If the neighbor
! 1200: does not reply, I don't create a new packet but just send the content
! 1201: of the buffer.
! 1202:
! 1203:
! 1204: <HR><H3>Function</H3>
! 1205: <P><I>void</I>
! 1206: <B>ospf_rt_spf</B>
! 1207: (<I>struct ospf_proto *</I> <B>p</B>) -- calculate internal routes
! 1208: <P>
! 1209: <H3>Arguments</H3>
! 1210: <P>
! 1211: <DL>
! 1212: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
! 1213: </DL>
! 1214: <H3>Description</H3>
! 1215: <P>Calculation of internal paths in an area is described in 16.1 of RFC 2328.
! 1216: It's based on Dijkstra's shortest path tree algorithms.
! 1217: This function is invoked from <B>ospf_disp()</B>.
! 1218:
! 1219: <H2><A NAME="ss5.5">5.5</A> <A HREF="prog.html#toc5.5">Pipe</A>
! 1220: </H2>
! 1221:
! 1222: <P>
! 1223: <P>The Pipe protocol is very simple. It just connects to two routing tables
! 1224: using <B>proto_add_announce_hook()</B> and whenever it receives a <B>rt_notify()</B>
! 1225: about a change in one of the tables, it converts it to a <B>rte_update()</B>
! 1226: in the other one.
! 1227: <P>To avoid pipe loops, Pipe keeps a `being updated' flag in each routing
! 1228: table.
! 1229: <P>A pipe has two announce hooks, the first connected to the main
! 1230: table, the second connected to the peer table. When a new route is
! 1231: announced on the main table, it gets checked by an export filter in
! 1232: ahook 1, and, after that, it is announced to the peer table via
! 1233: <B>rte_update()</B>, an import filter in ahook 2 is called. When a new
! 1234: route is announced in the peer table, an export filter in ahook2
! 1235: and an import filter in ahook 1 are used. Oviously, there is no
! 1236: need in filtering the same route twice, so both import filters are
! 1237: set to accept, while user configured 'import' and 'export' filters
! 1238: are used as export filters in ahooks 2 and 1. Route limits are
! 1239: handled similarly, but on the import side of ahooks.
! 1240: <P>
! 1241: <P>
! 1242: <H2><A NAME="ss5.6">5.6</A> <A HREF="prog.html#toc5.6">Routing Information Protocol (RIP)</A>
! 1243: </H2>
! 1244:
! 1245: <P>
! 1246: <P>The RIP protocol is implemented in two files: <CODE>rip.c</CODE> containing the protocol
! 1247: logic, route management and the protocol glue with BIRD core, and <CODE>packets.c</CODE>
! 1248: handling RIP packet processing, RX, TX and protocol sockets.
! 1249: <P>Each instance of RIP is described by a structure <I>rip_proto</I>, which contains
! 1250: an internal RIP routing table, a list of protocol interfaces and the main
! 1251: timer responsible for RIP routing table cleanup.
! 1252: <P>RIP internal routing table contains incoming and outgoing routes. For each
! 1253: network (represented by structure <I>rip_entry</I>) there is one outgoing route
! 1254: stored directly in <I>rip_entry</I> and an one-way linked list of incoming routes
! 1255: (structures <I>rip_rte</I>). The list contains incoming routes from different RIP
! 1256: neighbors, but only routes with the lowest metric are stored (i.e., all
! 1257: stored incoming routes have the same metric).
! 1258: <P>Note that RIP itself does not select outgoing route, that is done by the core
! 1259: routing table. When a new incoming route is received, it is propagated to the
! 1260: RIP table by <B>rip_update_rte()</B> and possibly stored in the list of incoming
! 1261: routes. Then the change may be propagated to the core by <B>rip_announce_rte()</B>.
! 1262: The core selects the best route and propagate it to RIP by <B>rip_rt_notify()</B>,
! 1263: which updates outgoing route part of <I>rip_entry</I> and possibly triggers route
! 1264: propagation by <B>rip_trigger_update()</B>.
! 1265: <P>RIP interfaces are represented by structures <I>rip_iface</I>. A RIP interface
! 1266: contains a per-interface socket, a list of associated neighbors, interface
! 1267: configuration, and state information related to scheduled interface events
! 1268: and running update sessions. RIP interfaces are added and removed based on
! 1269: core interface notifications.
! 1270: <P>There are two RIP interface events - regular updates and triggered updates.
! 1271: Both are managed from the RIP interface timer (<B>rip_iface_timer()</B>). Regular
! 1272: updates are called at fixed interval and propagate the whole routing table,
! 1273: while triggered updates are scheduled by <B>rip_trigger_update()</B> due to some
! 1274: routing table change and propagate only the routes modified since the time
! 1275: they were scheduled. There are also unicast-destined requested updates, but
! 1276: these are sent directly as a reaction to received RIP request message. The
! 1277: update session is started by <B>rip_send_table()</B>. There may be at most one
! 1278: active update session per interface, as the associated state (including the
! 1279: fib iterator) is stored directly in <I>rip_iface</I> structure.
! 1280: <P>RIP neighbors are represented by structures <I>rip_neighbor</I>. Compared to
! 1281: neighbor handling in other routing protocols, RIP does not have explicit
! 1282: neighbor discovery and adjacency maintenance, which makes the <I>rip_neighbor</I>
! 1283: related code a bit peculiar. RIP neighbors are interlinked with core neighbor
! 1284: structures (<I>neighbor</I>) and use core neighbor notifications to ensure that RIP
! 1285: neighbors are timely removed. RIP neighbors are added based on received route
! 1286: notifications and removed based on core neighbor and RIP interface events.
! 1287: <P>RIP neighbors are linked by RIP routes and use counter to track the number of
! 1288: associated routes, but when these RIP routes timeout, associated RIP neighbor
! 1289: is still alive (with zero counter). When RIP neighbor is removed but still
! 1290: has some associated routes, it is not freed, just changed to detached state
! 1291: (core neighbors and RIP ifaces are unlinked), then during the main timer
! 1292: cleanup phase the associated routes are removed and the <I>rip_neighbor</I>
! 1293: structure is finally freed.
! 1294: <P>Supported standards:
! 1295: - RFC 1058 - RIPv1
! 1296: - RFC 2453 - RIPv2
! 1297: - RFC 2080 - RIPng
! 1298: - RFC 4822 - RIP cryptographic authentication
! 1299: <P>
! 1300: <P><HR><H3>Function</H3>
! 1301: <P><I>void</I>
! 1302: <B>rip_announce_rte</B>
! 1303: (<I>struct rip_proto *</I> <B>p</B>, <I>struct rip_entry *</I> <B>en</B>) -- announce route from RIP routing table to the core
! 1304: <P>
! 1305: <H3>Arguments</H3>
! 1306: <P>
! 1307: <DL>
! 1308: <DT><I>struct rip_proto *</I> <B>p</B><DD><P>RIP instance
! 1309: <DT><I>struct rip_entry *</I> <B>en</B><DD><P>related network
! 1310: </DL>
! 1311: <H3>Description</H3>
! 1312: <P>The function takes a list of incoming routes from <B>en</B>, prepare appropriate
! 1313: <I>rte</I> for the core and propagate it by <B>rte_update()</B>.
! 1314:
! 1315:
! 1316: <HR><H3>Function</H3>
! 1317: <P><I>void</I>
! 1318: <B>rip_update_rte</B>
! 1319: (<I>struct rip_proto *</I> <B>p</B>, <I>ip_addr *</I> <B>prefix</B>, <I>int</I> <B>pxlen</B>, <I>struct rip_rte *</I> <B>new</B>) -- enter a route update to RIP routing table
! 1320: <P>
! 1321: <H3>Arguments</H3>
! 1322: <P>
! 1323: <DL>
! 1324: <DT><I>struct rip_proto *</I> <B>p</B><DD><P>RIP instance
! 1325: <DT><I>ip_addr *</I> <B>prefix</B><DD><P>network prefix
! 1326: <DT><I>int</I> <B>pxlen</B><DD><P>network prefix length
! 1327: <DT><I>struct rip_rte *</I> <B>new</B><DD><P>a <I>rip_rte</I> representing the new route
! 1328: </DL>
! 1329: <H3>Description</H3>
! 1330: <P>The function is called by the RIP packet processing code whenever it receives
! 1331: a reachable route. The appropriate routing table entry is found and the list
! 1332: of incoming routes is updated. Eventually, the change is also propagated to
! 1333: the core by <B>rip_announce_rte()</B>. Note that for unreachable routes,
! 1334: <B>rip_withdraw_rte()</B> should be called instead of <B>rip_update_rte()</B>.
! 1335:
! 1336:
! 1337: <HR><H3>Function</H3>
! 1338: <P><I>void</I>
! 1339: <B>rip_withdraw_rte</B>
! 1340: (<I>struct rip_proto *</I> <B>p</B>, <I>ip_addr *</I> <B>prefix</B>, <I>int</I> <B>pxlen</B>, <I>struct rip_neighbor *</I> <B>from</B>) -- enter a route withdraw to RIP routing table
! 1341: <P>
! 1342: <H3>Arguments</H3>
! 1343: <P>
! 1344: <DL>
! 1345: <DT><I>struct rip_proto *</I> <B>p</B><DD><P>RIP instance
! 1346: <DT><I>ip_addr *</I> <B>prefix</B><DD><P>network prefix
! 1347: <DT><I>int</I> <B>pxlen</B><DD><P>network prefix length
! 1348: <DT><I>struct rip_neighbor *</I> <B>from</B><DD><P>a <I>rip_neighbor</I> propagating the withdraw
! 1349: </DL>
! 1350: <H3>Description</H3>
! 1351: <P>The function is called by the RIP packet processing code whenever it receives
! 1352: an unreachable route. The incoming route for given network from nbr <B>from</B> is
! 1353: removed. Eventually, the change is also propagated by <B>rip_announce_rte()</B>.
! 1354:
! 1355:
! 1356: <HR><H3>Function</H3>
! 1357: <P><I>void</I>
! 1358: <B>rip_timer</B>
! 1359: (<I>timer *</I> <B>t</B>) -- RIP main timer hook
! 1360: <P>
! 1361: <H3>Arguments</H3>
! 1362: <P>
! 1363: <DL>
! 1364: <DT><I>timer *</I> <B>t</B><DD><P>timer
! 1365: </DL>
! 1366: <H3>Description</H3>
! 1367: <P>The RIP main timer is responsible for routing table maintenance. Invalid or
! 1368: expired routes (<I>rip_rte</I>) are removed and garbage collection of stale routing
! 1369: table entries (<I>rip_entry</I>) is done. Changes are propagated to core tables,
! 1370: route reload is also done here. Note that garbage collection uses a maximal
! 1371: GC time, while interfaces maintain an illusion of per-interface GC times in
! 1372: <B>rip_send_response()</B>.
! 1373: <P>Keeping incoming routes and the selected outgoing route are two independent
! 1374: functions, therefore after garbage collection some entries now considered
! 1375: invalid (RIP_ENTRY_DUMMY) still may have non-empty list of incoming routes,
! 1376: while some valid entries (representing an outgoing route) may have that list
! 1377: empty.
! 1378: <P>The main timer is not scheduled periodically but it uses the time of the
! 1379: current next event and the minimal interval of any possible event to compute
! 1380: the time of the next run.
! 1381:
! 1382:
! 1383: <HR><H3>Function</H3>
! 1384: <P><I>void</I>
! 1385: <B>rip_iface_timer</B>
! 1386: (<I>timer *</I> <B>t</B>) -- RIP interface timer hook
! 1387: <P>
! 1388: <H3>Arguments</H3>
! 1389: <P>
! 1390: <DL>
! 1391: <DT><I>timer *</I> <B>t</B><DD><P>timer
! 1392: </DL>
! 1393: <H3>Description</H3>
! 1394: <P>RIP interface timers are responsible for scheduling both regular and
! 1395: triggered updates. Fixed, delay-independent period is used for regular
! 1396: updates, while minimal separating interval is enforced for triggered updates.
! 1397: The function also ensures that a new update is not started when the old one
! 1398: is still running.
! 1399:
! 1400:
! 1401: <HR><H3>Function</H3>
! 1402: <P><I>void</I>
! 1403: <B>rip_send_table</B>
! 1404: (<I>struct rip_proto *</I> <B>p</B>, <I>struct rip_iface *</I> <B>ifa</B>, <I>ip_addr</I> <B>addr</B>, <I>bird_clock_t</I> <B>changed</B>) -- RIP interface timer hook
! 1405: <P>
! 1406: <H3>Arguments</H3>
! 1407: <P>
! 1408: <DL>
! 1409: <DT><I>struct rip_proto *</I> <B>p</B><DD><P>RIP instance
! 1410: <DT><I>struct rip_iface *</I> <B>ifa</B><DD><P>RIP interface
! 1411: <DT><I>ip_addr</I> <B>addr</B><DD><P>destination IP address
! 1412: <DT><I>bird_clock_t</I> <B>changed</B><DD><P>time limit for triggered updates
! 1413: </DL>
! 1414: <H3>Description</H3>
! 1415: <P>The function activates an update session and starts sending routing update
! 1416: packets (using <B>rip_send_response()</B>). The session may be finished during the
! 1417: call or may continue in <B>rip_tx_hook()</B> until all appropriate routes are
! 1418: transmitted. Note that there may be at most one active update session per
! 1419: interface, the function will terminate the old active session before
! 1420: activating the new one.
! 1421:
! 1422: <H2><A NAME="ss5.7">5.7</A> <A HREF="prog.html#toc5.7">Router Advertisements</A>
! 1423: </H2>
! 1424:
! 1425: <P>
! 1426: <P>The RAdv protocol is implemented in two files: <CODE>radv.c</CODE> containing
! 1427: the interface with BIRD core and the protocol logic and <CODE>packets.c</CODE>
! 1428: handling low level protocol stuff (RX, TX and packet formats).
! 1429: The protocol does not export any routes.
! 1430: <P>The RAdv is structured in the usual way - for each handled interface
! 1431: there is a structure <I>radv_iface</I> that contains a state related to
! 1432: that interface together with its resources (a socket, a timer).
! 1433: There is also a prepared RA stored in a TX buffer of the socket
! 1434: associated with an iface. These iface structures are created
! 1435: and removed according to iface events from BIRD core handled by
! 1436: <B>radv_if_notify()</B> callback.
! 1437: <P>The main logic of RAdv consists of two functions:
! 1438: <B>radv_iface_notify()</B>, which processes asynchronous events (specified
! 1439: by RA_EV_* codes), and <B>radv_timer()</B>, which triggers sending RAs and
! 1440: computes the next timeout.
! 1441: <P>The RAdv protocol could receive routes (through
! 1442: <B>radv_import_control()</B> and <B>radv_rt_notify()</B>), but only the
! 1443: configured trigger route is tracked (in <I>active</I> var). When a radv
! 1444: protocol is reconfigured, the connected routing table is examined
! 1445: (in <B>radv_check_active()</B>) to have proper <I>active</I> value in case of
! 1446: the specified trigger prefix was changed.
! 1447: <P>Supported standards:
! 1448: - RFC 4861 - main RA standard
! 1449: - RFC 6106 - DNS extensions (RDDNS, DNSSL)
! 1450: - RFC 4191 (partial) - Default Router Preference
! 1451: <P>
! 1452: <P>
! 1453: <H2><A NAME="ss5.8">5.8</A> <A HREF="prog.html#toc5.8">Static</A>
! 1454: </H2>
! 1455:
! 1456: <P>
! 1457: <P>The Static protocol is implemented in a straightforward way. It keeps
! 1458: two lists of static routes: one containing interface routes and one
! 1459: holding the remaining ones. Interface routes are inserted and removed according
! 1460: to interface events received from the core via the <B>if_notify()</B> hook. Routes
! 1461: pointing to a neighboring router use a sticky node in the neighbor cache
! 1462: to be notified about gaining or losing the neighbor. Special
! 1463: routes like black holes or rejects are inserted all the time.
! 1464: <P>Multipath routes are tricky. Because these routes depends on
! 1465: several neighbors we need to integrate that to the neighbor
! 1466: notification handling, we use dummy static_route nodes, one for
! 1467: each nexthop. Therefore, a multipath route consists of a master
! 1468: static_route node (of dest RTD_MULTIPATH), which specifies prefix
! 1469: and is used in most circumstances, and a list of dummy static_route
! 1470: nodes (of dest RTD_NONE), which stores info about nexthops and are
! 1471: connected to neighbor entries and neighbor notifications. Dummy
! 1472: nodes are chained using mp_next, they aren't in other_routes list,
! 1473: and abuse some fields (masklen, if_name) for other purposes.
! 1474: <P>The only other thing worth mentioning is that when asked for reconfiguration,
! 1475: Static not only compares the two configurations, but it also calculates
! 1476: difference between the lists of static routes and it just inserts the
! 1477: newly added routes and removes the obsolete ones.
! 1478: <P>
! 1479: <P>
! 1480: <H2><A NAME="ss5.9">5.9</A> <A HREF="prog.html#toc5.9">Direct</A>
! 1481: </H2>
! 1482:
! 1483: <P>
! 1484: <P>The Direct protocol works by converting all <B>ifa_notify()</B> events it receives
! 1485: to <B>rte_update()</B> calls for the corresponding network.
! 1486: <P>
! 1487: <P>
! 1488: <P>
! 1489: <HR>
! 1490: <A HREF="prog-6.html">Next</A>
! 1491: <A HREF="prog-4.html">Previous</A>
! 1492: <A HREF="prog.html#toc5">Contents</A>
! 1493: </BODY>
! 1494: </HTML>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog-5.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