diff --git a/TODO b/TODO index ecf00d81..d33162b7 100644 --- a/TODO +++ b/TODO @@ -58,59 +58,16 @@ OSPF Documentation (sorry, its in czech) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -K SGML: - -o Mohl bys, prosim, nekam napsat, co je vsechno potreba udelat, aby bylo - dokumentaci mozno postavit? Skoncil jsem u toho, ze jsem do doc/sbase/ - zkopiroval spoustu souboru z /usr/lib/sgml-tools a pridal nekolik symlinku - -- ted uz sice dokumentaci vygeneruji, ale asi to neni ta spravna cesta. - -K HTML: - -o "2000" zcela vypadava mimo hlavicku. -o Zkusit HTML projet nejakym validatorem. - -Uvod: - -o Chybi sekce popisujici instalaci, spousteni a command-line options. -o "About routing tables" by melo byt podstatne podrobnejsi (vysvetlit, co vlastne - routovaci tabulky jsou, co obsahuji, ze vubec existuji nejake atributy, k cemu - slouzi, ze nektere tabulky jsou synchronizovane s kernelem, zatimco jine nikoliv, - ze lze prenaset routy mezi tabulkami (odkaz na protokol pipe), ze k tabulkam - jsou pres filtry pripojeny protokoly atd.) Asi z toho udelat samostatnou kapitolu. -o Zminit logy a kategorie hlasek. -o Chybi installation requirements: tedy ze potrebujeme GCC a GNU make. - Filtry: -o Napsat neco o tom, jak filtry debugovat -- ze existuje trasovani filtru - a CLI command pro vypsani routovaci tabulky tak, jak projde filtrem ci tak, - jak ji vidi dany protokol. -o `filters internally work ...' patri do progdoc. o Vysvetlit nesting a zastinovani. -o Nadefinovat, co se stane, kdyz funkce nevrati hodnotu, i kdyz ma. -o ip: IPv4/IPv6 nezavisi na verzi BIRDa, nybrz na compile-time konfiguraci. -o ip: .mask zminit zvlast mezi specialnimi operatory. -o set: lepe vysvetlit matchovani prefixu, ukazat na prikladu. -o bgppath: list of autonomous system _numbers_ -o bgpmask: vysvetlit matchovani. -o operations: prejmenovat na `operators', mela by to asi byt tabulka - operatoru, u kazdeho receno, na jakych typech je definovan a jakeho - typu je vysledek. -o attributes: nemyslim, ze jsou vsechny -- co treba scope a preference? -o print: a coz takhle printn apod.? -o Mezi prikazy nikde neni zminen napriklad accept a reject. -o Co se stane, kdyz filtr skonci, aniz by vydal verdikt? Protocols: -o RIP: Per-interface optiony uvadet tez jako definition list. o passwords: syntaxe data uz, tusim, davno vypada jinak. Struktura dokumentace: -o Chybi kapitola o CLI a o clientovi. o Na konci (nebo ve zvlast sekci pro kazdy protokol?) by mel byt seznam referenci na vsechny mozne dokumenty, zejmena vsak vsechna RFC, kterymi se ridime nebo ktera maji neco spolecneho s tim, co delame (napriklad RPSL). @@ -122,17 +79,6 @@ o Pokud je v zavorce cela veta, patri pred ')' tecka, pokud neni, tak nepatri. o Davej si pozor na rody -- router je vzdycky `it', nikdy `he'. -> > Nechtel bys kapitolu o clientovy napsat ty? Ja o nem nic nevim, a -> > kvalita uzivatelske dokumentace je o hodne dulezitejsi nez -> > programatorske. -> -> O clientovi neni temer co psat, commandy si, myslim, snadno najdes v config.Y. -> Protokol je velice jednoduchy: uzivatel posila prikazy, BIRD odpovida radky -> typu CCCCs..., kde CCCC je kod hlasky (viz doc/reply-codes), `s' je whitespace, -> `...' hlaska. Viceradkove odpovedi maji na vsech radcich mimo posledniho misto `s' -> minus a nebo na druhem az predposlednim radku misto celeho prefixu jen whitespace -> (presne jako ve FTP). - Jeste by to chtelo trosku podrobneji: (1) zminit se o atributech, rici, co vsechno o route rikaji a odkazat diff --git a/doc/bird.sgml b/doc/bird.sgml index 9bae9eea..e817d0b2 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 . +