diff --git a/doc/bird.html b/doc/bird.html new file mode 100644 index 00000000..2401ede9 --- /dev/null +++ b/doc/bird.html @@ -0,0 +1,200 @@ +Bird + + + + + +

Introduction

+ +

You may wonder what 'bird' means. It is acronym of 'Basic Internet Routing Daemon', and we think +that's cool name. Its task is similar to what firmware of Cisco routers does, or what gated 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 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. + +

About this documentation

+ +

This documentation can have 4 forms: extended html (this is master copy), html with stripped +extensions, ascii text (generated from html) and dvi/postscript (generated from html using +html2latex and latex). You should always edit master copy; if you do so be sure to read comment at +beggining of file. If you want to view documentation, you can either launch your www browser at +master copy (and hope that browser does not have incompatible extensions from our), or you can +generate nice printed copy. + +

Bird configuration

+ +

Bird is configured using text configuration file. At startup, bird reads bird.conf +(unless -c command line parameter is given). Really simple configuration file might look like this: + +

+
+protocol kernel {
+	persist;		# Don't remove routes on bird shutdown
+	scan time 20;		# Scan kernel routing table every 20 seconds
+	export all;		# Default is export none
+}
+
+protocol device {
+	scan time 10;		# Scan interfaces every 10 seconds
+}
+
+protocol rip {
+	export all;
+	import all;
+}
+
+ +

You can find example of more complicated configuration file in doc/bird.conf.example. + +

Filters

+ +

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 interpretted. + +

You can find sources of filters language in filter/ directory. filter/config.Y contains filter gramar, and basically translates source from user into +tree of f_inst structures. These trees are later interpreted using code in filter/filter.c. Filters internally work with values/variables in struct f_val, +which contains type of value and value. + +

Filter basically looks like this: + +

+filter not_too_far
+int var;
+{
+	if defined( rip_metric ) then
+		var = rip_metric;
+	else {
+		var = 1;
+		rip_metric = 1;
+	}
+	if rip_metric > 10 then
+		reject "RIP metric is too big";
+	else
+		accept "ok";
+}
+
+ +

As you can see, filter has a header, list of local variables, and body. Header consists of filter keyword, followed by (unique) name of filter. List of local variables consists of +pairs type name;, where each pair defines one local variable. Body consists of + { statments }. Statements are terminated by ;. You can group +several statments into one by { statments } construction, that is usefull if +you want to make bigger block of code conditional. + +

Variables

+ +

Each variable and each value has certain type. Unlike C, filters distinguish between integers and +booleans (that is to prevent you from shooting in the foot). + +

+
bool +
this is boolean type, it can have only two values, TRUE and FALSE. Boolean is not compatible with integer and is the only type you can use + in if statments. + +
int +
this is common integer, you can expect it to store signed values from -2000000000 to + +2000000000. + +
pair +
this is pair of two short integers. Each component can have values from 0 to + 65535. Constant of this type is written as (1234,5678). + +
string +
this is string of characters. There are no ways to modify strings in filters. You can + pass them between functions, assign to variable of type string, print such variables, but + you can not concatenate two strings (for example). String constants are written as "This is string constant". + +
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 addresses are written (as you would expect) as + 1.2.3.4. You can apply special operator .mask(num) + on values of type ip. It masks out all but first num bits from ip + address. So 1.2.3.4.mask(8) = 1.0.0.0 is true. + +
prefix +
this type can hold ip address, prefix len pair. Prefixes are written as ip + address/px len. There are two special operators on prefix: .ip, which separates ip address from the pair, and .len, which + separates prefix len from the pair. + +
set int|ip|prefix|pair +
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 set int looks like + [ 1, 2, 5..7 ]. 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 + using [ 1.0.0.0/8+, 2.0.0.0/8-, 3.0.0.0/8{5,6} ]. + +
enum +
enumerational types are halfway-internal in the bird. You can not define your own + variable of enumerational type, but some pre-defined variables are of enumerational + type. Enumerational types are incompatible with each other, again, its for your + protection. +
+ +

Protocols

+ +

Rip

+ +

Rip protocol (sometimes called Rest In Pieces) is simple protocol, where each router broadcasts +distances to all networks he can reach. When router hears distance to other network, it increments +it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes +unreachable, routers keep telling each other that distance is old distance plus 1. After some time, +distance reaches infinity (that's 15 in rip) and all routers know that network is unreachable. Rip +tries to minimize situations where counting to infinity is neccessary, because it is slow. Due to +infinity being 15, you can not use rip on networks where maximal distance is bigger than 15 +hosts. You can read more about rip at rfc1234. + +

Configuration

+ +

In addition to options generic to other protocols, rip supports following options: + +

+
port number +
selects IP port to operate on, default 520. + +
authentication none|password|md5 +
selects authenticaion method to use. None means that packets are not authenticated at + all, password means that plaintext password is embedded into each packet, and md5 means + that packets are authenticated using md5 cryptographics hash. See rfc1234. If you set authentication to non-none, it is good idea to add + passwords { } section. +
+ +
+
+protocol rip MyRIP_test {
+        debug all;
+        port 1520;
+        period 7;
+        garbagetime 60;
+        interface "*";
+        honour neighbour;
+        passwords { password "ahoj" from 0 to 10;
+                password "nazdar" from 10;
+        }
+        authentication none;
+        import filter { print "importing"; accept; };
+        export filter { print "exporting"; accept; };
+}
+
+ +