Updates to both programmers and users doc

This commit is contained in:
Pavel Machek 2000-06-05 12:52:57 +00:00
parent 73275d855d
commit b093c328f5
4 changed files with 116 additions and 27 deletions

View file

@ -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, protocol, protocol decides (typically according to metrics). If not,
internal ordering is used to decide. You can internal ordering is used to decide. You can
get list of route attributes in "Route attributes" section in get list of route attributes in "Route attributes" section in
filters. Filters can alter routes passed between routing tables and filters.
<p>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. protocols.
<sect>Installing BIRD <sect>Installing BIRD
@ -142,7 +150,12 @@ system, installing BIRD should be as easy as:
<p>You can use <tt>./configure --help</tt> to get list of configure <p>You can use <tt>./configure --help</tt> to get list of configure
options. Most important (and not easily guessed) option is options. Most important (and not easily guessed) option is
<tt/--enable-ipv6/, which enables IPv6 support. <tt/--enable-ipv6/, which enables IPv6 support. You can use
<tt/--with-protocols=/ to produce slightly smaller BIRD, and
<tt/--prefix=/ to install bird somewhere else than
<file>/usr/local</file>.
<sect>Running bird
<p>You can pass several command-line options to bird: <p>You can pass several command-line options to bird:
@ -168,7 +181,7 @@ options. Most important (and not easily guessed) option is
<tt/-c/ command line option is given). Configuration may be changed on user request: if you modify <tt/-c/ command line option is given). Configuration may be changed on user request: if you modify
config file and then signal BIRD with SIGHUP, it will adjust to new config file and then signal BIRD with SIGHUP, it will adjust to new
config. Then there's BIRD client, config. Then there's BIRD client,
which allows you to talk with BIRD in more extensive way than just telling it to reconfigure. BIRD which allows you to talk with BIRD in extensive way. (Of course you can tell BIRD to reconfigure from BIRDC, you can also tell it to shut down, dump various info etc.). BIRD
writes messages about its work to log files or syslog (according to config). writes messages about its work to log files or syslog (according to config).
<p>In config, everything on a line after <cf/#/ or inside <cf>/* <p>In config, everything on a line after <cf/#/ or inside <cf>/*
@ -230,8 +243,8 @@ protocol rip {
about configuring protocols in their own chapters. You can run more than one instance of about configuring protocols in their own chapters. You can run more than one instance of
most protocols (like rip or bgp). most protocols (like rip or bgp).
<tag>define constant = (<m/expression/)|<m/number/</tag> define constant. You can use it later in every place <tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/ip address/</tag> define constant. You can use it later in every place
you could use simple integer. you could use simple integer/ip address.
<tag>router id <m/IPv4 address/</tag> set router id. Router id needs to be world-wide <tag>router id <m/IPv4 address/</tag> set router id. Router id needs to be world-wide
unique. It is usually one of router's IPv4 addresses. 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).
<cf/(a=b, a!=b, a&lt;b, a&gt;=b)/. Special operators include <cf/&tilde;/ for "in" operation. In operation can be <cf/(a=b, a!=b, a&lt;b, a&gt;=b)/. Special operators include <cf/&tilde;/ for "in" operation. In operation can be
used on element and set of that elements, or on ip and prefix, or on used on element and set of that elements, or on ip and prefix, or on
prefix and prefix or on bgppath and bgpmask or on pair and clist. Its result prefix and prefix or on bgppath and bgpmask or on pair and clist. Its result
is true if element is in given set or if ip address is inside given prefix. Operator <cf/=/ is used to assign value is true if element is in given set or if ip address is inside given prefix. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/>).
to variable. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/>).
<sect>Control structures <sect>Control structures
@ -531,14 +543,16 @@ defined using <cf>defined( <m>attribute</m> )</cf> syntax.
FIXME! FIXME!
</descrip> </descrip>
<p>Plus, there are protocol-specific attributes, which are described in protocol sections. <p>Then there are protocol-specific attributes, which are described in protocol sections.
<sect>Utility functions <sect>Statements
<p>There are few functions you might find convenient to use: <p>Following statements are supported:
<descrip> <descrip>
<tag>accept</tag> accept this route <tag><m/variable/ = <m/expr/</tag> set variable to give value.
<tag>accept [ <m/expr/ ]</tag> accept this route, possibly printing expr
<tag>reject</tag> reject this route <tag>reject</tag> reject this route

View file

