From a7c9f7c065907e310ce1954821f2a8fc61c0261b Mon Sep 17 00:00:00 2001 From: Pavel Machek Date: Tue, 6 Jun 2000 20:35:59 +0000 Subject: Batch of mj's corrections (config + filters) --- doc/bird.sgml | 240 ++++++++++++++++++++++++++++------------------------------ 1 file changed, 117 insertions(+), 123 deletions(-) (limited to 'doc') diff --git a/doc/bird.sgml b/doc/bird.sgml index 7c8d6c72..73bbf849 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -96,7 +96,6 @@ Public License. tested under Linux 2.0 to 2.4, but porting to other systems (even non-UNIX ones) should be relatively easy due to its highly modular architecture. - Installing BIRD

On a recent UNIX system with GNU development tools (GCC, binutils, m4, make) and Perl, installing BIRD should be as easy as: @@ -270,44 +269,42 @@ protocol rip { affects one protocol. Only messages in selected debugging categories will be written to the logs. - import filter can be either either { filter commands - } or filter or import { Specify a filter to be used for filtering routes comming from protocol tothe routing table. Default: export This is similar to export keyword, except that it - works in direction from main routing table to protocol. + export This is similar to import keyword, except that it + works in direction from the routing table to the protocol. Default: table Connect this protocol to non-default table. + table Connect this protocol to a non-default routing table. -

There are per-protocol options that give sense only with certain protocols. +

There are several options that give sense only with certain protocols: passwords { password " specifies passwords to be used with this protocol. Passive time is - time from which password is not announced, but is recognized on reception. id is password id, as needed by + Specifies passwords to be used with this protocol. Passive is + time from which the password is not used for sending, but it is recognized on reception. 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 + interface " Specifies which + interfaces this protocol is active on, and allows you to set options on + per-interface basis. Mask is specified in shell-like patterns, thus interface + "*" { mode broadcast; }; will start the protocol on all interfaces with mode broadcast; option. If first character of mask is Client -

You can use command-line client birdc to talk with -running BIRD. Communications is done using You can use the command-line client birdc to talk with +a running BIRD. Communication is done using 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 +

BIRD contains a rather simple programming language. (No, it can't yet read mail :-). There are +two objects in this language: filters and functions. Filters are called by BIRD core when a route is +being passed between protocola and routing tables. Filter language contains control structures such as if's and switches, but it allows no loops. Filters are -interpreted. Filter using many features can be found in filter/test.conf. +interpreted. An example of a filter using many features can be found in filter/test.conf. -

Filter 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 Filter gets the route, looks at its attributes and +modifies some of them if it wishes. At the end, it decides whether to +pass the changed route through (using @@ -346,15 +342,15 @@ int var; } -

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

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. They +over. Functions can have zero or more parameters and they can have local variables. Recursion is not allowed. They look like this: @@ -370,27 +366,24 @@ function with_parameters (int parameter) } -

Unlike C, variables are declared after function line but before first {. You can not declare +

Unlike in C, variables are declared after function line but before the first {. You can't declare variables in nested blocks. Functions are called like in C: name(); -with_parameters(5);. Function may return value using return -syntax. Returning value exits from current function (this is similar to C). +with_parameters(5);. Function may return value using the return +command. Returning a 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 -Filters are declared in a way similar to functions except they can't have explicit +parameters. They get route table entry as an implicit parameter, it is also passed automatically +to any functions called. The filter must terminate with either +Nice trick to debug filters is using show route filter - from command line client. Example session might look +

A nice trick to debug filters is to use show route filter + from the command line client. An example session might look like: pavel@bug:~/bird$ ./birdc -s bird.ctl BIRD 0.0.0 ready. -bird> help -No such command. -bird> bird> show route 10.0.0.0/8 dev eth0 [direct1 23:21] (240) 195.113.30.2/32 dev tunl1 [direct1 23:21] (240) @@ -404,32 +397,32 @@ bird> Data types -

Each variable and each value has certain type. Unlike C, booleans, integers and enums are +

Each variable and each value has certain type. 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: @@ -437,74 +430,78 @@ incompatible with each other (that is to prevent you from shooting in the foot). len from the pair. So 1.2.0.0/16.pxlen = 16 is true. set int looks like + Filters recognize four types of sets. Sets are similar to strings: you can pass them around + but you can't modify them. Literals of type set int look 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 prefix lengths 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 prefix length 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}. For example, - 1.2.0.0/16 ~ [ 1.0.0.0/8{ 15 , 17 } ] is true, but - 1.0.0.0/8 ~ [ 1.0.0.0/8- ] is false. + 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.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}. For example, + 1.2.0.0/16 ~ [ 1.0.0.0/8{ 15 , 17 } ] is true, but + 1.0.0.0/8 ~ [ 1.0.0.0/8- ] is false. path ~ / 2 3 5 ? / syntax ). Matching is - done using shell-like pattern: path ˜ /2 3 5 ?/ syntax). Matching is + done using shell-like patterns: /* which is start of comment.) For example, - / 4 3 2 1 / ~ / ? 4 3 ? / is true, but - / 4 3 2 1 / ~ / ? 4 5 ? / is false. + /4 3 2 1/ ~ /? 4 3 ?/ is true, but + /4 3 2 1/ ~ /? 4 5 ?/ is false. -Operations +Operators -

Filter language supports common integer operations (+,-,*,/), parentheses + +

The filter language supports common integer operators (+,-,*,/), parentheses ). +is true if element is in given set or if ip address is inside given prefix. Logical operations include unary not (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 { +

Filters support two control structures: conditions and case switches. + + + +

Syntax of condition is if +boolean expression then command; else command; and you can use { command_1; command_2; ... } instead of one or both commands. else 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 . Expression after +case can be of any type that can be on the left side of the ˜ operator, and anything that could +be a member of a set is allowed before Here is example that uses if and case structures: +

Here is example that uses case arg1 { 2: print "two"; print "I can do more commands without {}"; 3 .. 5: print "three to five"; else: print "something else"; - } +} if 1234 = i then printn "."; else { print "not 1234"; @@ -514,58 +511,58 @@ if 1234 = i then printn "."; else { Route attributes -

Filter is implicitly passed route, and it can access its -attributes, just like it accesses variables. Access to undefined -attribute results in runtime error; you can check if attribute is -defined using defined( attribute ) syntax. +

An filter is implicitly passed route, and it can access its +attributes just like it accesses variables. Attempt to access undefined +attribute result in a runtime error; you can check if an attribute is +defined using the defined( attribute ) operator. + + - network this route is talking about. (See section about routing tables) + Network the route is talking about. (See the section about routing tables.) + + + Address scope of the network () - preference of this route. (See section about routing tables) + Preference of the route. (See section about routing tables.) - who told me about this route. + The router which the route has originated from. - what is next hop packets routed using this route should be forwarded to. + Next hop packets routed using this route should be forwarded to. - what protocol told me about this route. This can have values such as - FIXME! + what protocol has told me about this route. Possible values: . - FIXME! + Route type () - FIXME! + Type of destination the packets should be sent to ( -

Then there are protocol-specific attributes, which are described in protocol sections. +

There also exist some protocol-specific attributes, which are described in protocol sections. Statements -

Following statements are supported: +

The following statements are available: - set variable to give value. - - accept [ accept this route, possibly printing expr + Set variable to a given value. - reject reject this route + accept|reject [ Accept or reject the route, possibly printing expr. - return return given value from function, function ends at this point. + return Return expr from function, the function ends at this point. - print|printn - prints given expressions, useful mainly while debugging - filters. Printn variant does not go to new line. + print|printn + Prints given expressions; useful mainly while debugging + filters. The quitbird - terminates bird. Useful while debugging filter interpreter. + Terminates BIRD. Useful when debugging filter interpreter. Protocols @@ -991,7 +988,7 @@ it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, 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 +counting to infinity is necessary, because it is slow. Due to infinity being 16, you can't 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, historical RIPv1 is @@ -1134,17 +1131,14 @@ protocol static { Problems

BIRD is relatively young system, and probably contains some -bugs. You can report bugs at , but before you do, +bugs. You can report bugs at bird-users mailing list (), but before you do, please make sure you have read available documentation, make sure are running latest version (available at ), and that bug was not already reported by someone else -(mailing list archives are at ). (Of course, patch +URL="ftp://bird.network.cz/pub/bird" TEXT="bird.network.cz:/pub/bird>). (Of course, patch 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 home page of bird is . When +want to use BIRD, join mailing list by sending +. Main home page of bird is . When trying to understand, what is going on, Internet standards are -relevant reading; you can get them from . +relevant reading; you can get them from (or nicely sorted version from .