diff --git a/doc/bird.sgml b/doc/bird.sgml index 913f3f4a..d6d7ca5c 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -177,10 +177,10 @@ protocols. Introduction

BIRD is configured using a text configuration file. Upon startup, BIRD reads $prefix/bird.conf (unless the -In the config, everything on a line after /* */ is a comment, whitespace characters are treated as a single space. If there's a variable number of options, they are grouped using @@ -214,9 +214,9 @@ protocol rip {

log " - Set logging of messages having the given (either protocol rip|ospf|bgp|... protocol options } Define a protocol - instance called (or with a name like "rip5" generated automatically, if you don't specify ). You can learn more + instance called (or with a name like "rip5" generated automatically if you don't specify any ). You can learn more about configuring protocols in their own chapters. You can run more than one instance of most protocols (like RIP or BGP). By default, no instances are configured. define Define a constant. You can use it later in every place - you could use a simple integer or IP address. + you could use a simple integer or an IP address. router id Set BIRD's router ID. It's a world-wide unique identification of your router, usually one of router's IPv4 addresses. Default: in IPv4 version, the lowest IP address of a non-loopback interface. In IPv6 version, this option is mandatory. @@ -253,7 +253,7 @@ protocol rip { to be added by this command. eval Evaluates given filter expression. It - is used by us for testing filters. + is used by us for testing of filters. Protocol options @@ -287,10 +287,10 @@ to zero to disable it. An empty is equivalent to import all | none | filter - Specify a filter to be used for filtering routes coming from protocol to the routing table. export This is similar to import keyword, except that it - works in direction from the routing table to the protocol. Default: export This is similar to the import keyword, except that it + works in the direction from the routing table to the protocol. Default: table Connect this protocol to a non-default routing table. @@ -300,14 +300,14 @@ to zero to disable it. An empty is equivalent to passwords { password " 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. is dd-mm-yyyy HH:MM:SS. 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 + interfaces is this protocol active on and allows you to set options on a + per-interface basis. Mask is specified as 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 option. If the first character of mask is is equivalent to Remote control

You can use the command-line client birdc to talk with -a running BIRD. Communication is done using Here is a brief list of supported functions: @@ -334,10 +334,10 @@ BIRD and BIRDC is stable (see programmer's documentation). Dump contents of internal data structures to the debugging output. show status - Show router status, that is bird version, uptime and time from last reconfiguration. + Show router status, that is BIRD version, uptime and time from last reconfiguration. show protocols [all] - Show list of protocols along with tables they are connected to and status, possibly giving verbose information. + Show list of protocol instances along with tables they are connected to and protocol status, possibly giving verbose information, if show ospf [interface|neighbors] [ Show detailed information about OSPF protocol, possibly giving a verbose list of interfaces and neighbors. The show interfaces [summary] - Show list of interfaces. For each interface, print its type, state, MTU and addresses assigned. + Show the list of interfaces. For each interface, print its type, state, MTU and addresses assigned. show symbols - Show list of symbols defined in the configuration (names of protocols, routing tables etc.). + Show the list of symbols defined in the configuration (names of protocols, routing tables etc.). show route [ Show contents of a routing table (by default of the main one), - i.e. routes, their metrics and (in case the You can specify a enable|disable|restart - Enable, disable or restart given protocol instance, instances matching the or or configure [" Reload configuration from a given file. @@ -391,15 +391,14 @@ BIRD and BIRDC is stable (see programmer's documentation). Introduction -

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 protocols and routing tables. Filter language contains control structures such -as if's and switches, but it allows no loops. Filters are -interpreted. An example of a filter using many features can be found in filter/test.conf. +

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

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 @@ -420,14 +419,14 @@ int var;

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 { statements }), that is useful if -you want to make bigger block of code conditional. +the type name; pairs where each pair defines one local variable. The body consists of + { statements }. Each { statements }) which is useful if +you want to make a 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 they can have local variables. Recursion is not allowed. They +

BIRD supports functions, so that you don't have to repeat the same blocks of code over and +over. Functions can have zero or more parameters and they can have local variables. Recursion is not allowed. Function definitions look like this: @@ -443,15 +442,15 @@ function with_parameters (int parameter) } -