@ -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 int
val_compare(struct f_val v1, struct f_val v2) 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 int
val_simple_in_range(struct f_val v1, struct f_val v2) 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; return CMP_ERROR;
} }
/**
* val_in_range - check if @v1 ~ @v2
*/
int int
val_in_range(struct f_val v1, struct f_val v2) val_in_range(struct f_val v1, struct f_val v2)
{ {
@ -175,6 +183,9 @@ tree_print(struct f_tree *t)
debug( "] " ); debug( "] " );
} }
/**
* val_print - format filter value
*/
void void
val_print(struct f_val v) val_print(struct f_val v)
{ {
@ -207,6 +218,9 @@ static struct ea_list **f_tmp_attrs;
static int f_flags; static int f_flags;
static rta *f_rta_copy; static rta *f_rta_copy;
/**
* rta_cow - prepare rta for modification by filter
*/
void void
rta_cow(void) rta_cow(void)
{ {
@ -239,6 +253,13 @@ rta_cow(void)
if (v1.type != v2.type) \ if (v1.type != v2.type) \
runtime( "Can not operate with values of incompatible types" ); 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 static struct f_val
interpret(struct f_inst *what) 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; #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 int
i_same(struct f_inst *f1, struct f_inst *f2) i_same(struct f_inst *f1, struct f_inst *f2)
{ {

View file

@ -26,7 +26,9 @@
#define PACKETLEN(num) (num * sizeof(struct rip_block) + sizeof(struct rip_packet_heading)) #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 int
rip_incoming_authentication( struct proto *p, struct rip_block_auth *block, struct rip_packet *packet, int num, ip_addr whotoldme ) 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; 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 int
rip_outgoing_authentication( struct proto *p, struct rip_block_auth *block, struct rip_packet *packet, int num ) rip_outgoing_authentication( struct proto *p, struct rip_block_auth *block, struct rip_packet *packet, int num )
{ {

View file

@ -40,7 +40,6 @@
* we look for any changed routes and broadcast them. * we look for any changed routes and broadcast them.
*/ */
#undef LOCAL_DEBUG #undef LOCAL_DEBUG
#include "nest/bird.h" #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 #define P_NAME p->name
/* /**
* Output processing * DOC: Output processing
*
* This part is responsible for getting packets out to the network.
*/ */
static void 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 ); 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 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 ) 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; return pos+1;
} }
/**
* rip_tx - send one rip packet to the network
*/
static void static void
rip_tx( sock *s ) rip_tx( sock *s )
{ {
@ -181,6 +194,11 @@ done:
return; 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 static void
rip_sendto( struct proto *p, ip_addr daddr, int dport, struct rip_interface *rif ) 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; c->daddr = daddr;
if (c->rif->sock->data != rif) if (c->rif->sock->data != rif)
bug("not enough send magic"); 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; c->done = 0;
FIB_ITERATE_INIT( &c->iter, &P->rtable ); FIB_ITERATE_INIT( &c->iter, &P->rtable );
@ -233,8 +245,10 @@ find_interface(struct proto *p, struct iface *what)
return NULL; return NULL;
} }
/* /**
* Input processing * DOC: Input processing
*
* This part is responsible for any updates that come from network
*/ */
static void 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); 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 static void
advertise_entry( struct proto *p, struct rip_block *b, ip_addr whotoldme ) 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" ); DBG( "done\n" );
} }
/**
* process_block - do some basic check and pass block to advertise_entry
*/
static void static void
process_block( struct proto *p, struct rip_block *block, ip_addr whotoldme ) 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; } #define BAD( x ) { log( L_REMOTE "%s: " x, P_NAME ); return 1; }
/**
* rip_process_packet - this is main routine for incoming packets.
*/
static int static int
rip_process_packet( struct proto *p, struct rip_packet *packet, int num, ip_addr whotoldme, int port ) 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; return 0;
} }
/**
* rip_rx - Receive hook: do basic checks and pass packet to rip_process_packet
*/
static int static int
rip_rx(sock *s, int size) rip_rx(sock *s, int size)
{ {
@ -431,8 +461,8 @@ rip_rx(sock *s, int size)
return 1; return 1;
} }
/* /**
* Interface to rest of bird * DOC: Interface to bird core
*/ */
static void static void
@ -443,6 +473,9 @@ rip_dump_entry( struct rip_entry *e )
debug( "\n" ); debug( "\n" );
} }
/**
* rip_timer - broadcast routing tables periodically (using rip_tx) and kill routes that are too old
*/
static void static void
rip_timer(timer *t) 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); 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 static void
rip_rt_notify(struct proto *p, struct network *net, struct rte *new, struct rte *old, struct ea_list *attrs) 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; 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 static void
rip_rte_insert(net *net, rte *rte) 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 ); add_head( &P->garbage, &rte->u.rip.garbage );
} }
/**
* rip_rte_remove - link list maintenance
*/
static void static void
rip_rte_remove(net *net, rte *rte) rip_rte_remove(net *net, rte *rte)
{ {