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