mirrors/bird
mirrors/bird
0
0
Fork 0
mirror of https://gitlab.nic.cz/labs/bird.git synced 2024-12-22 01:31:55 +00:00
Code Releases Activity

Documentation update

Browse Source
This commit is contained in:
Pavel Machek 2000-05-31 21:51:04 +00:00
parent 0b1cad8162
commit c184d9d0bd
2 changed files with 93 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
TODO
View File

@ -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
View File

@ -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>