Annotation of embedaddon/bird/doc/prog-5.html, revision 1.1.1.2
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>
1.1.1.2 ! misho 727: <DT><I>struct bgp_proto *</I> <B>p</B><DD><P>BGP instance (or NULL)
1.1 misho 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:
1.1.1.2 ! misho 758: <H2><A NAME="ss5.4">5.4</A> <A HREF="prog.html#toc5.4">Multi-Threaded Routing Toolkit (MRT) protocol</A>
! 759: </H2>
! 760:
! 761: <P>
! 762: <P>The MRT protocol is implemented in just one file: <CODE>mrt.c</CODE>. It contains of
! 763: several parts: Generic functions for preparing MRT messages in a buffer,
! 764: functions for MRT table dump (called from timer or CLI), functions for MRT
! 765: BGP4MP dump (called from BGP), and the usual protocol glue. For the MRT table
! 766: dump, the key structure is struct mrt_table_dump_state, which contains all
! 767: necessary data and created when the MRT dump cycle is started for the
! 768: duration of the MRT dump. The MBGP4MP dump is currently not bound to MRT
! 769: protocol instance and uses the config->mrtdump_file fd.
! 770: <P>The protocol is simple, just periodically scans routing table and export it
! 771: to a file. It does not use the regular update mechanism, but a direct access
! 772: in order to handle iteration through multiple routing tables. The table dump
! 773: needs to dump all peers first and then use indexes to address the peers, we
! 774: use a hash table (<B>peer_hash</B>) to find peer index based on BGP protocol key
! 775: attributes.
! 776: <P>One thing worth documenting is the locking. During processing, the currently
! 777: processed table (<B>table</B> field in the state structure) is locked and also the
! 778: explicitly named table is locked (<B>table_ptr</B> field in the state structure) if
! 779: specified. Between dumps no table is locked. Also the current config is
! 780: locked (by <B>config_add_obstacle()</B>) during table dumps as some data (strings,
! 781: filters) are shared from the config and the running table dump may be
! 782: interrupted by reconfiguration.
! 783: <P>Supported standards:
! 784: - RFC 6396 - MRT format standard
! 785: - RFC 8050 - ADD_PATH extension
! 786: <P>
! 787: <P>
! 788: <H2><A NAME="ss5.5">5.5</A> <A HREF="prog.html#toc5.5">Open Shortest Path First (OSPF)</A>
1.1 misho 789: </H2>
790:
791: <P>
792: <P>The OSPF protocol is quite complicated and its complex implemenation is split
793: to many files. In <CODE>ospf.c</CODE>, you will find mainly the interface for
794: communication with the core (e.g., reconfiguration hooks, shutdown and
795: initialisation and so on). File <CODE>iface.c</CODE> contains the interface state
796: machine and functions for allocation and deallocation of OSPF's interface
797: data structures. Source <CODE>neighbor.c</CODE> includes the neighbor state machine and
798: functions for election of Designated Router and Backup Designated router. In
799: <CODE>packet.c</CODE>, you will find various functions for sending and receiving generic
800: OSPF packets. There are also routines for authentication and checksumming.
801: In <CODE>hello.c</CODE>, there are routines for sending and receiving of hello packets
802: as well as functions for maintaining wait times and the inactivity timer.
803: Files <CODE>lsreq.c</CODE>, <CODE>lsack.c</CODE>, <CODE>dbdes.c</CODE> contain functions for sending and
804: receiving of link-state requests, link-state acknowledgements and database
805: descriptions respectively. In <CODE>lsupd.c</CODE>, there are functions for sending and
806: receiving of link-state updates and also the flooding algorithm. Source
807: <CODE>topology.c</CODE> is a place where routines for searching LSAs in the link-state
808: database, adding and deleting them reside, there also are functions for
809: originating of various types of LSAs (router LSA, net LSA, external LSA).
810: File <CODE>rt.c</CODE> contains routines for calculating the routing table. <CODE>lsalib.c</CODE>
811: is a set of various functions for working with the LSAs (endianity
812: conversions, calculation of checksum etc.).
813: <P>One instance of the protocol is able to hold LSA databases for multiple OSPF
814: areas, to exchange routing information between multiple neighbors and to
815: calculate the routing tables. The core structure is <I>ospf_proto</I> to which
816: multiple <I>ospf_area</I> and <I>ospf_iface</I> structures are connected. <I>ospf_proto</I> is
817: also connected to <I>top_hash_graph</I> which is a dynamic hashing structure that
818: describes the link-state database. It allows fast search, addition and
819: deletion. Each LSA is kept in two pieces: header and body. Both of them are
820: kept in the endianity of the CPU.
821: <P>In OSPFv2 specification, it is implied that there is one IP prefix for each
822: physical network/interface (unless it is an ptp link). But in modern systems,
823: there might be more independent IP prefixes associated with an interface. To
824: handle this situation, we have one <I>ospf_iface</I> for each active IP prefix
825: (instead for each active iface); This behaves like virtual interface for the
826: purpose of OSPF. If we receive packet, we associate it with a proper virtual
827: interface mainly according to its source address.
828: <P>OSPF keeps one socket per <I>ospf_iface</I>. This allows us (compared to one socket
829: approach) to evade problems with a limit of multicast groups per socket and
830: with sending multicast packets to appropriate interface in a portable way.
831: The socket is associated with underlying physical iface and should not
832: receive packets received on other ifaces (unfortunately, this is not true on
833: BSD). Generally, one packet can be received by more sockets (for example, if
834: there are more <I>ospf_iface</I> on one physical iface), therefore we explicitly
835: filter received packets according to src/dst IP address and received iface.
836: <P>Vlinks are implemented using particularly degenerate form of <I>ospf_iface</I>,
837: which has several exceptions: it does not have its iface or socket (it copies
838: these from 'parent' <I>ospf_iface</I>) and it is present in iface list even when
839: down (it is not freed in <B>ospf_iface_down()</B>).
840: <P>The heart beat of ospf is <B>ospf_disp()</B>. It is called at regular intervals
841: (<I>ospf_proto</I>->tick). It is responsible for aging and flushing of LSAs in the
842: database, updating topology information in LSAs and for routing table
843: calculation.
844: <P>To every <I>ospf_iface</I>, we connect one or more <I>ospf_neighbor</I>'s -- a structure
845: containing many timers and queues for building adjacency and for exchange of
846: routing messages.
847: <P>BIRD's OSPF implementation respects RFC2328 in every detail, but some of
848: internal algorithms do differ. The RFC recommends making a snapshot of the
849: link-state database when a new adjacency is forming and sending the database
850: description packets based on the information in this snapshot. The database
851: can be quite large in some networks, so rather we walk through a <I>slist</I>
852: structure which allows us to continue even if the actual LSA we were working
853: with is deleted. New LSAs are added at the tail of this <I>slist</I>.
854: <P>We also do not keep a separate OSPF routing table, because the core helps us
855: by being able to recognize when a route is updated to an identical one and it
856: suppresses the update automatically. Due to this, we can flush all the routes
857: we have recalculated and also those we have deleted to the core's routing
858: table and the core will take care of the rest. This simplifies the process
859: and conserves memory.
860: <P>Supported standards:
861: - RFC 2328 - main OSPFv2 standard
862: - RFC 5340 - main OSPFv3 standard
863: - RFC 3101 - OSPFv2 NSSA areas
864: - RFC 6549 - OSPFv2 multi-instance extensions
865: - RFC 6987 - OSPF stub router advertisement
866: <P>
867: <P><HR><H3>Function</H3>
868: <P><I>void</I>
869: <B>ospf_disp</B>
870: (<I>timer *</I> <B>timer</B>) -- invokes routing table calculation, aging and also <B>area_disp()</B>
871: <P>
872: <H3>Arguments</H3>
873: <P>
874: <DL>
875: <DT><I>timer *</I> <B>timer</B><DD><P>timer usually called every <B>ospf_proto</B>->tick second, <B>timer</B>->data
876: point to <B>ospf_proto</B>
877: </DL>
878:
879:
880: <HR><H3>Function</H3>
881: <P><I>int</I>
882: <B>ospf_import_control</B>
883: (<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
884: <P>
885: <H3>Arguments</H3>
886: <P>
887: <DL>
888: <DT><I>struct proto *</I> <B>P</B><DD><P>OSPF protocol instance
889: <DT><I>rte **</I> <B>new</B><DD><P>the new route
890: <DT><I>ea_list **</I> <B>attrs</B><DD><P>list of attributes
891: <DT><I>struct linpool *</I> <B>pool</B><DD><P>pool for allocation of attributes
892: </DL>
893: <H3>Description</H3>
894: <P>Its quite simple. It does not accept our own routes and leaves the decision on
895: import to the filters.
896:
897:
898: <HR><H3>Function</H3>
899: <P><I>int</I>
900: <B>ospf_shutdown</B>
901: (<I>struct proto *</I> <B>P</B>) -- Finish of OSPF instance
902: <P>
903: <H3>Arguments</H3>
904: <P>
905: <DL>
906: <DT><I>struct proto *</I> <B>P</B><DD><P>OSPF protocol instance
907: </DL>
908: <H3>Description</H3>
909: <P>RFC does not define any action that should be taken before router
910: shutdown. To make my neighbors react as fast as possible, I send
911: them hello packet with empty neighbor list. They should start
912: their neighbor state machine with event <I>NEIGHBOR_1WAY</I>.
913:
914:
915: <HR><H3>Function</H3>
916: <P><I>int</I>
917: <B>ospf_reconfigure</B>
918: (<I>struct proto *</I> <B>P</B>, <I>struct proto_config *</I> <B>c</B>) -- reconfiguration hook
919: <P>
920: <H3>Arguments</H3>
921: <P>
922: <DL>
923: <DT><I>struct proto *</I> <B>P</B><DD><P>current instance of protocol (with old configuration)
924: <DT><I>struct proto_config *</I> <B>c</B><DD><P>new configuration requested by user
925: </DL>
926: <H3>Description</H3>
927: <P>This hook tries to be a little bit intelligent. Instance of OSPF
928: will survive change of many constants like hello interval,
929: password change, addition or deletion of some neighbor on
930: nonbroadcast network, cost of interface, etc.
931:
932:
933: <HR><H3>Function</H3>
934: <P><I>struct top_hash_entry *</I>
935: <B>ospf_install_lsa</B>
936: (<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
937: <P>
938: <H3>Arguments</H3>
939: <P>
940: <DL>
941: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
942: <DT><I>struct ospf_lsa_header *</I> <B>lsa</B><DD><P>LSA header
943: <DT><I>u32</I> <B>type</B><DD><P>type of LSA
944: <DT><I>u32</I> <B>domain</B><DD><P>domain of LSA
945: <DT><I>void *</I> <B>body</B><DD><P>pointer to LSA body
946: </DL>
947: <H3>Description</H3>
948: <P>This function ensures installing new LSA received in LS update into LSA
949: database. Old instance is replaced. Several actions are taken to detect if
950: new routing table calculation is necessary. This is described in 13.2 of RFC
951: 2328. This function is for received LSA only, locally originated LSAs are
952: installed by <B>ospf_originate_lsa()</B>.
953: <P>The LSA body in <B>body</B> is expected to be mb_allocated by the caller and its
954: ownership is transferred to the LSA entry structure.
955:
956:
957: <HR><H3>Function</H3>
958: <P><I>void</I>
959: <B>ospf_advance_lsa</B>
960: (<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
961: <P>
962: <H3>Arguments</H3>
963: <P>
964: <DL>
965: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
966: <DT><I>struct top_hash_entry *</I> <B>en</B><DD><P>current LSA entry or NULL
967: <DT><I>struct ospf_lsa_header *</I> <B>lsa</B><DD><P>new LSA header
968: <DT><I>u32</I> <B>type</B><DD><P>type of LSA
969: <DT><I>u32</I> <B>domain</B><DD><P>domain of LSA
970: <DT><I>void *</I> <B>body</B><DD><P>pointer to LSA body
971: </DL>
972: <H3>Description</H3>
973: <P>This function handles received unexpected self-originated LSA (<B>lsa</B>, <B>body</B>)
974: by either advancing sequence number of the local LSA instance (<B>en</B>) and
975: propagating it, or installing the received LSA and immediately flushing it
976: (if there is no local LSA; i.e., <B>en</B> is NULL or MaxAge).
977: <P>The LSA body in <B>body</B> is expected to be mb_allocated by the caller and its
978: ownership is transferred to the LSA entry structure or it is freed.
979:
980:
981: <HR><H3>Function</H3>
982: <P><I>struct top_hash_entry *</I>
983: <B>ospf_originate_lsa</B>
984: (<I>struct ospf_proto *</I> <B>p</B>, <I>struct ospf_new_lsa *</I> <B>lsa</B>) -- originate new LSA
985: <P>
986: <H3>Arguments</H3>
987: <P>
988: <DL>
989: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
990: <DT><I>struct ospf_new_lsa *</I> <B>lsa</B><DD><P>New LSA specification
991: </DL>
992: <H3>Description</H3>
993: <P>This function prepares a new LSA, installs it into the LSA database and
994: floods it. If the new LSA cannot be originated now (because the old instance
995: was originated within MinLSInterval, or because the LSA seqnum is currently
996: wrapping), the origination is instead scheduled for later. If the new LSA is
997: equivalent to the current LSA, the origination is skipped. In all cases, the
998: corresponding LSA entry is returned. The new LSA is based on the LSA
999: specification (<B>lsa</B>) and the LSA body from lsab buffer of <B>p</B>, which is
1000: emptied after the call. The opposite of this function is <B>ospf_flush_lsa()</B>.
1001:
1002:
1003: <HR><H3>Function</H3>
1004: <P><I>void</I>
1005: <B>ospf_flush_lsa</B>
1006: (<I>struct ospf_proto *</I> <B>p</B>, <I>struct top_hash_entry *</I> <B>en</B>) -- flush LSA from OSPF domain
1007: <P>
1008: <H3>Arguments</H3>
1009: <P>
1010: <DL>
1011: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
1012: <DT><I>struct top_hash_entry *</I> <B>en</B><DD><P>LSA entry to flush
1013: </DL>
1014: <H3>Description</H3>
1015: <P>This function flushes <B>en</B> from the OSPF domain by setting its age to
1016: <I>LSA_MAXAGE</I> and flooding it. That also triggers subsequent events in LSA
1017: lifecycle leading to removal of the LSA from the LSA database (e.g. the LSA
1018: content is freed when flushing is acknowledged by neighbors). The function
1019: does nothing if the LSA is already being flushed. LSA entries are not
1020: immediately removed when being flushed, the caller may assume that <B>en</B> still
1021: exists after the call. The function is the opposite of <B>ospf_originate_lsa()</B>
1022: and is supposed to do the right thing even in cases of postponed
1023: origination.
1024:
1025:
1026: <HR><H3>Function</H3>
1027: <P><I>void</I>
1028: <B>ospf_update_lsadb</B>
1029: (<I>struct ospf_proto *</I> <B>p</B>) -- update LSA database
1030: <P>
1031: <H3>Arguments</H3>
1032: <P>
1033: <DL>
1034: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
1035: </DL>
1036: <H3>Description</H3>
1037: <P>This function is periodicaly invoked from <B>ospf_disp()</B>. It does some periodic
1038: or postponed processing related to LSA entries. It originates postponed LSAs
1039: scheduled by <B>ospf_originate_lsa()</B>, It continues in flushing processes started
1040: by <B>ospf_flush_lsa()</B>. It also periodically refreshs locally originated LSAs --
1041: when the current instance is older <I>LSREFRESHTIME</I>, a new instance is originated.
1042: Finally, it also ages stored LSAs and flushes ones that reached <I>LSA_MAXAGE</I>.
1043: <P>The RFC 2328 says that a router should periodically check checksums of all
1044: stored LSAs to detect hardware problems. This is not implemented.
1045:
1046:
1047: <HR><H3>Function</H3>
1048: <P><I>void</I>
1049: <B>ospf_originate_ext_lsa</B>
1050: (<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
1051: <P>
1052: <H3>Arguments</H3>
1053: <P>
1054: <DL>
1055: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
1056: <DT><I>struct ospf_area *</I> <B>oa</B><DD><P>ospf_area for which LSA is originated
1057: <DT><I>ort *</I> <B>nf</B><DD><P>network prefix and mask
1058: <DT><I>u8</I> <B>mode</B><DD><P>the mode of the LSA (LSA_M_EXPORT or LSA_M_RTCALC)
1059: <DT><I>u32</I> <B>metric</B><DD><P>the metric of a route
1060: <DT><I>u32</I> <B>ebit</B><DD><P>E-bit for route metric (bool)
1061: <DT><I>ip_addr</I> <B>fwaddr</B><DD><P>the forwarding address
1062: <DT><I>u32</I> <B>tag</B><DD><P>the route tag
1063: <DT><I>int</I> <B>pbit</B><DD><P>P-bit for NSSA LSAs (bool), ignored for external LSAs
1064: </DL>
1065: <H3>Description</H3>
1066: <P>If I receive a message that new route is installed, I try to originate an
1067: external LSA. If <B>oa</B> is an NSSA area, NSSA-LSA is originated instead.
1068: <B>oa</B> should not be a stub area. <B>src</B> does not specify whether the LSA
1069: is external or NSSA, but it specifies the source of origination -
1070: the export from <B>ospf_rt_notify()</B>, or the NSSA-EXT translation.
1071:
1072:
1073: <HR><H3>Function</H3>
1074: <P><I>struct top_graph *</I>
1075: <B>ospf_top_new</B>
1076: (<I>struct ospf_proto *p UNUSED4</I> <B>UNUSED6</B>, <I>pool *</I> <B>pool</B>) -- allocated new topology database
1077: <P>
1078: <H3>Arguments</H3>
1079: <P>
1080: <DL>
1081: <DT><I>struct ospf_proto *p UNUSED4</I> <B>UNUSED6</B><DD><P>-- undescribed --
1082: <DT><I>pool *</I> <B>pool</B><DD><P>pool for allocation
1083: </DL>
1084: <H3>Description</H3>
1085: <P>This dynamically hashed structure is used for keeping LSAs. Mainly it is used
1086: for the LSA database of the OSPF protocol, but also for LSA retransmission
1087: and request lists of OSPF neighbors.
1088:
1089:
1090: <HR><H3>Function</H3>
1091: <P><I>void</I>
1092: <B>ospf_neigh_chstate</B>
1093: (<I>struct ospf_neighbor *</I> <B>n</B>, <I>u8</I> <B>state</B>) -- handles changes related to new or lod state of neighbor
1094: <P>
1095: <H3>Arguments</H3>
1096: <P>
1097: <DL>
1098: <DT><I>struct ospf_neighbor *</I> <B>n</B><DD><P>OSPF neighbor
1099: <DT><I>u8</I> <B>state</B><DD><P>new state
1100: </DL>
1101: <H3>Description</H3>
1102: <P>Many actions have to be taken acording to a change of state of a neighbor. It
1103: starts rxmt timers, call interface state machine etc.
1104:
1105:
1106: <HR><H3>Function</H3>
1107: <P><I>void</I>
1108: <B>ospf_neigh_sm</B>
1109: (<I>struct ospf_neighbor *</I> <B>n</B>, <I>int</I> <B>event</B>) -- ospf neighbor state machine
1110: <P>
1111: <H3>Arguments</H3>
1112: <P>
1113: <DL>
1114: <DT><I>struct ospf_neighbor *</I> <B>n</B><DD><P>neighor
1115: <DT><I>int</I> <B>event</B><DD><P>actual event
1116: </DL>
1117: <H3>Description</H3>
1118: <P>This part implements the neighbor state machine as described in 10.3 of
1119: RFC 2328. The only difference is that state <I>NEIGHBOR_ATTEMPT</I> is not
1120: used. We discover neighbors on nonbroadcast networks in the
1121: same way as on broadcast networks. The only difference is in
1122: sending hello packets. These are sent to IPs listed in
1123: <B>ospf_iface</B>->nbma_list .
1124:
1125:
1126: <HR><H3>Function</H3>
1127: <P><I>void</I>
1128: <B>ospf_dr_election</B>
1129: (<I>struct ospf_iface *</I> <B>ifa</B>) -- (Backup) Designed Router election
1130: <P>
1131: <H3>Arguments</H3>
1132: <P>
1133: <DL>
1134: <DT><I>struct ospf_iface *</I> <B>ifa</B><DD><P>actual interface
1135: </DL>
1136: <H3>Description</H3>
1137: <P>When the wait timer fires, it is time to elect (Backup) Designated Router.
1138: Structure describing me is added to this list so every electing router has
1139: the same list. Backup Designated Router is elected before Designated
1140: Router. This process is described in 9.4 of RFC 2328. The function is
1141: supposed to be called only from <B>ospf_iface_sm()</B> as a part of the interface
1142: state machine.
1143:
1144:
1145: <HR><H3>Function</H3>
1146: <P><I>void</I>
1147: <B>ospf_iface_chstate</B>
1148: (<I>struct ospf_iface *</I> <B>ifa</B>, <I>u8</I> <B>state</B>) -- handle changes of interface state
1149: <P>
1150: <H3>Arguments</H3>
1151: <P>
1152: <DL>
1153: <DT><I>struct ospf_iface *</I> <B>ifa</B><DD><P>OSPF interface
1154: <DT><I>u8</I> <B>state</B><DD><P>new state
1155: </DL>
1156: <H3>Description</H3>
1157: <P>Many actions must be taken according to interface state changes. New network
1158: LSAs must be originated, flushed, new multicast sockets to listen for messages for
1159: <I>ALLDROUTERS</I> have to be opened, etc.
1160:
1161:
1162: <HR><H3>Function</H3>
1163: <P><I>void</I>
1164: <B>ospf_iface_sm</B>
1165: (<I>struct ospf_iface *</I> <B>ifa</B>, <I>int</I> <B>event</B>) -- OSPF interface state machine
1166: <P>
1167: <H3>Arguments</H3>
1168: <P>
1169: <DL>
1170: <DT><I>struct ospf_iface *</I> <B>ifa</B><DD><P>OSPF interface
1171: <DT><I>int</I> <B>event</B><DD><P>event comming to state machine
1172: </DL>
1173: <H3>Description</H3>
1174: <P>This fully respects 9.3 of RFC 2328 except we have slightly
1175: different handling of <I>DOWN</I> and <I>LOOP</I> state. We remove intefaces
1176: that are <I>DOWN</I>. <I>DOWN</I> state is used when an interface is waiting
1177: for a lock. <I>LOOP</I> state is used when an interface does not have a
1178: link.
1179:
1180:
1181: <HR><H3>Function</H3>
1182: <P><I>int</I>
1183: <B>ospf_rx_hook</B>
1184: (<I>sock *</I> <B>sk</B>, <I>uint</I> <B>len</B>)
1185: <H3>Arguments</H3>
1186: <P>
1187: <DL>
1188: <DT><I>sock *</I> <B>sk</B><DD><P>socket we received the packet.
1189: <DT><I>uint</I> <B>len</B><DD><P>size of the packet
1190: </DL>
1191: <H3>Description</H3>
1192: <P>This is the entry point for messages from neighbors. Many checks (like
1193: authentication, checksums, size) are done before the packet is passed to
1194: non generic functions.
1195:
1196:
1197: <HR><H3>Function</H3>
1198: <P><I>int</I>
1199: <B>lsa_validate</B>
1200: (<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
1201: <P>
1202: <H3>Arguments</H3>
1203: <P>
1204: <DL>
1205: <DT><I>struct ospf_lsa_header *</I> <B>lsa</B><DD><P>LSA header
1206: <DT><I>u32</I> <B>lsa_type</B><DD><P>one of <I>LSA_T_xxx</I>
1207: <DT><I>int</I> <B>ospf2</B><DD><P><I>true</I> means OSPF version 2, <I>false</I> means OSPF version 3
1208: <DT><I>void *</I> <B>body</B><DD><P>pointer to LSA body
1209: </DL>
1210: <H3>Description</H3>
1211: <P>Checks internal structure of given LSA body (minimal length,
1212: consistency). Returns true if valid.
1213:
1214:
1215: <HR><H3>Function</H3>
1216: <P><I>void</I>
1217: <B>ospf_send_dbdes</B>
1218: (<I>struct ospf_proto *</I> <B>p</B>, <I>struct ospf_neighbor *</I> <B>n</B>) -- transmit database description packet
1219: <P>
1220: <H3>Arguments</H3>
1221: <P>
1222: <DL>
1223: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
1224: <DT><I>struct ospf_neighbor *</I> <B>n</B><DD><P>neighbor
1225: </DL>
1226: <H3>Description</H3>
1227: <P>Sending of a database description packet is described in 10.8 of RFC 2328.
1228: Reception of each packet is acknowledged in the sequence number of another.
1229: When I send a packet to a neighbor I keep a copy in a buffer. If the neighbor
1230: does not reply, I don't create a new packet but just send the content
1231: of the buffer.
1232:
1233:
1234: <HR><H3>Function</H3>
1235: <P><I>void</I>
1236: <B>ospf_rt_spf</B>
1237: (<I>struct ospf_proto *</I> <B>p</B>) -- calculate internal routes
1238: <P>
1239: <H3>Arguments</H3>
1240: <P>
1241: <DL>
1242: <DT><I>struct ospf_proto *</I> <B>p</B><DD><P>OSPF protocol instance
1243: </DL>
1244: <H3>Description</H3>
1245: <P>Calculation of internal paths in an area is described in 16.1 of RFC 2328.
1246: It's based on Dijkstra's shortest path tree algorithms.
1247: This function is invoked from <B>ospf_disp()</B>.
1248:
1.1.1.2 ! misho 1249: <H2><A NAME="ss5.6">5.6</A> <A HREF="prog.html#toc5.6">Pipe</A>
1.1 misho 1250: </H2>
1251:
1252: <P>
1253: <P>The Pipe protocol is very simple. It just connects to two routing tables
1254: using <B>proto_add_announce_hook()</B> and whenever it receives a <B>rt_notify()</B>
1255: about a change in one of the tables, it converts it to a <B>rte_update()</B>
1256: in the other one.
1257: <P>To avoid pipe loops, Pipe keeps a `being updated' flag in each routing
1258: table.
1259: <P>A pipe has two announce hooks, the first connected to the main
1260: table, the second connected to the peer table. When a new route is
1261: announced on the main table, it gets checked by an export filter in
1262: ahook 1, and, after that, it is announced to the peer table via
1263: <B>rte_update()</B>, an import filter in ahook 2 is called. When a new
1264: route is announced in the peer table, an export filter in ahook2
1265: and an import filter in ahook 1 are used. Oviously, there is no
1266: need in filtering the same route twice, so both import filters are
1267: set to accept, while user configured 'import' and 'export' filters
1268: are used as export filters in ahooks 2 and 1. Route limits are
1269: handled similarly, but on the import side of ahooks.
1270: <P>
1271: <P>
1.1.1.2 ! misho 1272: <H2><A NAME="ss5.7">5.7</A> <A HREF="prog.html#toc5.7">Routing Information Protocol (RIP)</A>
1.1 misho 1273: </H2>
1274:
1275: <P>
1276: <P>The RIP protocol is implemented in two files: <CODE>rip.c</CODE> containing the protocol
1277: logic, route management and the protocol glue with BIRD core, and <CODE>packets.c</CODE>
1278: handling RIP packet processing, RX, TX and protocol sockets.
1279: <P>Each instance of RIP is described by a structure <I>rip_proto</I>, which contains
1280: an internal RIP routing table, a list of protocol interfaces and the main
1281: timer responsible for RIP routing table cleanup.
1282: <P>RIP internal routing table contains incoming and outgoing routes. For each
1283: network (represented by structure <I>rip_entry</I>) there is one outgoing route
1284: stored directly in <I>rip_entry</I> and an one-way linked list of incoming routes
1285: (structures <I>rip_rte</I>). The list contains incoming routes from different RIP
1286: neighbors, but only routes with the lowest metric are stored (i.e., all
1287: stored incoming routes have the same metric).
1288: <P>Note that RIP itself does not select outgoing route, that is done by the core
1289: routing table. When a new incoming route is received, it is propagated to the
1290: RIP table by <B>rip_update_rte()</B> and possibly stored in the list of incoming
1291: routes. Then the change may be propagated to the core by <B>rip_announce_rte()</B>.
1292: The core selects the best route and propagate it to RIP by <B>rip_rt_notify()</B>,
1293: which updates outgoing route part of <I>rip_entry</I> and possibly triggers route
1294: propagation by <B>rip_trigger_update()</B>.
1295: <P>RIP interfaces are represented by structures <I>rip_iface</I>. A RIP interface
1296: contains a per-interface socket, a list of associated neighbors, interface
1297: configuration, and state information related to scheduled interface events
1298: and running update sessions. RIP interfaces are added and removed based on
1299: core interface notifications.
1300: <P>There are two RIP interface events - regular updates and triggered updates.
1301: Both are managed from the RIP interface timer (<B>rip_iface_timer()</B>). Regular
1302: updates are called at fixed interval and propagate the whole routing table,
1303: while triggered updates are scheduled by <B>rip_trigger_update()</B> due to some
1304: routing table change and propagate only the routes modified since the time
1305: they were scheduled. There are also unicast-destined requested updates, but
1306: these are sent directly as a reaction to received RIP request message. The
1307: update session is started by <B>rip_send_table()</B>. There may be at most one
1308: active update session per interface, as the associated state (including the
1309: fib iterator) is stored directly in <I>rip_iface</I> structure.
1310: <P>RIP neighbors are represented by structures <I>rip_neighbor</I>. Compared to
1311: neighbor handling in other routing protocols, RIP does not have explicit
1312: neighbor discovery and adjacency maintenance, which makes the <I>rip_neighbor</I>
1313: related code a bit peculiar. RIP neighbors are interlinked with core neighbor
1314: structures (<I>neighbor</I>) and use core neighbor notifications to ensure that RIP
1315: neighbors are timely removed. RIP neighbors are added based on received route
1316: notifications and removed based on core neighbor and RIP interface events.
1317: <P>RIP neighbors are linked by RIP routes and use counter to track the number of
1318: associated routes, but when these RIP routes timeout, associated RIP neighbor
1319: is still alive (with zero counter). When RIP neighbor is removed but still
1320: has some associated routes, it is not freed, just changed to detached state
1321: (core neighbors and RIP ifaces are unlinked), then during the main timer
1322: cleanup phase the associated routes are removed and the <I>rip_neighbor</I>
1323: structure is finally freed.
1324: <P>Supported standards:
1325: - RFC 1058 - RIPv1
1326: - RFC 2453 - RIPv2
1327: - RFC 2080 - RIPng
1328: - RFC 4822 - RIP cryptographic authentication
1329: <P>
1330: <P><HR><H3>Function</H3>
1331: <P><I>void</I>
1332: <B>rip_announce_rte</B>
1333: (<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
1334: <P>
1335: <H3>Arguments</H3>
1336: <P>
1337: <DL>
1338: <DT><I>struct rip_proto *</I> <B>p</B><DD><P>RIP instance
1339: <DT><I>struct rip_entry *</I> <B>en</B><DD><P>related network
1340: </DL>
1341: <H3>Description</H3>
1342: <P>The function takes a list of incoming routes from <B>en</B>, prepare appropriate
1343: <I>rte</I> for the core and propagate it by <B>rte_update()</B>.
1344:
1345:
1346: <HR><H3>Function</H3>
1347: <P><I>void</I>
1348: <B>rip_update_rte</B>
1349: (<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
1350: <P>
1351: <H3>Arguments</H3>
1352: <P>
1353: <DL>
1354: <DT><I>struct rip_proto *</I> <B>p</B><DD><P>RIP instance
1355: <DT><I>ip_addr *</I> <B>prefix</B><DD><P>network prefix
1356: <DT><I>int</I> <B>pxlen</B><DD><P>network prefix length
1357: <DT><I>struct rip_rte *</I> <B>new</B><DD><P>a <I>rip_rte</I> representing the new route
1358: </DL>
1359: <H3>Description</H3>
1360: <P>The function is called by the RIP packet processing code whenever it receives
1361: a reachable route. The appropriate routing table entry is found and the list
1362: of incoming routes is updated. Eventually, the change is also propagated to
1363: the core by <B>rip_announce_rte()</B>. Note that for unreachable routes,
1364: <B>rip_withdraw_rte()</B> should be called instead of <B>rip_update_rte()</B>.
1365:
1366:
1367: <HR><H3>Function</H3>
1368: <P><I>void</I>
1369: <B>rip_withdraw_rte</B>
1370: (<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
1371: <P>
1372: <H3>Arguments</H3>
1373: <P>
1374: <DL>
1375: <DT><I>struct rip_proto *</I> <B>p</B><DD><P>RIP instance
1376: <DT><I>ip_addr *</I> <B>prefix</B><DD><P>network prefix
1377: <DT><I>int</I> <B>pxlen</B><DD><P>network prefix length
1378: <DT><I>struct rip_neighbor *</I> <B>from</B><DD><P>a <I>rip_neighbor</I> propagating the withdraw
1379: </DL>
1380: <H3>Description</H3>
1381: <P>The function is called by the RIP packet processing code whenever it receives
1382: an unreachable route. The incoming route for given network from nbr <B>from</B> is
1383: removed. Eventually, the change is also propagated by <B>rip_announce_rte()</B>.
1384:
1385:
1386: <HR><H3>Function</H3>
1387: <P><I>void</I>
1388: <B>rip_timer</B>
1389: (<I>timer *</I> <B>t</B>) -- RIP main timer hook
1390: <P>
1391: <H3>Arguments</H3>
1392: <P>
1393: <DL>
1394: <DT><I>timer *</I> <B>t</B><DD><P>timer
1395: </DL>
1396: <H3>Description</H3>
1397: <P>The RIP main timer is responsible for routing table maintenance. Invalid or
1398: expired routes (<I>rip_rte</I>) are removed and garbage collection of stale routing
1399: table entries (<I>rip_entry</I>) is done. Changes are propagated to core tables,
1400: route reload is also done here. Note that garbage collection uses a maximal
1401: GC time, while interfaces maintain an illusion of per-interface GC times in
1402: <B>rip_send_response()</B>.
1403: <P>Keeping incoming routes and the selected outgoing route are two independent
1404: functions, therefore after garbage collection some entries now considered
1405: invalid (RIP_ENTRY_DUMMY) still may have non-empty list of incoming routes,
1406: while some valid entries (representing an outgoing route) may have that list
1407: empty.
1408: <P>The main timer is not scheduled periodically but it uses the time of the
1409: current next event and the minimal interval of any possible event to compute
1410: the time of the next run.
1411:
1412:
1413: <HR><H3>Function</H3>
1414: <P><I>void</I>
1415: <B>rip_iface_timer</B>
1416: (<I>timer *</I> <B>t</B>) -- RIP interface timer hook
1417: <P>
1418: <H3>Arguments</H3>
1419: <P>
1420: <DL>
1421: <DT><I>timer *</I> <B>t</B><DD><P>timer
1422: </DL>
1423: <H3>Description</H3>
1424: <P>RIP interface timers are responsible for scheduling both regular and
1425: triggered updates. Fixed, delay-independent period is used for regular
1426: updates, while minimal separating interval is enforced for triggered updates.
1427: The function also ensures that a new update is not started when the old one
1428: is still running.
1429:
1430:
1431: <HR><H3>Function</H3>
1432: <P><I>void</I>
1433: <B>rip_send_table</B>
1434: (<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
1435: <P>
1436: <H3>Arguments</H3>
1437: <P>
1438: <DL>
1439: <DT><I>struct rip_proto *</I> <B>p</B><DD><P>RIP instance
1440: <DT><I>struct rip_iface *</I> <B>ifa</B><DD><P>RIP interface
1441: <DT><I>ip_addr</I> <B>addr</B><DD><P>destination IP address
1442: <DT><I>bird_clock_t</I> <B>changed</B><DD><P>time limit for triggered updates
1443: </DL>
1444: <H3>Description</H3>
1445: <P>The function activates an update session and starts sending routing update
1446: packets (using <B>rip_send_response()</B>). The session may be finished during the
1447: call or may continue in <B>rip_tx_hook()</B> until all appropriate routes are
1448: transmitted. Note that there may be at most one active update session per
1449: interface, the function will terminate the old active session before
1450: activating the new one.
1451:
1.1.1.2 ! misho 1452: <H2><A NAME="ss5.8">5.8</A> <A HREF="prog.html#toc5.8">Router Advertisements</A>
1.1 misho 1453: </H2>
1454:
1455: <P>
1.1.1.2 ! misho 1456: <P>The RAdv protocol is implemented in two files: <CODE>radv.c</CODE> containing the
! 1457: interface with BIRD core and the protocol logic and <CODE>packets.c</CODE> handling low
! 1458: level protocol stuff (RX, TX and packet formats). The protocol does not
! 1459: export any routes.
! 1460: <P>The RAdv is structured in the usual way - for each handled interface there is
! 1461: a structure <I>radv_iface</I> that contains a state related to that interface
! 1462: together with its resources (a socket, a timer). There is also a prepared RA
! 1463: stored in a TX buffer of the socket associated with an iface. These iface
! 1464: structures are created and removed according to iface events from BIRD core
! 1465: handled by <B>radv_if_notify()</B> callback.
! 1466: <P>The main logic of RAdv consists of two functions: <B>radv_iface_notify()</B>, which
! 1467: processes asynchronous events (specified by RA_EV_* codes), and <B>radv_timer()</B>,
! 1468: which triggers sending RAs and computes the next timeout.
! 1469: <P>The RAdv protocol could receive routes (through <B>radv_import_control()</B> and
! 1470: <B>radv_rt_notify()</B>), but only the configured trigger route is tracked (in
! 1471: <I>active</I> var). When a radv protocol is reconfigured, the connected routing
! 1472: table is examined (in <B>radv_check_active()</B>) to have proper <I>active</I> value in
! 1473: case of the specified trigger prefix was changed.
1.1 misho 1474: <P>Supported standards:
1475: - RFC 4861 - main RA standard
1.1.1.2 ! misho 1476: - RFC 4191 - Default Router Preferences and More-Specific Routes
1.1 misho 1477: - RFC 6106 - DNS extensions (RDDNS, DNSSL)
1478: <P>
1479: <P>
1.1.1.2 ! misho 1480: <H2><A NAME="ss5.9">5.9</A> <A HREF="prog.html#toc5.9">Static</A>
1.1 misho 1481: </H2>
1482:
1483: <P>
1484: <P>The Static protocol is implemented in a straightforward way. It keeps
1485: two lists of static routes: one containing interface routes and one
1486: holding the remaining ones. Interface routes are inserted and removed according
1487: to interface events received from the core via the <B>if_notify()</B> hook. Routes
1488: pointing to a neighboring router use a sticky node in the neighbor cache
1489: to be notified about gaining or losing the neighbor. Special
1490: routes like black holes or rejects are inserted all the time.
1491: <P>Multipath routes are tricky. Because these routes depends on
1492: several neighbors we need to integrate that to the neighbor
1493: notification handling, we use dummy static_route nodes, one for
1494: each nexthop. Therefore, a multipath route consists of a master
1495: static_route node (of dest RTD_MULTIPATH), which specifies prefix
1496: and is used in most circumstances, and a list of dummy static_route
1497: nodes (of dest RTD_NONE), which stores info about nexthops and are
1498: connected to neighbor entries and neighbor notifications. Dummy
1499: nodes are chained using mp_next, they aren't in other_routes list,
1500: and abuse some fields (masklen, if_name) for other purposes.
1501: <P>The only other thing worth mentioning is that when asked for reconfiguration,
1502: Static not only compares the two configurations, but it also calculates
1503: difference between the lists of static routes and it just inserts the
1504: newly added routes and removes the obsolete ones.
1505: <P>
1506: <P>
1.1.1.2 ! misho 1507: <H2><A NAME="ss5.10">5.10</A> <A HREF="prog.html#toc5.10">Direct</A>
1.1 misho 1508: </H2>
1509:
1510: <P>
1511: <P>The Direct protocol works by converting all <B>ifa_notify()</B> events it receives
1512: to <B>rte_update()</B> calls for the corresponding network.
1513: <P>
1514: <P>
1515: <P>
1516: <HR>
1517: <A HREF="prog-6.html">Next</A>
1518: <A HREF="prog-4.html">Previous</A>
1519: <A HREF="prog.html#toc5">Contents</A>
1520: </BODY>
1521: </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