Jerry/bird
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Documentation update.

Browse source
This commit is contained in:
Pavel Machek 2000-05-28 19:11:08 +00:00
parent cdc25e8db7
commit d150c6379c
2 changed files with 143 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

97
TODO
View file

@ -56,3 +56,100 @@ OSPF
- RFC1587 NSSA areas
- RFC2370 opaque LSA's
- respect interface MTU and try not to create larger packets unless unavoidable
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.
Uvod:
o "What is bird": tam by melo byt receno, _co_ je BIRD, nikoliv cemu se podoba.
To obnasi jednak par vet o tom, o co se vlastne snazi, potom nejaky feature
list (s odkazy do jednotlivych casti dokumentace?) a tez neco na tema "v cem
jsme lepsi nez konkurence" (a neargumentovat pouze licenci :) ).
Rovnez tak neni vubec urcen jen pro unixove systemy -- je velice portabilni
a shodou okolnosti Unix (presneji Linux) je jediny zatim napsany port.
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.
Filtry:
o Na zacatku zejmena vysvetlit, jak jsou filtry do systemu zapojeny, k cemu slouzi,
ze dostanou routu a ocekava se od nich verdikt. Teprve pak vysvetlovat, ze to
jsou programy, ze mohou volat funkce atd. Tez zminit, ze protokol ma pravo
nektere routy akceptovat/odmitnout bez toho, aniz by se zeptal filtru.
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 Popsat runtime errory a ze se chovaji jako rejecty.
o Typy: tez rici, ze integery se lisi nejen od booleanu, ale take od enumu.
o Boolean: TRUE nebo true? U kazdeho typu zminit, jak vypadaji literaly
tohoto typu a psat je vzdycky tt fontem.
o int: Nadefinovat rozsah a rici, ze preteceni se nekontroluje. Zminit
hexadecimalni konstanty.
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 operations: ~ pracuje i na clistech, neni-liz pravda?
o Examply by mohly byt krapet smysluplnejsi.
o defined(): To, ze undefined attribute cannot be accessed, by melo byt
rozhodne receno nekde jinde (v uvodu sekce) -- vzdyt u defined samotneho
to mozne je.
o attributes: nemyslim, ze jsou vsechny -- co treba scope a preference?
o Chybi operace na clistech a cestach.
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 U kazdeho protokolu rici, jestli podporujeme pouze IPv4 nebo i IPv6 verzi.
o RIP: Vysvetlit, na ktere site se RIP hodi a na ktere ne, rici, ze je
hodnoty spise historicke, ale ze ve svete IPv6 se bezne pouziva, protoze
zatim neexistuji slusne implementace OSPFv3.
o RIP: Per-interface optiony uvadet tez jako definition list.
o RIP: U RIP-specific atributu zminit, jakeho jsou typu a jak vznikaji.
o Example u RIPu je out of date: `honour' -> `honor' apod. Tez ukazat
per-interface optiony.
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).
K jazyku:
o K "BIRD Internet Routing Daemon" by mel patrit urcity clen.
o Nerika se `comparation', nybrz `comparison'.
o RFC (a ostatni zkratky) psat vzdy velkymi pismeny.
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'.

80
doc/bird.sgml
View file

