Jerry/bird
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merged mj's changes, up-to "import filter".

Browse source
This commit is contained in:
Pavel Machek 2000-06-06 11:53:22 +00:00
parent 41ad16e2d5
commit 02357f960e
1 changed files with 81 additions and 83 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

162
doc/bird.sgml
View file

@ -3,6 +3,10 @@
<!-- <!--
BIRD documentation BIRD documentation
This documentation can have 4 forms: sgml (this is master copy), html,
ASCII text and dvi/postscript (generated from sgml using
sgmltools). You should always edit master copy.
This is slightly modified linuxdoc dtd. Anything in <descrip> tags is considered definition of This is slightly modified linuxdoc dtd. Anything in <descrip> tags is considered definition of
configuration primitives, <cf> is fragment of configuration within normal text, <m> is configuration primitives, <cf> is fragment of configuration within normal text, <m> is
"meta" information within fragment of configuration - something in config which is not keyword. "meta" information within fragment of configuration - something in config which is not keyword.
@ -46,22 +50,20 @@ for `BIRD Internet Routing Daemon', you remember, don't you? :-)
which works as a dynamic router in an Internet type network (that is, in a network running either which works as a dynamic router in an Internet type network (that is, in a network running either
the IPv4 or the IPv6 protocol). Routers are devices which forward packets between interconnected the IPv4 or the IPv6 protocol). Routers are devices which forward packets between interconnected
networks in order to allow hosts not connected directly to the same local area network to networks in order to allow hosts not connected directly to the same local area network to
communicate with each other. They also communicate with other routers in the Internet to discover communicate with each other. They also communicate with the other routers in the Internet to discover
the topology of the network which allows them to find optimal (in terms of some metric) rules for the topology of the network which allows them to find optimal (in terms of some metric) rules for
forwarding of packets (which will be called routes in the rest of this document) and to adapt to the forwarding of packets (which will be called routes in the rest of this document) and to adapt themselves to the
changing conditions such as outages of network links, building of new connections and so on. Most of changing conditions such as outages of network links, building of new connections and so on. Most of
these routers are costly dedicated devices running obscure firmware which is hard to configure and these routers are costly dedicated devices running obscure firmware which is hard to configure and
not open to any changes (but these costly dedicated beasts are needed not open to any changes (on the other hand, their special hardware design allows them to keep up with lots of high-speed network interfaces, better than general-purpose computer does). Fortunately, most operating systems of the UNIX family allow an ordinary
for routing on many fast interfaces -- a PC class machine can not keep up with more than 4
100Mbps cards). Fortunately, most operating systems of the UNIX family allow an ordinary
computer to act as a router and forward packets belonging to the other hosts, but only according to computer to act as a router and forward packets belonging to the other hosts, but only according to
a statically configured table. a statically configured table.
<p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program running on <p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program running on
background which does the dynamic part of Internet routing, that is it communicates background which does the dynamic part of Internet routing, that is it communicates
with the other routers, calculates routing tables and sends them to the OS kernel with the other routers, calculates routing tables and sends them to the OS kernel
which does the actual packet forwarding. There are other such routing daemons: routed (rip only), GateD <HTMLURL URL="http://www.gated.org/"> which does the actual packet forwarding. There already exist other such routing daemons: routed (rip only), GateD<HTMLURL URL="http://www.gated.org/">
(non free) and Zebra <HTMLURL URL="http://www.zebra.org">, but their capabilities are limited and (non free), Zebra<HTMLURL URL="http://www.zebra.org"> and mrtd<HTMLURL URL="FIXME">, but their capabilities are limited and
they are relatively hard to configure and maintain. they are relatively hard to configure and maintain.
<p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings, <p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
@ -75,15 +77,15 @@ protocols to be incorporated easily. Among other features, BIRD supports:
<item>the Border Gateway Protocol (BGPv4) <item>the Border Gateway Protocol (BGPv4)
<item>the Routing Interchange Protocol (RIPv2) <item>the Routing Interchange Protocol (RIPv2)
<item>the Open Shortest Path First protocol (OSPFv2) <item>the Open Shortest Path First protocol (OSPFv2)
<item>a virtual protocol for exchange of routes between internal routing tables <item>a virtual protocol for exchange of routes between different routing tables on a single host
<item>a command-line interface allowing on-line control and inspection <item>a command-line interface allowing on-line control and inspection
of status of the daemon of status of the daemon
<item>soft reconfiguration (no need to use complex online commands <item>soft reconfiguration (no need to use complex online commands
to change the configuration, just edit the configuration file to change the configuration, just edit the configuration file
and notify BIRD to re-read it and it will smoothly switch and notify BIRD to re-read it and it will smoothly switch itself
to the new configuration, not disturbing routing protocols to the new configuration, not disturbing routing protocols
unless they are affected by the configuration changes) unless they are affected by the configuration changes)
<item>powerful language for route filtering <item>a powerful language for route filtering
</itemize> </itemize>
<p>BIRD has been developed at the Faculty of Math and Physics, Charles University, Prague, <p>BIRD has been developed at the Faculty of Math and Physics, Charles University, Prague,
@ -91,18 +93,13 @@ Czech Republic as a student project. It can be freely distributed under the term
Public License. Public License.
<p>BIRD has been designed to work on all UNIX-like systems. It has been developed and <p>BIRD has been designed to work on all UNIX-like systems. It has been developed and
tested under Linux 2.0 to 2.3, but porting to other systems (even non-UNIX ones) should 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. be relatively easy due to its highly modular architecture.
<sect>About this documentation
<p>This documentation can have 4 forms: sgml (this is master copy), html, ASCII text and dvi/postscript (generated from sgml using sgmltools). You should always edit master copy.
<sect>Installing BIRD <sect>Installing BIRD
<p>On recent UNIX (with GNU-compatible tools -- BIRD relies on GCC extensions) <p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make) and Perl, installing BIRD should be as easy as:
system, installing BIRD should be as easy as:
<code> <code>
./configure ./configure
@ -112,64 +109,66 @@ system, installing BIRD should be as easy as:
bird bird
</code> </code>
<p>You can use <tt>./configure --help</tt> to get list of configure <p>You can use <tt>./configure --help</tt> to get a list of configure
options. Most important (and not easily guessed) option is options. The most important ones are:
<tt/--enable-ipv6/, which enables IPv6 support. You can use <tt/--enable-ipv6/ which enables building of an IPv6 version of BIRD,
<tt/--with-protocols=/ to produce slightly smaller BIRD, and <tt/--with-protocols=/ to produce a slightly smaller BIRD executable by configuring out routing protocols you don't use, and
<tt/--prefix=/ to install bird somewhere else than <tt/--prefix=/ to install BIRD to a place different from.
<file>/usr/local</file>. <file>/usr/local</file>.
<sect>Running bird <sect>Running BIRD
<p>You can pass several command-line options to bird: <p>You can pass several command-line options to bird:
<descrip> <descrip>
<tag>-c <m/config name/</tag> <tag>-c <m/config name/</tag>
use given config file instead of <file>bird.conf</file>. use given configuration file instead of <file>$prefix/etc/bird.conf</file>.
<tag>-d</tag> <tag>-d</tag>
enable debugging. enable debug messages and run bird in foreground.
<tag>-D <m/filename for debug log/</tag> <tag>-D <m/filename of debug log/</tag>
log debugging information to given file. log debugging information to given file instead of stderr
<tag>-s <m/name of communication socket/</tag> <tag>-s <m/name of communication socket/</tag>
use given filename for socket for communications with bird client, default is <file/bird.ctl/. use given filename for a socket for communications with the client, default is <file>$prefix/var/run/bird.ctl</file>.
</descrip> </descrip>
<p>BIRD writes messages about its work to log files or syslog (according to config).
<chapt>About routing tables <chapt>About routing tables
<p>Bird has one or more routing tables, which may or may not be <p>BIRD has one or more routing tables, which may or may not be
synchronized with kernel and which may or may not be synchronized with synchronized with kernel and which may or may not be synchronized with
each other (see the Pipe protocol). Each routing table contains list of each other (see the Pipe protocol). Each routing table contains list of
known routes. Each route consists of: known routes. Each route consists of:
<itemize> <itemize>
<item>network this route is for <item>network prefix this route is for (consists of networkk address and number of bits forming the network part of the address)
<item>preference of this route (taken from preference of <item>preference of this route (taken from preference of
protocol and possibly altered by filters) protocol and possibly altered by filters)
<item>ip address of router who told us about this route <item>IP address of router who told us about this route
<item>ip address of router we should use for packets routing <item>IP address of router we should forward the packets to
using this route using this route
<item>other attributes common to all routes <item>other attributes common to all routes
<item>dynamic attributes defined by protocols, which may or <item>dynamic attributes defined by protocols which may or
may not be present (typically protocol metric) may not be present (typically protocol metrics)
</itemize> </itemize>
Routing table maintains more than Routing table maintains more than
one entry for network, but at most one entry for one network and one one entry for a network, but at most one entry for one network and one
protocol. The entry with biggest preference is used for routing. If protocol. The entry with biggest preference is used for routing. If
there are more entries with same preference and they are from same there are more entries with the same preference and they are from the same
protocol, protocol decides (typically according to metrics). If not, protocol, protocol decides (typically according to metrics). If not,
internal ordering is used to decide. You can internal ordering is used to decide. You can
get list of route attributes in "Route attributes" section in get list of route attributes in "Route attributes" section in
filters. filters.
<p>Protocols are connected to routing tables using filters. Routes <p>Protocols are connected to routing tables through filters. Routes
that come from network go to the protocol, it then passes them to that come from other routers go to the protocol, it then passes them to
filters, if import filter accepts route, it gets to main routing filters, if import filter accepts route, it gets to main routing
table. It is then broadcasted to all other protocols (filtered through table. It is then broadcasted to all other protocols (filtered through
their export filters), which typically send it to the network. their export filters), which typically send it to other routers.
Filters can alter routes passed between routing tables and Filters can alter routes passed between routing tables and
protocols. protocols.
@ -178,22 +177,22 @@ protocols.
<sect>Introduction <sect>Introduction
<p>BIRD is configured using text configuration file. At startup, BIRD reads <file/bird.conf/ (unless <!-- fixme: add default values to all places? Where do I learn them? -->
<tt/-c/ command line option is given). Configuration may be changed on user request: if you modify
config file and then signal BIRD with SIGHUP, it will adjust to new
config. Then there's BIRD client,
which allows you to talk with BIRD in extensive way. (Of course you can tell BIRD to reconfigure from BIRDC, you can also tell it to shut down, dump various info etc.). BIRD
writes messages about its work to log files or syslog (according to config).
<p>In config, everything on a line after <cf/#/ or inside <cf>/* <p>BIRD is configured using a text configuration file. Upon startup, BIRD reads <file>$prefix/bird.conf</file> (unless the
*/</cf> is a comment, whitespace is ignored, C-style comments <cf>/* comment */</cf> are also <tt/-c/ command line option is given). Configuration may be changed on user's request: if you modify
recognized. If there's variable number of options, they are grouped using config file and then signal BIRD with SIGHUP, it will adjust to the new
<cf/{ }/ brackets. Each option is terminated by <cf/;/. Configuration config. Then there's the client,
which allows you to talk with BIRD in an extensive way. (Of course you can tell BIRD to reconfigure from BIRDC, you can also tell it to shut down, dump various info etc.).
<p>In the config, everything on a line after <cf/#/ or inside <cf>/*
*/</cf> is a comment, whitespace characters are treated as a single space. If there's a variable number of options, they are grouped using
the <cf/{ }/ brackets. Each option is terminated by a <cf/;/. Configuration
is case sensitive. is case sensitive.
<p>Really simple configuration file might look like this: It enables <p>Here is an example of a simple config file. It enables
synchronization of routing tables with kernel, scans for synchronization of routing tables with OS kernel, scans for
new network interfaces every 10 seconds and runs RIP on all interfaces found. new network interfaces every 10 seconds and runs RIP on all network interfaces found.
<code> <code>
@ -218,58 +217,57 @@ protocol rip {
<p><descrip> <p><descrip>
<tag>log "<m/filename/"|syslog|stderr all|{ <m/list of classes/ }</tag> <tag>log "<m/filename/"|syslog|stderr all|{ <m/list of classes/ }</tag>
set logging of classes (either all or <cf/{ Set logging of messages having the given (either <cf/all/ or <cf/{
error, trace }/ etc.) into selected destination. Classes are: error, trace }/ etc.) into selected destination. Classes are:
<cf/info/, <cf/warning/, <cf/error/, <cf/fatal/ for messages about local problems <cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems
<cf/debug/ for debugging messages, <cf/debug/ for debugging messages,
<cf/trace/ when you want to know what happens on network, <cf/trace/ when you want to know what happens in the network,
<cf/remote/ for messages about misbehavior of remote side, <cf/remote/ for messages about misbehavior of remote machines,
<cf/auth/ about authentication failures, <cf/auth/ about authentication failures,
<cf/bug/ for internal bugs <cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to estabilish logging to multiple
of BIRD. You may specify more than one <cf/log/ line to log to multiple
destinations. destinations.
<!--fixme: mj says explain-->
<tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag> <tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
sets global default of protocol debugging options. Set global default of protocol debugging options.
<tag>filter <m/name local variables/{ <m/commands/ }</tag> define filter. You can learn more about filters <tag>filter <m/name local variables/{ <m/commands/ }</tag> Define a filter. You can learn more about filters
in next chapter. in the following chapter.
<tag>function <m/name (parameters) local variables/ { <m/commands/ }</tag> define function. You can learn more <tag>function <m/name (parameters) local variables/ { <m/commands/ }</tag> Define a function. You can learn more
about functions about functions in the following chapter.
in next chapter.
<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> define protocol <tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
instance, called name (or called something like rip5 if you omit name). You can learn more instance called <cf><m/name/</cf> (or with a name like "rip5" generated automatically, if you don't specify <cf><m/name/</cf>). You can learn more
about configuring protocols in their own chapters. You can run more than one instance of about configuring protocols in their own chapters. You can run more than one instance of
most protocols (like rip or bgp). most protocols (like RIP or BGP).
<tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/ip address/</tag> define constant. You can use it later in every place <tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/IP address/</tag> Define a constant. You can use it later in every place
you could use simple integer/ip address. you could use a simple integer or IP address.
<tag>router id <m/IPv4 address/</tag> set router id. Router id needs to be world-wide <tag>router id <m/IPv4 address/</tag> Set BIRD's router ID. It's a world-wide unique identification of your router, usually one of router's IPv4 addresses.
unique. It is usually one of router's IPv4 addresses.
<tag>table <m/name/</tag> create new routing table. Default <tag>table <m/name/</tag> Create a new routing table. The default
routing table is created implicitly, other routing tables have routing table is created implicitly, other routing tables have
to be added by this command. to be added by this command.
<tag>eval <m/expr/</tag> evaluates given filter expression. It <tag>eval <m/expr/</tag> Evaluates given filter expression. It
is used by us for testing. is used by us for testing filters.
</descrip> </descrip>
<sect>Protocol options <sect>Protocol options
<p>Several options are per-protocol, but all protocols support them. They are described here. <p>Each routing protocol has its own set of options (see the corresponding sections). These options are common to all protocols:
<descrip> <descrip>
<tag>preference <m/expr/</tag> sets preference of routes generated by this protocol. <tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol.
<tag>disabled</tag> disables given protocol. You can disable/enable protocol from command <tag>disabled</tag> Disables the protocol. You can change the disable/enable status from the command
line interface without needing to touch config. Disabled protocol is not activated. line interface without needing to touch the configuration. Disabled protocol is not activated.
<tag>debug <m/setting/</tag> this is similar to global debug setting, except that it only <tag>debug <m/setting/</tag> Similar to global <cf/debug/ setting, except that it only
affects one protocol. Only messages in selected debugging categories will be written to affects one protocol. Only messages in selected debugging categories will be written to the
logs. logs.
<tag>import <m/filter/</tag> filter can be either either <cf> { <m>filter commands</m> <tag>import <m/filter/</tag> filter can be either either <cf> { <m>filter commands</m>
@ -355,7 +353,7 @@ pairs <cf><M>type name</M>;</cf>, where each pair defines one local variable. Bo
several statements into one by <cf>{ <M>statements</M> }</cf> construction, that is useful if several statements into one by <cf>{ <M>statements</M> }</cf> construction, that is useful if
you want to make bigger block of code conditional. you want to make bigger block of code conditional.
<p>Bird supports functions, so that you don't have to repeat same blocks of code over and <p>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 can have local variables. They
look like this: look like this:
@ -1160,5 +1158,5 @@ LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth
LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek
LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's
LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole
LocalWords: uninstalls ethernets LocalWords: uninstalls ethernets IP
--> -->