Annotation of embedaddon/bird/doc/prog-5.html, revision 1.1.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 &gt;= 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>-&gt;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 &gt; Keepalive &gt; Open &gt; 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>-&gt;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>-&gt;tick second, <B>timer</B>-&gt;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>-&gt;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>