@ -1,7 +1,7 @@
<!doctype linuxdoc system>
<!--
Bird documentation
BIRD documentation
Look for "about this documentation" section to learn more.
@ -13,7 +13,7 @@
<article>
<title>Bird
<title>BIRD
<author>
Pavel Machek <tt/pavel@ucw.cz/
@ -29,15 +29,15 @@ This document contains documentation for BIRD Internet Routing Daemon
<sect>Introduction
<sect1>What is bird
<sect1>What is BIRD
<p><label id="intro"> You may wonder what 'bird' means. It is acronym of 'BIRD Internet Routing
<p><label id="intro"> You may wonder what 'BIRD' means. It is acronym of 'BIRD Internet Routing
Daemon', and we think that's cool name. Its task is similar to what firmware of Cisco routers does,
or what gated <HTMLURL URL="http://www.gated.org/"> or GNU zebra <HTMLURL
URL="http://www.zebra.org/"> does. However, you can not run Cisco's firmware on "normal" computer
and gated is really hard to configure and comes under wrong license. Bird is being developed on
and gated is really hard to configure and comes under wrong license. BIRD is being developed on
Charles University, Prague, and can be freely distributed under terms of GNU General Public
License. Bird is designed to run on Unix and unix-like systems, it is primarily developed on Linux.
License. BIRD is designed to run on Unix and unix-like systems, it is primarily developed on Linux.
<sect1>About this documentation
@ -61,6 +61,12 @@ section in filters.
<sect1>Introduction
<p>BIRD is configured using text configuration file. At startup, BIRD reads <file/bird.conf/ (unless
-c command line parameter is given). Configuration may be changed on user request: if you modify
config file and then signal BIRD with SIGHUP, it will adjust to new config. There's BIRD client,
which allows you to talk with BIRD in more extensive way than just telling it to reconfig. BIRD
writes messages about its work to log files or syslog (according to config).
<p>Bird is configured using text configuration file. At startup, bird
reads <file/bird.conf/ (unless -c command line parameter is
given). Everything on a line after <cf/#/ is a comment, whitespace is
@ -68,13 +74,11 @@ ignored, C-style comments <cf>/* comment */</cf> are also
recognized. If there's variable number of options, it is grouped using
<cf/{ }/ brackets. Each option is terminated by <cf/;/.
<p>Really simple configuration file might look like this, you can find
example of more complicated configuration file in
<file>doc/bird.conf.example</file>.
<p>Really simple configuration file might look like this:
<code>
protocol kernel {
persist; # Don't remove routes on bird shutdown
persist; # Don't remove routes on BIRD shutdown
scan time 20; # Scan kernel routing table every 20 seconds
export all; # Default is export none
}
@ -98,42 +102,44 @@ protocol rip {
<cf/debug/ for debugging message, <cf/trace/, <cf/info/,
<cf/remote/ for messages about misbehavior of remote side, <cf/warning/,
<cf/error/, <cf/auth/, <cf/fatal/, <cf/bug/ for internal bugs
of bird. You may specify more than one <cf/log/ line to log to multiple
of BIRD. You may specify more than one <cf/log/ line to log to multiple
destinations.
<tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
sets global default of debugging options.
sets global default of protocol debugging options.
<tag>filter <m/name/{ <m/commands/ }</tag> define filter. You can learn more about filters
in next chapter.
<tag>protocol rip|ospf|bgp <m/[name]/ { <m>protocol options</m> }</tag> define protocol
<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> define protocol
instance, called name (or called something like rip5 if you omit name). You can learn more
about configuring protocols in their own chapters.
about configuring protocols in their own chapters. You can run more than one instance of
most protocols (like rip or bgp).
<tag>define constant = expression</tag> define constant. You can use it later in every place
you could use simple integer.
<tag>router id <m/num.num.num.num/</tag> set router id. Router
id needs to be world-wide unique 32bit number, identifying
router. It is usually one of router's IP addresses.
<tag>router id <m/IPv4 address/</tag> set router id. Router id needs to be world-wide
unique. It is usually one of router's IPv4 addresses.
<tag>table <m/name/</tag> create new routing table.
<tag>eval <m/expr/</tag> evaluates given filter expression. It is used for testing.
</descrip>
<sect1>Per-protocol options
<sect1>Protocol options
<p>Several options are per-protocol, but all protocols support them. They are described here.
<descrip>
<tag>preference <m/expr/</tag> sets preference of this protocol.
<tag>preference <m/expr/</tag> sets preference of routes generated by this protocol.
<tag>disabled</tag> disables given protocol.
<tag>disabled</tag> disables given protocol. You can disable/enable protcol from command
line interface without needing to touch config.
<tag>debug <m/setting/</tag> this is similar to global debug setting, except that it only
affects one protocol.
affects one protocol. Only messages in selected debugging categories will be written to
logs.
<tag>import <m/filter/</tag> filter can be either either <cf> { <m>filter commands</m>
}</cf> or <cf>filter <m/name/</cf>. Import filter works in direction from protocol to main
@ -153,18 +159,20 @@ protocol rip {
time from which password is not announced but is allowed. id is password id, as needed by
certain protocols.
<tag>interface "<m/mask/" [ { <m/option/ ; [ ... ] } ]</tag> specifies, which interfaces
this protocol is active at, and allows you to set options on interface-by-interface
basis. Mask is specified in shell-like patters, thus <cf>interface "*" { mode broadcast;
};</cf> will start given protocol on all interfaces, with <cf>mode broadcast;</cf> option.
<tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [ ... ] } ]</tag> specifies, which
interfaces this protocol is active at, and allows you to set options on
interface-by-interface basis. Mask is specified in shell-like patters, thus <cf>interface
"*" { mode broadcast; };</cf> will start given protocol on all interfaces, with <cf>mode
broadcast;</cf> option.
</descrip>
<sect>Filters
<sect1>Introduction
<p>Bird contains rather simple programming language. (No, it can not yet read mail :-). There are
two objects in this language: filters and functions. Filters are called by bird core when route is
<p>BIRD contains rather simple programming language. (No, it can not yet read mail :-). There are
two objects in this language: filters and functions. Filters are called by BIRD core when route is
being passed between protocol and main routing table, and filters may call functions. Functions may
call other functions, but recursion is not allowed. Filter language contains control structures such
as if's and switches, but it allows no loops. Filters are
@ -205,6 +213,10 @@ pairs <cf><M>type name</M>;</cf>, where each pair defines one local variable. Bo
several statements into one by <cf>{ <M>statements</M> }</cf> construction, that is useful if
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:
@ -252,7 +264,7 @@ booleans (that is to prevent you from shooting in the foot).
such variables, but you can not concatenate two strings (for example). String constants
are written as <cf/"This is a string constant"/.
<tag/ip/ this type can hold single ip address. Depending on version of bird you are using, it
<tag/ip/ this type can hold single ip address. Depending on version of BIRD you are using, it
can be IPv4 or IPv6 address. IPv4 addresses are written (as you would expect) as
<cf/1.2.3.4/. You can apply special operator <cf>.mask(<M>num</M>)</cf>
on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from ip
@ -275,7 +287,7 @@ booleans (that is to prevent you from shooting in the foot).
3.0.0.0/8- is shorthand for 3.0.0.0/{0,7}.
<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
variable of enumeration type, but some predefined variables are of enumeration
type. Enumeration types are incompatible with each other, again, for your
protection.
@ -406,12 +418,12 @@ periodic messages onto this interface and <cf>nolisten</cf> means that rip will
interface but not listen on it.
<p>Following options generally override specified behavior from rfc. If you use any of these
options, bird will no longer be rfc-compatible, which means it will not be able to talk to anything
other than equally misconfigured bird. I warned you.
options, BIRD will no longer be rfc-compatible, which means it will not be able to talk to anything
other than equally misconfigured BIRD. I warned you.
<descrip>
<tag>port <M>number</M></tag>
selects IP port to operate on, default 520. (This is useful when testing bird, if you
selects IP port to operate on, default 520. (This is useful when testing BIRD, if you
set this to address &gt;1024, you will not need to run bird with UID==0).
<tag>infinity <M>number</M></tag>
@ -438,8 +450,8 @@ protocol rip MyRIP_test {
port 1520;
period 7;
garbagetime 60;
interface "*";
honour neighbour;
interface "eth0" { metric 3; mode multicast; } "eth1" { metric 2; mode broadcast; };
honor neighbour;
passwords { password "ahoj" from 0 to 10;
password "nazdar" from 10;
}