From b093c328f5b352e3d059cb14cceed1e4daa1b9dc Mon Sep 17 00:00:00 2001 From: Pavel Machek Date: Mon, 5 Jun 2000 12:52:57 +0000 Subject: [PATCH] Updates to both programmers and users doc --- doc/bird.sgml | 36 ++++++++++++++++-------- filter/filter.c | 26 ++++++++++++++++- proto/rip/auth.c | 8 +++++- proto/rip/rip.c | 73 ++++++++++++++++++++++++++++++++++++++---------- 4 files changed, 116 insertions(+), 27 deletions(-) diff --git a/doc/bird.sgml b/doc/bird.sgml index 1dc2bee9..2adf9b55 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -124,7 +124,15 @@ there are more entries with same preference and they are from same protocol, protocol decides (typically according to metrics). If not, internal ordering is used to decide. You can get list of route attributes in "Route attributes" section in -filters. Filters can alter routes passed between routing tables and +filters. + +

Protocols are connected to routing tables using filters. Routes +that come from network go to the protocol, it then passes them to +filters, if import filter accepts route, it gets to main routing +table. It is then broadcasted to all other protocols (filtered through +their export filters), which typically send it to the network. + +Filters can alter routes passed between routing tables and protocols. Installing BIRD @@ -142,7 +150,12 @@ system, installing BIRD should be as easy as:

You can use ./configure --help to get list of configure options. Most important (and not easily guessed) option is -/usr/local. + +Running bird

