Commit b093c328 authored by Pavel Machek's avatar Pavel Machek

Updates to both programmers and users doc

parent 73275d85
......@@ -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.
<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.
<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
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:
......@@ -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
config file and then signal BIRD with SIGHUP, it will adjust to new
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).
<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
most protocols (like rip or bgp).
<tag>define constant = (<m/expression/)|<m/number/</tag> define constant. You can use it later in every place
you could use simple integer.
<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/ip address.
<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.
......@@ -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
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
is true if element is in given set or if ip address is inside given prefix. Operator <cf/=/ is used to assign value
to variable. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/>).
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/||/>).
<sect>Control structures
......@@ -531,14 +543,16 @@ defined using <cf>defined( <m>attribute</m> )</cf> syntax.
FIXME!
</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>
<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
......
......@@ -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)
{
......
......@@ -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 )
{
......
......@@ -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)
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment