diff --git a/doc/bird.sgml b/doc/bird.sgml index 013c7dd5..17ff37e4 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -3,7 +3,9 @@ +

On recent UNIX (with GNU-compatible tools - BIRD relies on GCC extensions) +system, installing BIRD should be as easy as: ./configure @@ -142,7 +154,7 @@ options. Most important (and not easily guessed) option is enable debugging. -D - log debugging information to given file + log debugging information to given file. -s use given filename for socket for communications with bird client, default is BIRD is configured using text configuration file. At startup, BIRD reads Bird is configured using text configuration file. At startup, bird -reads In config, everything on a line after /* +*/ is a comment, whitespace is ignored, C-style comments /* comment */ are also -recognized. If there's variable number of options, it is grouped using -Really simple configuration file might look like this: It enables +synchronization of routing tables with kernel, scans for +new network interfaces every 10 seconds and runs RIP on all interfaces found. -

Really simple configuration file might look like this: protocol kernel { @@ -184,6 +200,7 @@ protocol rip { } + Global options

@@ -202,7 +219,11 @@ protocol rip { debug protocols all|off|{ states, routes, filters, interfaces, events, packets } sets global default of protocol debugging options. - filter define filter. You can learn more about filters + filter define filter. You can learn more about filters + in next chapter. + + function define function. You can learn more + about functions in next chapter. protocol rip|ospf|bgp|... protocol options } define protocol @@ -210,15 +231,18 @@ protocol rip { about configuring protocols in their own chapters. You can run more than one instance of most protocols (like rip or bgp). - define constant = expression define constant. You can use it later in every place + define constant = ( define constant. You can use it later in every place you could use simple integer. router id set router id. Router id needs to be world-wide unique. It is usually one of router's IPv4 addresses. - table create new routing table. + table create new routing table. Default + routing table is created implicitly, other routing tables have + to be added by this command. - eval evaluates given filter expression. It is used for testing. + eval evaluates given filter expression. It + is used by us for testing. Protocol options @@ -229,15 +253,15 @@ protocol rip { preference sets preference of routes generated by this protocol. disabled disables given protocol. You can disable/enable protocol from command - line interface without needing to touch config. + line interface without needing to touch config. Disabled protocol is not activated. debug this is similar to global debug setting, except that it only affects one protocol. Only messages in selected debugging categories will be written to logs. import filter can be either either { filter commands - } or filter . Import filter works in direction from protocol to main - routing table. + } or filter or export This is similar to export keyword, except that it works in direction from main routing table to protocol. @@ -250,14 +274,16 @@ protocol rip { passwords { password " specifies passwords to be used with this protocol. Passive time is - time from which password is not announced but is allowed. id is password id, as needed by + time from which password is not announced, but is recognized on reception. id is password id, as needed by certain protocols. interface " 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 interface "*" { mode broadcast; }; will start given protocol on all interfaces, with mode - broadcast; option. + broadcast; option. If first character of mask is @@ -289,7 +315,7 @@ interpreted. Filter using many features can be found in filter/test.confFilter basically gets the route, looks at its attributes and modifies some of them if it wishes. At the end, it decides, whether to -pass change route through (using @@ -312,16 +338,13 @@ int var;

As you can see, filter has a header, list of local variables, and body. Header consists of type name;, where each pair defines one local variable. Body consists of - { statements }. Statements are terminated by { statements }. Each Statement is terminated by { statements } construction, that is useful if you want to make bigger block of code conditional. -

There are two special filters, 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: +over. Functions can have zero or more parameters, and can have local variables. They +look like this: function name () @@ -344,7 +367,7 @@ syntax. Returning value exits from current function (this is similar to C).

Filters are declared in similar way to functions, except they can not have explicit parameters. They get route table entry as implicit parameter. Route table entry is passed implicitly to any functions being called. Filter must terminate with either -accept or reject statement. If there's runtime error in filter, route +Nice trick to debug filters is using show route filter @@ -370,12 +393,12 @@ bird> Data types -

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

Each variable and each value has certain type. Unlike C, booleans, integers and enums are +incompatible with each other (that is to prevent you from shooting in the foot). - .mask(num) on values of type ip. It masks out all but first num bits from ip address. So ipaddress/pxlen, or ipaddress/netmask There are two special operators on prefix: 1.2.0.0/16.pxlen = 16 is true. - set int looks like [ 1, 2, 5..7 ]. As you can see, both simple values and ranges are permitted in @@ -414,13 +437,13 @@ booleans and between integers and enums (that is to prevent you from shooting in 1.0.0.0/8 ~ [ 1.0.0.0/8- ] is false. /* which is start of comment.) For example, - / 4 3 2 1 / ~ / ? 4 3 ? 1 / is true, but + / 4 3 2 1 / ~ / ? 4 3 ? / is true, but / 4 3 2 1 / ~ / ? 4 5 ? / is false. @@ -447,7 +471,7 @@ booleans and between integers and enums (that is to prevent you from shooting in used on element and set of that elements, or on ip and prefix, or on prefix and prefix or on bgppath and bgpmask or on pair and clist. Its result is true if element is in given set or if ip address is inside given prefix. Operator ). Control structures @@ -459,8 +483,9 @@ clause may be omitted.

case is similar to case from Pascal. Syntax is case . Expression after case can be of any type 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, +be member of set is allowed before Here is example that uses if and case structures: @@ -472,7 +497,7 @@ case arg1 { else: print "something else"; } -if 1234 = i then printn "."; else { print "*** FAIL: if 1 else"; } +if 1234 = i then printn "."; else { print "not 1234"; print "You need {} around multiple commands"; } Route attributes @@ -484,10 +509,10 @@ defined using defined( attribute ) syntax. defined( attribute ) syntax.

There are few functions you might find convenient to use: + accept accept this route + + reject reject this route + + return return given value from function, function ends at this point. + print|printn prints given expressions, useful mainly while debugging filters. Printn variant does not go to new line. @@ -539,7 +570,7 @@ Boundary routers at the border of the AS communicate with their peers in the neighboring AS'es via exterior BGP (eBGP).

Each BGP router sends to its neighbors updates of the parts of its -routing table it wishes to export along with complete path information +routing table it wishes to export, along with complete path information (a list of AS'es the packet will travel through if it uses that particular route) in order to avoid routing loops. @@ -644,7 +675,7 @@ table below) are available on internal BGP connections only, some of them (marke with `O') are optional. - path Sequence of AS numbers describing the AS path + bgppath Sequence of AS numbers describing the AS path the packet will travel through when forwarded according to this route. On internal BGP connections it doesn't contain the number of the local AS. int Local preference value used for @@ -654,10 +685,10 @@ with `O') are optional. which is an optional attribute which is often used within the local AS to reflect interior distances to various boundary routers. See the route selection rules above for exact semantics. - enum Origin of the route: either enum Origin of the route: either EGP protocol - (nowadays it seems to be obsolete) or EGP protocol + (nowadays it seems to be obsolete) or ip Next hop to be used for forwarding of packets to this destination. On internal BGP connections, it's an address of the @@ -678,7 +709,7 @@ with `O') are optional. the community and the second one is a per-AS identifier. There are lots of uses of the community mechanism, but generally they are used to carry policy information like "don't export to USA peers". As each AS can define - its own routing policy, it's also has a complete freedom about which community + its own routing policy, it also has a complete freedom about which community attributes it defines and what their semantics will be. @@ -783,7 +814,7 @@ kernel table.

persist Tell BIRD to leave all its routes in the - routing tables when it exits instead of cleaning them up. + routing tables when it exits (instead of cleaning them up). scan time Time in seconds between two scans of the kernel routing table. learn Enable learning of routes added to the kernel @@ -795,7 +826,7 @@ kernel table. only on systems supporting multiple routing tables. -

A default simple configuration can look this way: +

A simple configuration can look this way:

protocol kernel { @@ -837,10 +868,10 @@ and vice versa, depending on what's allowed by the filters. Export filters contr of routes from the primary table to the secondary one, import filters control the opposite direction. -

The primary use of multiple routing tables and the pipe protocol is for policy routing +

The primary use of multiple routing tables and the pipe protocol is for policy routing, where handling of a single packet doesn't depend only on its destination address, but also on its source address, source interface, protocol type and other similar parameters. -In many OS'es (Linux 2.2 being a good example) the kernel allows to enforce routing policies +In many systems (Linux 2.2 being a good example) the kernel allows to enforce routing policies by defining routing rules which choose one of several routing tables to be used for a packet according to its parameters. Setting of these rules is outside the scope of BIRD's work (you can use the 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 +

Rip protocol (sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts +distances to all networks it 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 necessary, 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 . Both IPv4 and IPv6 versions of rip are supported by BIRD. +URL="http://www.ietf.org/html.charters/rip-charter.html">. Both IPv4 +and IPv6 versions of rip are supported by BIRD, historical Ripv1 is +currently not fully supported.

Rip is very simple protocol, and it is not too good. Slow convergence, big network load and inability to handle bigger networks @@ -987,7 +1020,8 @@ other than equally misconfigured BIRD. I warned you. period number specifies number of seconds between periodic updates. Default is 30 seconds. Lower - number will mean faster convergence but bigger network load. + number will mean faster convergence but bigger network + load. Do not use values lower than 10. timeout time number specifies how old route has to be to be considered unreachable. Default is 4*period. @@ -1016,13 +1050,10 @@ other than equally misconfigured BIRD. I warned you. protocol rip MyRIP_test { debug all; port 1520; - period 7; - garbagetime 60; + period 10; + garbage time 60; interface "eth0" { metric 3; mode multicast; } "eth1" { metric 2; mode broadcast; }; - honor neighbour; - passwords { password "ahoj" from 0 to 10; - password "nazdar" from 10; - } + honor neighbor; authentication none; import filter { print "importing"; accept; }; export filter { print "exporting"; accept; }; @@ -1047,12 +1078,11 @@ packet.

When the particular destination is not available (the interface is down or the next hop of the route is not a neighbor at the moment), Static just -uninstalls the route from the table its connected to and adds it again as soon +uninstalls the route from the table it is connected to and adds it again as soon as the destinations becomes adjacent again.

The Static protocol has no configuration options. Instead, the -definition of the protocol contains a list of static routes which -can contain: +definition of the protocol contains a list of static routes: route Static route through @@ -1081,10 +1111,14 @@ protocol static {

BIRD is relatively young system, and probably contains some bugs. You can report bugs at , but before you do, -please make sure you are running latest version (available at ), and that bug was not already reported by someone else (mailing list archives are at ). (Of course, patch -which fixes the bug along with bug report is always welcome). When +which fixes the bug along with bug report is always welcome). If you +want to join the development, join developer's mailing list by sending +. You can also get current sources from +anoncvs at . You can find this documentation online +at , main homepage of bird is . When trying to understand, what is going on, Internet standards are relevant reading; you can get them from .