Documentation update
This commit is contained in:
parent
0b1cad8162
commit
c184d9d0bd
2 changed files with 93 additions and 78 deletions
54
TODO
54
TODO
|
@ -58,59 +58,16 @@ OSPF
|
||||||
|
|
||||||
Documentation (sorry, its in czech)
|
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:
|
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 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:
|
Protocols:
|
||||||
|
|
||||||
o RIP: Per-interface optiony uvadet tez jako definition list.
|
|
||||||
o passwords: syntaxe data uz, tusim, davno vypada jinak.
|
o passwords: syntaxe data uz, tusim, davno vypada jinak.
|
||||||
|
|
||||||
Struktura dokumentace:
|
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
|
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
|
na vsechny mozne dokumenty, zejmena vsak vsechna RFC, kterymi se ridime nebo
|
||||||
ktera maji neco spolecneho s tim, co delame (napriklad RPSL).
|
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.
|
nepatri.
|
||||||
o Davej si pozor na rody -- router je vzdycky `it', nikdy `he'.
|
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:
|
Jeste by to chtelo trosku podrobneji:
|
||||||
|
|
||||||
(1) zminit se o atributech, rici, co vsechno o route rikaji a odkazat
|
(1) zminit se o atributech, rici, co vsechno o route rikaji a odkazat
|
||||||
|
|
117
doc/bird.sgml
117
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
|
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.
|
"meta" information within fragment of configuration -- something in config which is not keyword.
|
||||||
|
|
||||||
|
|
||||||
|
<sect1>About routing tables
|
||||||
|
|
||||||
|
<p>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.
|
||||||
|
|
||||||
<sect1>Installing BIRD
|
<sect1>Installing BIRD
|
||||||
|
|
||||||
<p>On UNIX system, installing BIRD should be as easy as:
|
<p>On recent UNIX system, installing BIRD should be as easy as (bird
|
||||||
|
relies on GNU C and GNU make extensions): <!-- It is not true that we
|
||||||
|
require gcc, there are other compilers supporting gcc extensions! -->
|
||||||
|
|
||||||
<code>
|
<code>
|
||||||
./configure
|
./configure
|
||||||
make
|
make
|
||||||
make install
|
make install
|
||||||
vi /usr/local/etc/bird.conf
|
vi /usr/local/etc/bird.conf
|
||||||
|
bird
|
||||||
</code>
|
</code>
|
||||||
|
|
||||||
<p>You can use <tt>./configure --help</tt> to get list of configure options.
|
<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.
|
||||||
|
|
||||||
<sect1>About routing tables
|
<p>You can pass several command-line options to bird:
|
||||||
|
|
||||||
<p>Bird has one or more routing tables. Each routing table contains
|
<descrip>
|
||||||
list of known routes. Each route has certain attributes, most
|
<tag>-c <m/config name/</tag>
|
||||||
important is prefix of network this route is for. Routing table
|
use given config file instead of <file>bird.conf</file>.
|
||||||
maintains more than one entry for network, but at most one entry for
|
|
||||||
one network and one protocol. The entry with biggest preference is
|
<tag>-d</tag>
|
||||||
used for routing. If there are more entries with same preference and
|
enable debugging.
|
||||||
they are from same protocol, protocol decides (typically according to
|
|
||||||
metrics). You can get list of route attributes in "Route attributes"
|
<tag>-D <m/filename for debug log/</tag>
|
||||||
section in filters.
|
log debugging information to given file
|
||||||
|
|
||||||
|
<tag>-s <m/name of communication socket/</tag>
|
||||||
|
use given filename for socket for communications with bird client, default is <file/bird.ctl/.
|
||||||
|
</descrip>
|
||||||
|
|
||||||
<sect>Configuration
|
<sect>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
|
show routing table filtered by any filter, or telling bird to
|
||||||
reconfigure. Press <tt/?/ at any time to get online help. Option
|
reconfigure. Press <tt/?/ at any time to get online help. Option
|
||||||
<tt/-v/ can be passed to client, telling it to dump numeric return
|
<tt/-v/ can be passed to client, telling it to dump numeric return
|
||||||
codes.
|
codes. You do not neccessarily need to use BIRDC to talk to BIRD, your
|
||||||
|
own application could do that, too -- format of communication between
|
||||||
|
BIRD and BIRDC is stable (see programmer's documenation).
|
||||||
|
|
||||||
|
|
||||||
<sect>Filters
|
<sect>Filters
|
||||||
|
|
||||||
|
@ -291,7 +319,6 @@ you want to make bigger block of code conditional.
|
||||||
<p>There are two special filters, <cf/all/ (which accepts all routes) and <cf/none/ (which rejects
|
<p>There are two special filters, <cf/all/ (which accepts all routes) and <cf/none/ (which rejects
|
||||||
all routes).
|
all routes).
|
||||||
|
|
||||||
|
|
||||||
<p>Bird supports functions, so that you don't have to repeat same blocks of code over and
|
<p>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
|
over. Functions can have zero or more parameters, and can have local variables. Function basically
|
||||||
looks like this:
|
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
|
accept or reject statement. If there's runtime error in filter, route
|
||||||
is rejected.
|
is rejected.
|
||||||
|
|
||||||
|
<p>Nice trick to debug filters is using <cf>show route filter
|
||||||
|
<m/name/</cf> from command line client. Example session might look
|
||||||
|
like:
|
||||||
|
|
||||||
|
<code>
|
||||||
|
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 [<prefix>] [table <t>] [filter <f>] [all] [primary] [(import|protocol) <p>] [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>
|
||||||
|
</code>
|
||||||
|
|
||||||
<sect1>Data types
|
<sect1>Data types
|
||||||
|
|
||||||
<p>Each variable and each value has certain type. Unlike C, filters distinguish between integers and
|
<p>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
|
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 <cf>set int</cf> looks like <cf>
|
but you can not modify them. Constant of type <cf>set int</cf> looks like <cf>
|
||||||
[ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
|
[ 1, 2, 5..7 ]</cf>. 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 <cf>[ 1.0.0.0/8+, 2.0.0.0/8-, 3.0.0.0/8{5,6} ]</cf>. 3.0.0.0/8{5,6} matches
|
using <cf>[ 1.0.0.0/8+, 2.0.0.0/8-, 3.0.0.0/8{5,6} ]</cf>. 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},
|
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,
|
||||||
|
<tt>1.2.0.0/16 ~ [ 1.0.0.0/8{ 15 , 17 } ]</tt> is true, but
|
||||||
|
<tt>1.0.0.0/8 ~ [ 1.0.0.0/8- ]</tt> is false.
|
||||||
|
|
||||||
<tag/enum/
|
<tag/enum/
|
||||||
enumeration types are halfway-internal in the BIRD. You can not define your own
|
enumeration types are halfway-internal in the BIRD. You can not define your own
|
||||||
|
@ -374,10 +424,14 @@ booleans and between integers and enums (that is to prevent you from shooting in
|
||||||
|
|
||||||
<tag/bgpmask/
|
<tag/bgpmask/
|
||||||
bgp mask is mask used for matching bgp paths
|
bgp mask is mask used for matching bgp paths
|
||||||
(using <cf>path ~ / 2 3 5 ? / syntax </cf>). <cf/?/ is
|
(using <cf>path ~ / 2 3 5 ? / syntax </cf>). Matching is
|
||||||
really serving in "any number of autonomous systems", but we
|
done using shell-like pattern: <cf/?/ means
|
||||||
|
"any number of any autonomous systems". Pattern for single
|
||||||
|
unknown autonomous system is not supported. (We
|
||||||
did not want to use * because then it becomes too easy to
|
did not want to use * because then it becomes too easy to
|
||||||
write <cf>/*</cf> which is start of comment.
|
write <cf>/*</cf> which is start of comment.) For example,
|
||||||
|
<tt>/ 4 3 2 1 / ~ / ? 4 3 ? 1 /</tt> is true, but
|
||||||
|
<tt>/ 4 3 2 1 / ~ / ? 4 5 ? /</tt> is false.
|
||||||
|
|
||||||
<tag/clist/
|
<tag/clist/
|
||||||
community list. This is similar to set of pairs,
|
community list. This is similar to set of pairs,
|
||||||
|
@ -428,11 +482,13 @@ attributes, just like it accesses variables. Access to undefined
|
||||||
attribute results in runtime error; you can check if attribute is
|
attribute results in runtime error; you can check if attribute is
|
||||||
defined using <cf>defined( <m>attribute</m> )</cf> syntax.
|
defined using <cf>defined( <m>attribute</m> )</cf> syntax.
|
||||||
|
|
||||||
|
|
||||||
<descrip>
|
<descrip>
|
||||||
<tag/<m/prefix/ network/
|
<tag/<m/prefix/ net/
|
||||||
network this route is talking about.
|
network this route is talking about.
|
||||||
|
|
||||||
|
<tag/<m/int/ preference/
|
||||||
|
preference of this route.
|
||||||
|
|
||||||
<tag/<m/ip/ from/
|
<tag/<m/ip/ from/
|
||||||
who told me about this route.
|
who told me about this route.
|
||||||
|
|
||||||
|
@ -441,6 +497,12 @@ defined using <cf>defined( <m>attribute</m> )</cf> syntax.
|
||||||
|
|
||||||
<tag/<m/enum/ source/
|
<tag/<m/enum/ source/
|
||||||
what protocol told me about this route. This can have values such as <cf/RTS_RIP/ or <cf/RTS_OSPF_EXT/.
|
what protocol told me about this route. This can have values such as <cf/RTS_RIP/ or <cf/RTS_OSPF_EXT/.
|
||||||
|
|
||||||
|
<tag/<m/enum/ scope/
|
||||||
|
|
||||||
|
<tag/<m/enum/ cast/
|
||||||
|
|
||||||
|
<tag/<m/enum/ dest/
|
||||||
</descrip>
|
</descrip>
|
||||||
|
|
||||||
<p>Plus, there are protocol-specific attributes, which are described in protocol sections.
|
<p>Plus, there are protocol-specific attributes, which are described in protocol sections.
|
||||||
|
@ -1014,11 +1076,18 @@ protocol static {
|
||||||
}
|
}
|
||||||
</code>
|
</code>
|
||||||
|
|
||||||
<sect>Getting more help
|
<sect>Problems
|
||||||
|
|
||||||
<p>This is really last section of this file, should give pointers to
|
<p>BIRD is relatively young system, and probably contains some
|
||||||
programmers documentation, web pages mailing lists and similar stuff.
|
bugs. You can report bugs at <HTML URL="fixme">, but before you do,
|
||||||
|
please make sure you are running latest version (available at <HTML
|
||||||
|
URL="fixme">), and that bug was not already reported by someone else
|
||||||
|
(mailing list archives are at <HTML URL="fixme">). (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 <HTML URL="fixme">.
|
||||||
|
|
||||||
|
<p><it/Good luck!/
|
||||||
|
|
||||||
</article>
|
</article>
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue