diff --git a/doc/bird.html b/doc/bird.html deleted file mode 100644 index 5c157114..00000000 --- a/doc/bird.html +++ /dev/null @@ -1,297 +0,0 @@ -Bird - - - - - -

Introduction

- -

What is bird

- -

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

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

- -

Introduction

- -

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. Filter using many features can be found in filter/test.conf. - -

There's one strange thing with filter language: it does not permit you to create loops. There's -no equivalent of while() or for() command, and recursive functions are not permitted. - -

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

Data types

- -

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} ]. 3.0.0.0/8{5,6} matches - prefixes 3.X.X.X, whose prefixlength 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}. - -
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. -
- -

Operations

- -

Filter language supports common integer operations (+,-,*,/), parenthesis (a*(b+c)), comparation -(a=b, a!=b, a<b, a>=b). Special operators include ~ for "in" operation. In operation can be -used on element and set of that elements, or on ip and prefix, or on prefix and prefix. Its result -is true if element is in given set or if ip adress is inside given prefix. - -

Functions

- -

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

-function name ()
-int local_variable;
-{
-	local_variable = 5;
-}
-
-function with_parameters (int parameter)
-{
-	print parameter;
-}
-
- -

Unlike C, variables are declared after function line but before first {. You can not declare -variables in nested blocks. Functions are called like in C: name(); with_parameters(5);. - -

Filters are declared in similar way to functions, except they can not have explicit -parameters. They get route table entry as implicit parameter. - -

Control structures

- -

Filters support two control structures: if/then/else and case. Syntax of if/then/else is if expression then command; else command; and you can use { -command_1; command_2; ... } instead of one or both commands. else clause may be ommited. Case is used like this: - -

-        case argument {
-        2: print "dva"; print "jeste jednou dva";
-        3 .. 5: print "tri az pet";
-        else: print "neco jineho";
-        }
-
- -where argument is any argument that can be on the left side of ~ operator, and anything that -could be member of set is allowed before :. Multiple commands are allowed without {} grouping. If -argument matches neither of : clauses, else: clause is used. (Case is actually implemented as set -matching, internally.) - -

Protocols

- -

Rip

- -

Introduction

- -

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 (actually, plus -interface metric, which is usually one). 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 16, 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: - -

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

There are two options that can be specified per-interface. First is metric, with -default one. Second is mode broadcast|quiet|nolisten|version1, it selects mode for -rip to work in. If nothing is specified, rip runs in multicasts mode. version1 is -currently equivalent to broadcast, and it makes rip talk at broadcast address even -through multicast mode is possible. quiet option means that rip will not transmit -periodic messages onto this interface and nolisten means that rip will talk to this -interface but not listen on it. - -

Following options generally override specified behaviour 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 (mis-)configured bird. I warned you. - -

-
port number -
selects IP port to operate on, default 520. (This is usefull when testing bird, if you - set this to address >1024, you will not need to run bird with uid==0). - -
infinity number -
select value of infinity, default 16. Bigger values will make protocol convergence - even slower. - -
period number -
specifies number of seconds between periodic updates. Default is 30 seconds. Lower - number will mean faster convergence but bigger network load. - -
timeouttime number -
specifies how old route has to be to be considered unreachable. Default is 4*period. - -
garbagetime number -
specifies how old route has to be to be discarded. Default is 10*period. -
- -

In addition, rip defines two filter variables, both of type it. rip_metric is rip -metric of current route, rip_tag is tag of current route. - -

-
-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; };
-}
-
- -