Unlike in C, variables are declared after function line but before the first {. You can't declare +

Unlike in C, variables are declared after the name(); -with_parameters(5);. Function may return value using the return +with_parameters(5);. Function may return values using the return command. Returning a value exits from current function (this is similar to C).

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 +parameters. They get a route table entry as an implicit parameter, it is also passed automatically to any functions called. The filter must terminate with either -A nice trick to debug filters is to use show route filter @@ -466,7 +465,7 @@ bird> show route 195.113.30.2/32 dev tunl1 [direct1 23:21] (240) 127.0.0.0/8 dev lo [direct1 23:21] (240) bird> show route ? -show route [] [table ] [filter ] [all] [primary] [(import|protocol)

]... +show route [] [table ] [filter ] [all] [primary]... bird> show route filter { if 127.0.0.5 ~ net then accept; } 127.0.0.0/8 dev lo [direct1 23:21] (240) bird> @@ -479,7 +478,7 @@ 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 + on values of type ip. It masks out all but first num bits from the IP address. So ipaddress/pxlen, or - ipaddress/netmask There are two special - operators on prefix: - 1.2.0.0/16.pxlen = 16 is true. + ipaddress/netmask. There are two special + operators on prefixes: + 1.2.0.0/16.pxlen = 16 is true. . 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 address/num+ is shorthand for address/{0,, - address/ is shorthand for address/{0,. 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. + prefixes address/num+ is a shorthand for address/{0,, + address/ is a shorthand for address/{0,. 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. Operators - -

The filter language supports common integer operators (+,-,*,/), parentheses Control structures

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

Syntax of condition is if +

Syntax of a condition is: if boolean expression then command1; else command2; and you can use { -command_1; command_2; ... } instead of one or both commands. else -clause may be omitted. If boolean expression is true, command1 is executed, otherwise command2 is executed. +command_1; command_2; ... } instead of either command. The else +clause may be omitted. If the boolean expression is true, command1 is executed, otherwise command2 is executed. -

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 the ˜ operator, and anything that could -be a member of a set is allowed before matches one of matches neither of The case is similar to case from Pascal. Syntax is case . The expression after +case can be of any type which can be on the left side of the ˜ operator and anything that could +be a member of a set is allowed before matches one of the matches neither of the Here is example that uses Route attributes -

An filter is implicitly passed route, and it can access its -attributes just like it accesses variables. Attempt to access undefined +

A filter is implicitly passed a route, and it can access its +attributes just like it accesses variables. Attempts to access undefined attribute result in a runtime error; you can check if an attribute is -defined using the defined( attribute ) operator. +defined by using the defined( attribute ) operator. - Network the route is talking about. Read-only. (See the section about routing tables.) + Network the route is talking about. Read-only. (See the chapter about routing tables.) Address scope of the network ( - Preference of the route. (See section about routing tables.) + Preference of the route. (See the chapter about routing tables.) The router which the route has originated from. Read-only. @@ -614,9 +611,9 @@ defined using the defined( attribute ) operator. Type of destination the packets should be sent to ( -

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

There also exist some protocol-specific attributes which are described in the corresponding protocol sections. -Statements +Other statements

The following statements are available: @@ -625,14 +622,14 @@ defined using the defined( attribute ) operator. accept|reject [ Accept or reject the route, possibly printing expr. - return Return expr from function, the function ends at this point. + return Return expr from the current function, the function ends at this point. print|printn Prints given expressions; useful mainly while debugging filters. The quitbird - Terminates BIRD. Useful when debugging filter interpreter. + Terminates BIRD. Useful when debugging the filter interpreter. Protocols @@ -971,7 +968,7 @@ protocol kernel { # Secondary routing table

Open Shortest Path First (OSPF) is a quite complex interior gateway protocol. The current IPv4 version (OSPFv2) is defined in RFC 2328. It's a link -state (a.k.a. shortest path first) protocol -- Each router maintains a database +state (a.k.a. shortest path first) protocol -- each router maintains a database describing the autonomous system's topology. Each participating router has an identical copy of the database and all routers run the same algorithm calculating a shortest path tree with themselves as a root. @@ -981,19 +978,19 @@ OSPF chooses the least cost path as the best path. to reduce the amount of resources consumed for exchanging the routing information and to protect the other areas from incorrect routing data. Topology of the area is hidden to the rest of the autonomous system. -Unfortunately multiple OSPF areas are not yet fully supported +Unfortunately, multiple OSPF areas are not yet fully supported by this version of BIRD and neither is the IPv6 version (OSPFv3).

Another very important feature of OSPF is that it can keep routing information from other protocols (like Static or BGP) in its link state database as external routes. Each external route can -be tagged by the advertising router, making possible to pass additional +be tagged by the advertising router, making it possible to pass additional information between routers on the boundary of the autonomous system.

OSPF quickly detects topological changes in the autonomous system (such -as router interface failures) and calculates new loop-free routes after a -period of convergence. This period is short and involves only minimal -routing traffic. +as router interface failures) and calculates new loop-free routes after a short +period of convergence. Only a minimal ammount of +routing traffic is involved.

Each router participating in OSPF routing periodically sends Hello messages to all its interfaces. This allows neighbors to be discovered dynamically. @@ -1011,9 +1008,9 @@ on nonbroadcast networks. protocol ospf <name> { - rfc1583compat <bool>; + rfc1583compat <switch>; area <id> { - stub <bool>; + stub <switch>; tick <num>; interface <interface pattern> { @@ -1035,7 +1032,7 @@ protocol ospf <name> { - rfc1583compat bool + rfc1583compat switch This option controls compatibility of routing table calculation with RFC 1583. Default @@ -1047,7 +1044,7 @@ protocol ospf <name> { The most important area is the backbone (ID 0) to which every other area must be connected. - stub bool + stub switch No external routes are flooded into stub areas. Default value is no. tick num diff --git a/doc/sbase/dist/birddoc/latex2e/mapping b/doc/sbase/dist/birddoc/latex2e/mapping index 94940b60..747d0d33 100644 --- a/doc/sbase/dist/birddoc/latex2e/mapping +++ b/doc/sbase/dist/birddoc/latex2e/mapping @@ -1,7 +1,8 @@ % birddoc to LaTeX replacement file - + "\\documentclass\[a4paper,10pt,openany\]{book}\n" +% The \relax is there to avoid sgml2latex rewriting the class + + "\\relax\\documentclass\[a4paper,10pt,openany\]{book}\n" "\\usepackage{birddoc}\n" "\\usepackage{qwertz}\n" "\\usepackage{url}\n"