You can pass several command-line options to bird: @@ -168,7 +181,7 @@ options. Most important (and not easily guessed) option is In config, everything on a line after /* @@ -230,8 +243,8 @@ protocol rip { about configuring protocols in their own chapters. You can run more than one instance of most protocols (like rip or bgp). - define constant = ( define constant. You can use it later in every place - you could use simple integer. + define define constant. You can use it later in every place + you could use simple integer/ip address. router id set router id. Router id needs to be world-wide unique. It is usually one of router's IPv4 addresses. @@ -468,8 +481,7 @@ incompatible with each other (that is to prevent you from shooting in the foot). ). +is true if element is in given set or if ip address is inside given prefix. Logical operations include unary not (). Control structures @@ -531,14 +543,16 @@ defined using defined( attribute ) syntax. FIXME! -

Plus, there are protocol-specific attributes, which are described in protocol sections. +

Then there are protocol-specific attributes, which are described in protocol sections. -Utility functions +Statements -

There are few functions you might find convenient to use: +

Following statements are supported: - accept accept this route + set variable to give value. + + accept [ accept this route, possibly printing expr reject reject this route diff --git a/filter/filter.c b/filter/filter.c index c12435cf..5c50b9a2 100644 --- a/filter/filter.c +++ b/filter/filter.c @@ -70,7 +70,9 @@ pm_path_compare(struct f_path_mask *m1, struct f_path_mask *m2) } } -/* Compare two values, returns -1, 0, 1 compared, ERROR 999 */ +/** + * val_compare - compare two values, returns -1, 0, 1 on <, =, > and 999 on error */ + */ int val_compare(struct f_val v1, struct f_val v2) { @@ -103,6 +105,9 @@ val_compare(struct f_val v1, struct f_val v2) } } +/** + * val_simple_in_range - check if @v1 ~ @v2 for everything except sets + */ int val_simple_in_range(struct f_val v1, struct f_val v2) { @@ -134,6 +139,9 @@ val_simple_in_range(struct f_val v1, struct f_val v2) return CMP_ERROR; } +/** + * val_in_range - check if @v1 ~ @v2 + */ int val_in_range(struct f_val v1, struct f_val v2) { @@ -175,6 +183,9 @@ tree_print(struct f_tree *t) debug( "] " ); } +/** + * val_print - format filter value + */ void val_print(struct f_val v) { @@ -207,6 +218,9 @@ static struct ea_list **f_tmp_attrs; static int f_flags; static rta *f_rta_copy; +/** + * rta_cow - prepare rta for modification by filter + */ void rta_cow(void) { @@ -239,6 +253,13 @@ rta_cow(void) if (v1.type != v2.type) \ runtime( "Can not operate with values of incompatible types" ); +/** + * interpret + * @what: filter to interrpret + * + * Interrpret given tree of filter instructions. This is core function + * of filter system and does all the hard work. + */ static struct f_val interpret(struct f_inst *what) { @@ -660,6 +681,9 @@ interpret(struct f_inst *what) #define A2_SAME if (f1->a2.i != f2->a2.i) return 0; +/** + * i_same - function that does real comparing of instruction trees, you should call filter_same from outside + */ int i_same(struct f_inst *f1, struct f_inst *f2) { diff --git a/proto/rip/auth.c b/proto/rip/auth.c index 994021e7..f1a3204e 100644 --- a/proto/rip/auth.c +++ b/proto/rip/auth.c @@ -26,7 +26,9 @@ #define PACKETLEN(num) (num * sizeof(struct rip_block) + sizeof(struct rip_packet_heading)) -/* 1 == failed, 0 == ok */ +/** + * rip_incoming_authentication - check authentication of incomming packet and return 1 if there's problem. + */ int rip_incoming_authentication( struct proto *p, struct rip_block_auth *block, struct rip_packet *packet, int num, ip_addr whotoldme ) { @@ -108,6 +110,10 @@ rip_incoming_authentication( struct proto *p, struct rip_block_auth *block, stru return 0; } +/** + * rip_outgoing_authentication - append authentication information to the packet. + * %num: number of rip_blocks already in packets. This function returns size of packet to send. + */ int rip_outgoing_authentication( struct proto *p, struct rip_block_auth *block, struct rip_packet *packet, int num ) { diff --git a/proto/rip/rip.c b/proto/rip/rip.c index 02565282..698f0e28 100644 --- a/proto/rip/rip.c +++ b/proto/rip/rip.c @@ -40,7 +40,6 @@ * we look for any changed routes and broadcast them. */ - #undef LOCAL_DEBUG #include "nest/bird.h" @@ -65,8 +64,10 @@ static struct rip_interface *new_iface(struct proto *p, struct iface *new, unsig #define P_NAME p->name -/* - * Output processing +/** + * DOC: Output processing + * + * This part is responsible for getting packets out to the network. */ static void @@ -77,6 +78,15 @@ rip_tx_err( sock *s, int err ) log( L_ERR "%s: Unexpected error at rip transmit: %M", P_NAME, err ); } +/** + * rip_tx_prepare: + * @e: rip entry that needs to be translated to form suitable for network + * @b: block to be filled + * + * Fill one rip block with info that needs to go to the network. Handle + * nexthop and split horizont correctly. (Next hop is ignored for IPv6, + * that could be fixed but it is not real problem). + */ static int rip_tx_prepare(struct proto *p, ip_addr daddr, struct rip_block *b, struct rip_entry *e, struct rip_interface *rif, int pos ) { @@ -106,6 +116,9 @@ rip_tx_prepare(struct proto *p, ip_addr daddr, struct rip_block *b, struct rip_e return pos+1; } +/** + * rip_tx - send one rip packet to the network + */ static void rip_tx( sock *s ) { @@ -181,6 +194,11 @@ done: return; } +/** + * rip_sendto - send whole routing table to selected destination + * @rif: interface to use. Notice that we lock interface so that at + * most one send to one interface is done. + */ static void rip_sendto( struct proto *p, ip_addr daddr, int dport, struct rip_interface *rif ) { @@ -204,12 +222,6 @@ rip_sendto( struct proto *p, ip_addr daddr, int dport, struct rip_interface *rif c->daddr = daddr; if (c->rif->sock->data != rif) bug("not enough send magic"); -#if 0 - if (sk_open(c->send)<0) { - log( L_ERR "%s Could not open socket for data send to %I:%d on %s", P_NAME, daddr, dport, rif->iface->name ); - return; - } -#endif c->done = 0; FIB_ITERATE_INIT( &c->iter, &P->rtable ); @@ -233,8 +245,10 @@ find_interface(struct proto *p, struct iface *what) return NULL; } -/* - * Input processing +/** + * DOC: Input processing + * + * This part is responsible for any updates that come from network */ static void @@ -247,7 +261,14 @@ rip_rte_update_if_better(rtable *tab, net *net, struct proto *p, rte *new) rte_update(tab, net, p, new); } -/* Let main routing table know about our new entry */ +/** + * advertise_entry - let main routing table know about our new entry + * @b: entry in network format + * + * This basically translates @b to format used by bird core and feeds + * bird core with this route. Notice that we do not store info anywhere + * in our data structures: we'll do that when core notifies us back. + */ static void advertise_entry( struct proto *p, struct rip_block *b, ip_addr whotoldme ) { @@ -312,6 +333,9 @@ advertise_entry( struct proto *p, struct rip_block *b, ip_addr whotoldme ) DBG( "done\n" ); } +/** + * process_block - do some basic check and pass block to advertise_entry + */ static void process_block( struct proto *p, struct rip_block *block, ip_addr whotoldme ) { @@ -335,6 +359,9 @@ process_block( struct proto *p, struct rip_block *block, ip_addr whotoldme ) #define BAD( x ) { log( L_REMOTE "%s: " x, P_NAME ); return 1; } +/** + * rip_process_packet - this is main routine for incoming packets. + */ static int rip_process_packet( struct proto *p, struct rip_packet *packet, int num, ip_addr whotoldme, int port ) { @@ -402,6 +429,9 @@ rip_process_packet( struct proto *p, struct rip_packet *packet, int num, ip_addr return 0; } +/** + * rip_rx - Receive hook: do basic checks and pass packet to rip_process_packet + */ static int rip_rx(sock *s, int size) { @@ -431,8 +461,8 @@ rip_rx(sock *s, int size) return 1; } -/* - * Interface to rest of bird +/** + * DOC: Interface to bird core */ static void @@ -443,6 +473,9 @@ rip_dump_entry( struct rip_entry *e ) debug( "\n" ); } +/** + * rip_timer - broadcast routing tables periodically (using rip_tx) and kill routes that are too old + */ static void rip_timer(timer *t) { @@ -771,6 +804,10 @@ rip_store_tmp_attrs(struct rte *rt, struct ea_list *attrs) rt->u.rip.metric = ea_get_int(attrs, EA_RIP_METRIC, 1); } +/** + * rip_rt_notify - core tells us about new route (possibly our + * own), so store it into our data structures. + */ static void rip_rt_notify(struct proto *p, struct network *net, struct rte *new, struct rte *old, struct ea_list *attrs) { @@ -839,6 +876,11 @@ rip_rte_better(struct rte *new, struct rte *old) return 0; } +/** + * rip_rte_insert - we maintain linked list of "our" entries in main + * routing table, so that we can timeout them correctly. rip_timer + * walks the list. + */ static void rip_rte_insert(net *net, rte *rte) { @@ -849,6 +891,9 @@ rip_rte_insert(net *net, rte *rte) add_head( &P->garbage, &rte->u.rip.garbage ); } +/** + * rip_rte_remove - link list maintenance + */ static void rip_rte_remove(net *net, rte *rte) {