From c184d9d0bdded559fb9d19accd17b88963e46669 Mon Sep 17 00:00:00 2001 From: Pavel Machek Date: Wed, 31 May 2000 21:51:04 +0000 Subject: Documentation update --- doc/bird.sgml | 117 ++++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 93 insertions(+), 24 deletions(-) (limited to 'doc') diff --git a/doc/bird.sgml b/doc/bird.sgml index 9bae9ee..e817d0b 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -98,30 +98,55 @@ it is slightly modified linuxdoc dtd. Anything in <descrip> tags is consi configuration primitives, <cf> is fragment of configuration within normal text, <m> is "meta" information within fragment of configuration -- something in config which is not keyword. + +About routing tables + +

Bird has one or more routing tables, which may or may not be +synchronized with kernel and which may or may not be synchronized with +each other (see protocol pipe). Each routing table contains list of +known routes. Each route has certain attributes, most important is +prefix of network this route is for. Routing table maintains more than +one entry for network, but at most one entry for one network and one +protocol. The entry with biggest preference is used for routing. If +there are more entries with same preference and they are from same +protocol, protocol decides (typically according to metrics). You can +get list of route attributes in "Route attributes" section in +filters. Filters can alter routes passed between routing tables and +protocols. + Installing BIRD -

On UNIX system, installing BIRD should be as easy as: +

On recent UNIX system, installing BIRD should be as easy as (bird +relies on GNU C and GNU make extensions): ./configure make make install vi /usr/local/etc/bird.conf + bird -

You can use ./configure --help to get list of configure options. +

You can use ./configure --help to get list of configure +options. Most important (and not easily guessed) option is +About routing tables +

You can pass several command-line options to bird: -

Bird has one or more routing tables. Each routing table contains -list of known routes. Each route has certain attributes, most -important is prefix of network this route is for. Routing table -maintains more than one entry for network, but at most one entry for -one network and one protocol. The entry with biggest preference is -used for routing. If there are more entries with same preference and -they are from same protocol, protocol decides (typically according to -metrics). You can get list of route attributes in "Route attributes" -section in filters. + + -c + use given config file instead of bird.conf. + + -d + enable debugging. + + -D + log debugging information to given file + + -s + use given filename for socket for communications with bird client, default is Configuration @@ -246,7 +271,10 @@ protocols, telling BIRD to show various information, telling it to show routing table filtered by any filter, or telling bird to reconfigure. Press Filters @@ -291,7 +319,6 @@ you want to make bigger block of code conditional.

There are two special filters, Bird supports functions, so that you don't have to repeat same blocks of code over and over. Functions can have zero or more parameters, and can have local variables. Function basically looks like this: @@ -320,6 +347,27 @@ to any functions being called. Filter must terminate with either accept or reject statement. If there's runtime error in filter, route is rejected. +

Nice trick to debug filters is using show route filter + from command line client. Example session might look +like: + + +pavel@bug:~/bird$ ./birdc -s bird.ctl +BIRD 0.0.0 ready. +bird> help +No such command. +bird> +bird> show route +10.0.0.0/8 dev eth0 [direct1 23:21] (240) +195.113.30.2/32 dev tunl1 [direct1 23:21] (240) +127.0.0.0/8 dev lo [direct1 23:21] (240) +bird> show route ? +show route [] [table ] [filter ] [all] [primary] [(import|protocol)

] [stats] Show routing table +bird> show route filter { if 127.0.0.5 ~ net then accept; } +127.0.0.0/8 dev lo [direct1 23:21] (240) +bird> + + Data types

Each variable and each value has certain type. Unlike C, filters distinguish between integers and @@ -358,10 +406,12 @@ booleans and between integers and enums (that is to prevent you from shooting in filters know four types of sets. Sets are similar to strings: you can pass them around but you can not modify them. Constant of type set int looks like [ 1, 2, 5..7 ]. As you can see, both simple values and ranges are permitted in - sets. Sets of prefixes are special: you can specify which prefixes should match them by + sets. Sets of prefixes are special: you can specify which prefix lengths should match them by using [ 1.0.0.0/8+, 2.0.0.0/8-, 3.0.0.0/8{5,6} ]. 3.0.0.0/8{5,6} matches prefixes 3.X.X.X, whose prefix length is 5 to 6. 3.0.0.0/8+ is shorthand for 3.0.0.0/{0,8}, - 3.0.0.0/8- is shorthand for 3.0.0.0/{0,7}. + 3.0.0.0/8- is shorthand for 3.0.0.0/{0,7}. For example, + 1.2.0.0/16 ~ [ 1.0.0.0/8{ 15 , 17 } ] is true, but + 1.0.0.0/8 ~ [ 1.0.0.0/8- ] is false. path ~ / 2 3 5 ? / syntax ). path ~ / 2 3 5 ? / syntax ). Matching is + done using shell-like pattern: /* which is start of comment. + write /* which is start of comment.) For example, + / 4 3 2 1 / ~ / ? 4 3 ? 1 / is true, but + / 4 3 2 1 / ~ / ? 4 5 ? / is false. defined( attribute ) syntax. - - defined( attribute ) syntax.

Plus, there are protocol-specific attributes, which are described in protocol sections. @@ -1014,11 +1076,18 @@ protocol static { } -Getting more help +Problems -

This is really last section of this file, should give pointers to -programmers documentation, web pages mailing lists and similar stuff. +

BIRD is relatively young system, and probably contains some +bugs. You can report bugs at , but before you do, +please make sure you are running latest version (available at ), and that bug was not already reported by someone else +(mailing list archives are at ). (Of course, patch +which fixes the bug along with bug report is always welcome). When +trying to understand, what is going on, Internet standards are +relevant reading; you can get them from . +

-- cgit v1.2.3