Documentation update
This commit is contained in:
Pavel Machek
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)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
|
|
|
|||
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
|
||||
"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
|
||||
|
||||
<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>
|
||||
./configure
|
||||
make
|
||||
make install
|
||||
vi /usr/local/etc/bird.conf
|
||||
bird
|
||||
</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
|
||||
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.
|
||||
<descrip>
|
||||
<tag>-c <m/config name/</tag>
|
||||
use given config file instead of <file>bird.conf</file>.
|
||||
|
||||
<tag>-d</tag>
|
||||
enable debugging.
|
||||
|
||||
<tag>-D <m/filename for debug log/</tag>
|
||||
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
|
||||
|
||||
|
|
@ -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 <tt/?/ at any time to get online help. Option
|
||||
<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
|
||||
|
||||
|
|
@ -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
|
||||
all routes).
|
||||
|
||||
|
||||
<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
|
||||
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.
|
||||
|
||||
<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
|
||||
|
||||
<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
|
||||
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
|
||||
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
|
||||
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/
|
||||
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/
|
||||
bgp mask is mask used for matching bgp paths
|
||||
(using <cf>path ~ / 2 3 5 ? / syntax </cf>). <cf/?/ is
|
||||
really serving in "any number of autonomous systems", but we
|
||||
(using <cf>path ~ / 2 3 5 ? / syntax </cf>). Matching is
|
||||
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
|
||||
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/
|
||||
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
|
||||
defined using <cf>defined( <m>attribute</m> )</cf> syntax.
|
||||
|
||||
|
||||
<descrip>
|
||||
<tag/<m/prefix/ network/
|
||||
<tag/<m/prefix/ net/
|
||||
network this route is talking about.
|
||||
|
||||
<tag/<m/int/ preference/
|
||||
preference of this route.
|
||||
|
||||
<tag/<m/ip/ from/
|
||||
who told me about this route.
|
||||
|
||||
|
|
@ -441,6 +497,12 @@ defined using <cf>defined( <m>attribute</m> )</cf> syntax.
|
|||
|
||||
<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/.
|
||||
|
||||
<tag/<m/enum/ scope/
|
||||
|
||||
<tag/<m/enum/ cast/
|
||||
|
||||
<tag/<m/enum/ dest/
|
||||
</descrip>
|
||||
|
||||
<p>Plus, there are protocol-specific attributes, which are described in protocol sections.
|
||||
|
|
@ -1014,11 +1076,18 @@ protocol static {
|
|||
}
|
||||
</code>
|
||||
|
||||
<sect>Getting more help
|
||||
<sect>Problems
|
||||
|
||||
<p>This is really last section of this file, should give pointers to
|
||||
programmers documentation, web pages mailing lists and similar stuff.
|
||||
<p>BIRD is relatively young system, and probably contains some
|
||||
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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue