Documentation update.
This commit is contained in:
Pavel Machek
parent
cdc25e8db7
commit
d150c6379c
97
TODO
97
TODO
|
|
@ -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'.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 >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;
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue