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

Docs updates.

Browse source
This commit is contained in:
Pavel Machek 2000-06-08 10:24:42 +00:00
parent b178d92a0b
commit 5a203dac61
1 changed files with 194 additions and 115 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

299
doc/bird.sgml
View file

@ -176,8 +176,6 @@ protocols.
<sect>Introduction <sect>Introduction
<!-- fixme: add default values to all places? Where do I learn them? -->
<p>BIRD is configured using a text configuration file. Upon startup, BIRD reads <file>$prefix/bird.conf</file> (unless the <p>BIRD is configured using a text configuration file. Upon startup, BIRD reads <file>$prefix/bird.conf</file> (unless the
<tt/-c/ command line option is given). Configuration may be changed on user's request: if you modify <tt/-c/ command line option is given). Configuration may be changed on user's request: if you modify
config file and then signal BIRD with SIGHUP, it will adjust to the new config file and then signal BIRD with SIGHUP, it will adjust to the new
@ -224,12 +222,15 @@ protocol rip {
<cf/remote/ for messages about misbehavior of remote machines, <cf/remote/ for messages about misbehavior of remote machines,
<cf/auth/ about authentication failures, <cf/auth/ about authentication failures,
<cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to establish logging to multiple <cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to establish logging to multiple
destinations. destinations. Default: log everything to the system log.
<!--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>
Set global default of protocol debugging options. Set global defaults of protocol debugging options. See <cf/debug/ in the following section. Default: off.
<tag>debug commands <m/number/</tag>
Control logging of client connections (0 for no logging, 1 for
logging of connects and disconnects, 2 and higher for logging of
all client commands). Default: 0.
<tag>filter <m/name local variables/{ <m/commands/ }</tag> Define a 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 the following chapter. in the following chapter.
@ -240,12 +241,12 @@ protocol rip {
<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol <tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
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 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). By default, no instances are configured.
<tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/IP address/</tag> Define a 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 a simple integer or IP address. you could use a simple integer or IP address.
<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. <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. Default: in IPv4 version, the lowest IP address of a non-loopback interface. In IPv6 version, this option is mandatory.
<tag>table <m/name/</tag> Create a new routing table. The 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
@ -257,22 +258,39 @@ protocol rip {
<sect>Protocol options <sect>Protocol options
<p>Each routing protocol has its own set of options (see the corresponding sections). These options are common to all protocols: <p>For each protocol instance, you can configure a bunch of options.
Some of them (those described in this section) are generic, some are
specific to the protocol (see sections talking about the protocols).
<p>Several options use a <cf><m/switch/</cf> argument. It can be either
<cf/on/, <cf/yes/ or a numeric expression with a non-zero value for the
option to be enabled or <cf/off/, <cf/no/ or a numeric expression evaluating
to zero to disable it. An empty <cf><m/switch/</cf> is equivalent to <cf/on/
("silence means agreement").
<descrip> <descrip>
<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. <tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
<tag>disabled</tag> Disables the protocol. You can change the disable/enable status from the command <tag>disabled <m/switch/</tag> Disables the protocol. You can change the disable/enable status from the command
line interface without needing to touch the configuration. Disabled protocol is not activated. line interface without needing to touch the configuration. Disabled protocols are not activated. Default: protocol is enabled.
<tag>debug <m/setting/</tag> Similar to global <cf/debug/ setting, except that it only <tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
affects one protocol. Only messages in selected debugging categories will be written to the Set protocol debugging options. If asked, each protocol is capable of
logs. writing trace messages about its work to the log (with category
<cf/trace/). You can either request printing of <cf/all/ trace messages
or only of the types selected: <cf/states/ for protocol state changes
(protocol going up, down, starting, stopping etc.),
<cf/routes/ for routes exchanged with the routing table,
<cf/filters/ for details on route filtering,
<cf/interfaces/ for interface change events sent to the protocol,
<cf/events/ for events internal to the protocol and
<cf/packets/ for packets sent and received by the protocol. Default: off.
<tag>import { <m/filter commands/ } | <m/name/ | all | none</tag> Specify a filter to be used for filtering routes coming from protocol to the routing table. Default: <cf/all/. <cf/all/ is shorthand for <cf/{ accept; }/ and <cf/none/ is shorthand for <cf/{ reject; }/. <tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag>
Specify a filter to be used for filtering routes coming from protocol to the routing table. <cf/all/ is shorthand for <cf/where true/ and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/.
<tag>export <m/filter/</tag> This is similar to <cf>import</cf> keyword, except that it <tag>export <m/filter/</tag> This is similar to <cf>import</cf> keyword, except that it
works in direction from the routing table to the protocol. Default: <cf/none/ works in direction from the routing table to the protocol. Default: <cf/none/.
<tag>table <m/name/</tag> Connect this protocol to a non-default routing table. <tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
</descrip> </descrip>
@ -283,7 +301,7 @@ protocol rip {
<tag>passwords { password "<m/password/" from <m/time/ to <m/time/ passive <m/time/ id <tag>passwords { password "<m/password/" from <m/time/ to <m/time/ passive <m/time/ id
<m/num/ [...] }</tag> Specifies passwords to be used with this protocol. <cf>Passive <m/time/</cf> is <m/num/ [...] }</tag> Specifies passwords to be used with this protocol. <cf>Passive <m/time/</cf> is
time from which the password is not used for sending, but it is recognized on reception. <cf/id/ is password ID, as needed by time from which the password is not used for sending, but it is recognized on reception. <cf/id/ is password ID, as needed by
certain protocols. Format of <cf><m/time/</cf> is <tt>dd-mm-yy HH:MM:SS</tt>. certain protocols. Format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
<tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [ ... ] } ]</tag> Specifies which <tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [ ... ] } ]</tag> Specifies which
interfaces this protocol is active on, and allows you to set options on interfaces this protocol is active on, and allows you to set options on
@ -291,14 +309,14 @@ protocol rip {
"*" { mode broadcast; };</cf> will start the protocol on all interfaces with <cf>mode "*" { mode broadcast; };</cf> will start the protocol on all interfaces with <cf>mode
broadcast;</cf> option. If first character of mask is <cf/-/, such interfaces are broadcast;</cf> option. If first character of mask is <cf/-/, such interfaces are
excluded. Masks are parsed left-to-right, thus <cf/interface "-eth*", "*";/ means all but excluded. Masks are parsed left-to-right, thus <cf/interface "-eth*", "*";/ means all but
the ethernets. the ethernets. Default: none.
</descrip> </descrip>
<sect>Client <chapt>Remote control
<p>You can use the command-line client <file>birdc</file> to talk with <p>You can use the command-line client <file>birdc</file> to talk with
a running BIRD. Communication is done using <file/bird.ctl/ unix domain a running BIRD. Communication is done using <file/bird.ctl/ UNIX domain
socket (unless changed with the <tt/-s/ option given to both the server and socket (unless changed with the <tt/-s/ option given to both the server and
the client). The client can do simple actions such as enabling/disabling the client). The client can do simple actions such as enabling/disabling
protocols, telling BIRD to show various information, telling it to protocols, telling BIRD to show various information, telling it to
@ -309,20 +327,61 @@ codes. You do not necessarily need to use BIRDC to talk to BIRD, your
own application could do that, too -- format of communication between own application could do that, too -- format of communication between
BIRD and BIRDC is stable (see programmer's documentation). BIRD and BIRDC is stable (see programmer's documentation).
<p>Here is very brief list of supported functions: <p>Here is a brief list of supported functions:
<descrip> <descrip>
<tag>dump resources|sockets|interfaces|neighbors|attributs|routes|protocols</tag> <tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
Send requested information to a standard logging facility. Dump contents of internal data structures to the debugging output.
<tag>show status|protocols [all]|interfaces [summary]|symbols</tag> <tag>show status</tag>
Show requested information on client. Show router status, that is bird version, uptime and time from last reconfiguration.
<tag>show route [<m/prefix/|for <m/prefix or IP/] [table <m/name/] [table <m/sym/] [all] [stats] [count] [primary] [filter <m/name/] [import_or_proto <m/sym/]</tag> <tag>show protocols [all]</tag>
Show contents of the routing table, possibly filtered by the filter. If you put <cf><m/prefix/</cf> on the line, only routes to given destination are shown. You can also make list more verbose by using <cf/all/ or limit routes to be shown to those from given protocol (using <cf/import_or_proto/). Show list of protocols along with tables they are connected to and status, possibly giving verbose information.
<tag>enable|disable|restart <m/name/|all</tag> <tag>show ospf [interface|neighbors] [<m/name/] ["<m/interface/"]</tag>
Enable/disable or restart given protocol. Show detailed information about OSPF protocol, possibly giving a verbose list of interfaces and neighbors. The <m/name/ of the protocol instance can be omitted if there exists only a single instance.
<tag>show static [<m/name/]</tag>
Show detailed information about static routes. The <m/name/ of the protocol instance can be omitted if there exists only a single instance.
<tag>show interfaces [summary]</tag>
Show list of interfaces. For each interface, print its type, state, MTU and addresses assigned.
<tag>show symbols</tag>
Show list of symbols defined in the configuration (names of protocols, routing tables etc.).
<tag>show route [<m/prefix/|for <m/prefix or IP/] [primary] [table <m/sym/] [all] [stats|count] [filter <m/name/|where <m/condition/] [(import|proto) <m/sym/]</tag>
Show contents of a routing table (by default of the main one),
i.e. routes, their metrics and (in case the <cf/all/ switch is given)
all their attributes.
<p>You can specify a <m/prefix/ if you want to print routes for a
specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get
the entry which will be used for forwarding of packets to the given
destination. By default, all routes for each network are printed with
the selected one at the top, unless <cf/primary/ is given in which case
only the selected route is shown.
<p>You can also ask for printing only routes processed and accepted by
a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
</cf> or matching a given condition (<cf>where <m/condition/</cf>).
The <cf/import/ and <cf/proto/ switches ask for printing of entries as
they would be seen by the specified protocol. With <cf/import/, the
export filter of the protocol is skipped.
<p>The <cf/stats/ switch requests showing of route statistics (the
number of networks, number of routes before and after filtering). If
you use <cf/count/ instead, only the statistics will be printed.
<tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
Enable, disable or restart given protocol instance, instances matching the <cf><m/pattern/</cf> or <cf/all/ instances.
<tag>configure ["<m/config file/"]</tag>
Reload configuration from a given file.
<tag/down/
Shut BIRD down.
<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets } <tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }
Control protocol debugging. Control protocol debugging.
@ -435,10 +494,9 @@ incompatible with each other (that is to prevent you from shooting in the foot).
are written as <cf/"This is a string constant"/. are written as <cf/"This is a string constant"/.
<tag/ip/ This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it <tag/ip/ This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it
is either an IPv4 or IPv6 address. IPv4 addresses are written (as you would expect) as is either an IPv4 or IPv6 address. IP addresses are written in the standard notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator <cf>.mask(<M>num</M>)</cf>
<cf/1.2.3.4/. You can apply special operator <cf>.mask(<M>num</M>)</cf>
on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from ip on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from ip
address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true. <!-- FIXME: IPv6? --> address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as <tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
<cf><M>ipaddress</M>/<M>pxlen</M></cf>, or <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
@ -467,15 +525,14 @@ incompatible with each other (that is to prevent you from shooting in the foot).
BGP path is a list of autonomous system numbers. You can't write literals of this type. BGP path is a list of autonomous system numbers. You can't write literals of this type.
<tag/bgpmask/ <tag/bgpmask/
BGP mask is a mask used for matching BGP paths BGP masks are patterns used for BGP path matching
(using <cf>path &tilde; /2 3 5 ?/</cf> syntax). Matching is (using <cf>path &tilde; /2 3 5 ?/</cf> syntax). The masks
done using shell-like patterns: <cf/?/ means resemble wildcard patterns as used by UNIX shells. Autonomous
"any number of any autonomous systems". Pattern for single system numbers match themselves, <cf/?/ matches any (even empty)
unknown autonomous system is not supported. (We sequence of arbitrary AS numbers (<cf/*/ hasn't been chosen, because
did not want to use * because then it becomes too easy to <cf>/*</cf> starts a comment). For example:
write <cf>/*</cf> which is start of comment.) For example,
<tt>/4 3 2 1/ ~ /? 4 3 ?/</tt> is true, but <tt>/4 3 2 1/ ~ /? 4 3 ?/</tt> is true, but
<tt>/4 3 2 1/ ~ /? 4 5 ?/</tt> is false. <!-- fixme: formulate better --> <tt>/4 3 2 1/ ~ /? 4 5 ?/</tt> is false.
<tag/clist/ <tag/clist/
Community list is similar to set of pairs, Community list is similar to set of pairs,
except that unlike other sets, it can be modified. except that unlike other sets, it can be modified.
@ -536,7 +593,7 @@ defined using the <cf>defined( <m>attribute</m> )</cf> 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 section about routing tables.)
<tag><m/enum/ scope</tag> <tag><m/enum/ scope</tag>
Address scope of the network (<cf/SCOPE_HOST/ for addresses local to this host, <cf/SCOPE_LINK/ for those specific for a physical link, <cf/SCOPE_SITE/, <cf/SCOPE_ORGANIZATION/, <cf/SCOPE_UNIVERSE/) Address scope of the network (<cf/SCOPE_HOST/ for addresses local to this host, <cf/SCOPE_LINK/ for those specific for a physical link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private addresses, <cf/SCOPE_UNIVERSE/ for globally visible addresses).
<tag><m/int/ preference</tag> <tag><m/int/ preference</tag>
Preference of the route. (See section about routing tables.) Preference of the route. (See section about routing tables.)
@ -551,10 +608,10 @@ defined using the <cf>defined( <m>attribute</m> )</cf> operator.
what protocol has told me about this route. Possible values: <cf/RTS_DUMMY, RTS_STATIC, RTS_INHERIT, RTS_DEVICE, RTS_STATIC_DEVICE, RTS_REDIRECT, RTS_RIP, RTS_OSPF, RTS_OSPF_EXT, RTS_OSPF_IA, RTS_OSPF_BOUNDARY, RTS_BGP, RTS_PIPE/. what protocol has told me about this route. Possible values: <cf/RTS_DUMMY, RTS_STATIC, RTS_INHERIT, RTS_DEVICE, RTS_STATIC_DEVICE, RTS_REDIRECT, RTS_RIP, RTS_OSPF, RTS_OSPF_EXT, RTS_OSPF_IA, RTS_OSPF_BOUNDARY, RTS_BGP, RTS_PIPE/.
<tag><m/enum/ cast</tag> <tag><m/enum/ cast</tag>
Route type (<cf/RTC_UNICAST/ for normal routes, <cf/RTC_BROADCAST, RTC_MULTICAST, RTC_ANYCAST/ for broadcast, multicast and anycast routes.) Read-only. Route type (<cf/RTC_UNICAST/ for normal routes, <cf/RTC_BROADCAST, RTC_MULTICAST, RTC_ANYCAST/ for broadcast, multicast and anycast routes). Read-only.
<tag><m/enum/ dest</tag> <tag><m/enum/ dest</tag>
Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, <cf/RTD_NETWORK/ for routing to directly-connected network, <cf/RTD_BLACKHOLE/ for packets to be silently discarded, <cf/RTD_UNREACHABLE, RTD_PROHIBIT/ for packets that should be discarded with ICMP host unreachable / ICMP administratively prohibited messages.) Read-only. Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, <cf/RTD_NETWORK/ for routing to a directly-connected network, <cf/RTD_BLACKHOLE/ for packets to be silently discarded, <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be returned with ICMP host unreachable / ICMP administratively prohibited messages). Read-only.
</descrip> </descrip>
<p>There also exist some protocol-specific attributes, which are described in protocol sections. <p>There also exist some protocol-specific attributes, which are described in protocol sections.
@ -583,22 +640,22 @@ defined using the <cf>defined( <m>attribute</m> )</cf> operator.
<sect>BGP <sect>BGP
<p>The Border Gateway Protocol is the routing protocol used for backbone <p>The Border Gateway Protocol is the routing protocol used for backbone
level routing in the today's Internet. Contrary to other protocols, its convergence level routing in the today's Internet. Contrary to the other protocols, its convergence
doesn't rely on all routers following the same rules for route selection, doesn't rely on all routers following the same rules for route selection,
making it possible to implement any routing policy at any router in the making it possible to implement any routing policy at any router in the
network, the only restriction being that if a router advertises a route, network, the only restriction being that if a router advertises a route,
it must accept and forward packets according to it. it must accept and forward packets according to it.
<p>BGP works in terms of autonomous systems (often abbreviated as AS). Each <p>BGP works in terms of autonomous systems (often abbreviated as AS). Each
AS is a part of the network with common management and common routing policy. AS is a part of the network with common management and common routing policy. It is identified by a unique 16-bit number.
Routers within each AS usually communicate using either a interior routing Routers within each AS usually communicate with each other using either a interior routing
protocol (such as OSPF or RIP) or an interior variant of BGP (called iBGP). protocol (such as OSPF or RIP) or an interior variant of BGP (called iBGP).
Boundary routers at the border of the AS communicate with their peers Boundary routers at the border of the AS communicate with their peers
in the neighboring AS'es via exterior BGP (eBGP). in the neighboring AS'es via exterior BGP (eBGP).
<p>Each BGP router sends to its neighbors updates of the parts of its <p>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 (a list of AS'es the packet will travel through if it uses the particular
route) in order to avoid routing loops. route) in order to avoid routing loops.
<p>BIRD supports all requirements of the BGP4 standard as defined in <p>BIRD supports all requirements of the BGP4 standard as defined in
@ -608,7 +665,7 @@ latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-id
It also supports the community attributes as per It also supports the community attributes as per
RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">, RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">,
capability negotiation defined in capability negotiation defined in
RFC 2842<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2842.txt">, RFC 2842<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2842.txt">.
For IPv6, it uses the standard multiprotocol extensions defined in For IPv6, it uses the standard multiprotocol extensions defined in
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt"> RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
including changes described in the including changes described in the
@ -620,25 +677,25 @@ RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
<p>BGP doesn't have any simple metric, so the rules for selection of an optimal <p>BGP doesn't have any simple metric, so the rules for selection of an optimal
route among multiple BGP routes with the same preference are a bit more complex route among multiple BGP routes with the same preference are a bit more complex
and are implemented according to the following algorithm. First it uses the first and they are implemented according to the following algorithm. It starts the first
rule, if there are more "best" routes, then it uses the second rule to choose rule, if there are more "best" routes, then it uses the second rule to choose
among them and so on. among them and so on.
<itemize> <itemize>
<item>Prefer route with the highest local preference attribute. <item>Prefer route with the highest Local Preference attribute.
<item>Prefer route with the shortest AS path. <item>Prefer route with the shortest AS path.
<item>Prefer IGP origin over EGP and EGP over incomplete. <item>Prefer IGP origin over EGP and EGP over incomplete.
<item>Prefer the lowest value of the Multiple Exit Discriminator. <item>Prefer the lowest value of the Multiple Exit Discriminator.
<item>Prefer internal routes over external routes. <item>Prefer internal routes over external ones.
<item>Prefer route with the lowest value of router ID of the <item>Prefer the route with the lowest value of router ID of the
advertising router. advertising router.
</itemize> </itemize>
<sect1>Configuration <sect1>Configuration
<p>Each instance of the BGP corresponds to one neighboring router. <p>Each instance of the BGP corresponds to one neighboring router.
This allows to set routing policy and all other parameters differently This allows to set routing policy and all the other parameters differently
for each neighbor using the following protocol parameters: for each neighbor using the following configuration parameters:
<descrip> <descrip>
<tag>local as <m/number/</tag> Define which AS we are part of. (Note that <tag>local as <m/number/</tag> Define which AS we are part of. (Note that
@ -646,51 +703,66 @@ for each neighbor using the following protocol parameters:
in multiple AS'es simultaneously, but in such cases you need to tweak in multiple AS'es simultaneously, but in such cases you need to tweak
the BGP paths manually in the filters to get consistent behavior.) the BGP paths manually in the filters to get consistent behavior.)
This parameter is mandatory. This parameter is mandatory.
<tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router <tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router
this instance will be talking to and what AS it's located in. Unless this instance will be talking to and what AS it's located in. Unless
you use the <cf/multihop/ clause, it must be directly connected to one you use the <cf/multihop/ clause, it must be directly connected to one
of your router's interfaces. In case the neighbor is in the same AS of your router's interfaces. In case the neighbor is in the same AS
as we are, we automatically switch to iBGP. This parameter is mandatory. as we are, we automatically switch to iBGP. This parameter is mandatory.
<tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a <tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a
neighbor which is connected at most <m/number/ hops far and to which neighbor which is connected at most <m/number/ hops far and to which
we should route via our direct neighbor with address <m/ip/. we should route via our direct neighbor with address <m/ip/.
Default: switched off. Default: switched off.
<tag>next hop self</tag> Avoid calculation of the Next Hop attribute <tag>next hop self</tag> Avoid calculation of the Next Hop attribute
and always advertise our own source address (see below) as a next hop. and always advertise our own source address (see below) as a next hop.
This needs to be used only This needs to be used only
occasionally to circumvent misconfigurations of other routers. occasionally to circumvent misconfigurations of other routers.
Default: disabled. Default: disabled.
<tag>source address <m/ip/</tag> Define local address we should use <tag>source address <m/ip/</tag> Define local address we should use
for next hop calculation. Default: the address of the local end for next hop calculation. Default: the address of the local end
of the interface our neighbor is connected to. of the interface our neighbor is connected to.
<tag>disable after error <m/switch/</tag> When an error is encountered (either <tag>disable after error <m/switch/</tag> When an error is encountered (either
locally or by the other side), disable the instance automatically locally or by the other side), disable the instance automatically
and wait for an administrator to solve the problem manually. Default: off. and wait for an administrator to fix the problem manually. Default: off.
<tag>hold time <m/number/</tag> Time in seconds to wait for a keepalive
<tag>hold time <m/number/</tag> Time in seconds to wait for a Keepalive
message from the other side before considering the connection stale. message from the other side before considering the connection stale.
Default: depends on agreement with the neighboring router, we prefer Default: depends on agreement with the neighboring router, we prefer
240 seconds if the other side is willing to accept it. 240 seconds if the other side is willing to accept it.
<tag>startup hold time <m/number/</tag> Value of the hold timer used <tag>startup hold time <m/number/</tag> Value of the hold timer used
before the routers have a chance to exchange OPEN messages and agree before the routers have a chance to exchange open messages and agree
on the real value. Default: 240 seconds. on the real value. Default: 240 seconds.
<tag>keepalive time <m/number/</tag> Delay in seconds between sending <tag>keepalive time <m/number/</tag> Delay in seconds between sending
of two consecutive keepalive messages. Default: One third of the hold time. of two consecutive Keepalive messages. Default: One third of the hold time.
<tag>connect retry time <m/number/</tag> Time in seconds to wait before <tag>connect retry time <m/number/</tag> Time in seconds to wait before
retrying a failed connect attempt. Default: 120 seconds. retrying a failed attempt to connect. Default: 120 seconds.
<tag>start delay time <m/number/</tag> Delay in seconds between protocol <tag>start delay time <m/number/</tag> Delay in seconds between protocol
startup and first attempt to connect. Default: 5 seconds. startup and the first attempt to connect. Default: 5 seconds.
<tag>error wait time <m/number/, <m/number/</tag> Minimum and maximum delay in seconds between protocol
failure (either local or reported by the peer) and automatic startup. <tag>error wait time <m/number/,<m/number/</tag> Minimum and maximum delay in seconds between a protocol
failure (either local or reported by the peer) and automatic restart.
Doesn't apply when <cf/disable after error/ is configured. If consecutive Doesn't apply when <cf/disable after error/ is configured. If consecutive
errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300. errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300.
<tag>error forget time <m/number/</tag> Maximum time in seconds between two protocol <tag>error forget time <m/number/</tag> Maximum time in seconds between two protocol
failures to treat them as a error sequence which makes the <cf/error wait time/ failures to treat them as a error sequence which makes the <cf/error wait time/
increase exponentially. Default: 300 seconds. increase exponentially. Default: 300 seconds.
<tag>path metric <m/switch/</tag> Enable comparison of path lengths <tag>path metric <m/switch/</tag> Enable comparison of path lengths
when deciding which BGP route is the best one. Default: on. when deciding which BGP route is the best one. Default: on.
<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit <tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
Discriminator to be used during route selection when the MED attribute Discriminator to be used during route selection when the MED attribute
is missing. Default: infinite. is missing. Default: infinite.
<tag>default bgp_local_pref <m/number/</tag> Value of the Local Preference <tag>default bgp_local_pref <m/number/</tag> Value of the Local Preference
to be used during route selection when the Local Preference attribute to be used during route selection when the Local Preference attribute
is missing. Default: 0. is missing. Default: 0.
@ -698,47 +770,53 @@ for each neighbor using the following protocol parameters:
<sect1>Attributes <sect1>Attributes
<p>BGP defines several route attributes. Some of them (those marked with `I' in the <p>BGP defines several route attributes. Some of them (those marked with `<tt/I/' in the
table below) are available on internal BGP connections only, some of them (marked table below) are available on internal BGP connections only, some of them (marked
with `O') are optional. with `<tt/O/') are optional.
<descrip> <descrip>
<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path <tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
the packet will travel through when forwarded according to this route. On the packet will travel through when forwarded according to the particular route. In case of
internal BGP connections it doesn't contain the number of the local AS. internal BGP it doesn't contain the number of the local AS.
<tag>int <cf/bgp_local_pref/ [I]</tag> Local preference value used for <tag>int <cf/bgp_local_pref/ [I]</tag> Local preference value used for
selection among multiple BGP routes (see the selection rules above). It's selection among multiple BGP routes (see the selection rules above). It's
used as an additional metric which is propagated through the whole local AS. used as an additional metric which is propagated through the whole local AS.
<tag>int <cf/bgp_med/ [IO]</tag> The Multiple Exit Discriminator of the route <tag>int <cf/bgp_med/ [IO]</tag> The Multiple Exit Discriminator of the route
is an optional attribute which is often used within the local AS to is an optional attribute which is often used within the local AS to
reflect interior distances to various boundary routers. See the route selection reflect interior distances to various boundary routers. See the route selection
rules above for exact semantics. rules above for exact semantics.
<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/,
if the route has originated in interior routing protocol of an AS or <tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
<cf/ORIGIN_EGP/, if it's been imported from the <tt>EGP</tt> protocol if the route has originated in an interior routing protocol or
(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/, if the origin <cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
is unknown. is unknown.
<tag>ip <cf/bgp_next_hop/</tag> Next hop to be used for forwarding of packets <tag>ip <cf/bgp_next_hop/</tag> Next hop to be used for forwarding of packets
to this destination. On internal BGP connections, it's an address of the to this destination. On internal BGP connections, it's an address of the
originating router if it's inside the local AS or a boundary router the originating router if it's inside the local AS or a boundary router the
packet will leave the AS through if it's an exterior route, so each BGP packet will leave the AS through if it's an exterior route, so each BGP
speaker within the AS has a chance to use the shortest interior path speaker within the AS has a chance to use the shortest interior path
possible to this point. possible to this point.
<tag>void <cf/bgp_atomic_aggr/ [O]</tag> This is an optional attribute <tag>void <cf/bgp_atomic_aggr/ [O]</tag> This is an optional attribute
which carries no value, but which sole presence indicates that the route which carries no value, but the sole presence of which indicates that the route
has been aggregated from multiple routes by some AS on the path from has been aggregated from multiple routes by some router on the path from
the originator. the originator.
<!-- we don't handle aggregators right since they are of a very obscure type <!-- we don't handle aggregators right since they are of a very obscure type
<tag>bgp_aggregator</tag> <tag>bgp_aggregator</tag>
--> -->
<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated <tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
with the route. Each such value is a pair (represented as a <cf/pair/ data with the route. Each such value is a pair (represented as a <cf/pair/ data
type inside the filters) of 16-bit integers, the first of them containing a number of the AS which defines type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines
the community and the second one is a per-AS identifier. There are lots the community and the second one being a per-AS identifier. There are lots
of uses of the community mechanism, but generally they are used to carry 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 policy information like "don't export to USA peers". As each AS can define
its own routing policy, it 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. attributes it defines and what will their semantics be.
</descrip> </descrip>
<sect1>Example <sect1>Example
@ -746,14 +824,14 @@ with `O') are optional.
<p><code> <p><code>
protocol bgp { protocol bgp {
local as 65000; # Use a private AS number local as 65000; # Use a private AS number
neighbor 62.168.0.130 as 5588; # Our neighbor neighbor 62.168.0.130 as 5588; # Our neighbor...
multihop 20 via 62.168.0.13; # Which is connected indirectly multihop 20 via 62.168.0.13; # ... which is connected indirectly
export filter { # We use non-trivial export rules export filter { # We use non-trivial export rules
if source = RTS_STATIC then { # Export only static routes if source = RTS_STATIC then { # Export only static routes
# Assign our community # Assign our community
bgp_community.add((65000,5678)); bgp_community.add((65000,5678));
# Artificially increase path length # Artificially increase path length
# by prepending local AS number twice # by advertising local AS number twice
if bgp_path ~ / 65000 / then if bgp_path ~ / 65000 / then
bgp_path.prepend(65000); bgp_path.prepend(65000);
accept; accept;
@ -761,19 +839,19 @@ protocol bgp {
reject; reject;
}; };
import all; import all;
source address 62.168.0.1; # Use non-standard source address source address 62.168.0.1; # Use a non-standard source address
} }
</code> </code>
<sect>Device <sect>Device
<p>The Device protocol is not a real routing protocol as it doesn't generate <p>The Device protocol is not a real routing protocol. It doesn't generate
any routes and only serves as a module for getting information about network any routes and it only serves as a module for getting information about network
interfaces from the kernel. interfaces from the kernel.
<p>Except for very unusual circumstances, you probably should include <p>Except for very unusual circumstances, you probably should include
this protocol in the configuration since almost all other protocol this protocol in the configuration since almost all other protocols
require network interfaces to be defined in order to work. require network interfaces to be defined for them to work with.
<p>The only configurable thing is interface scan time: <p>The only configurable thing is interface scan time:
@ -781,8 +859,8 @@ require network interfaces to be defined in order to work.
<tag>scan time <m/number/</tag> Time in seconds between two scans <tag>scan time <m/number/</tag> Time in seconds between two scans
of the network interface list. On systems where we are notified about of the network interface list. On systems where we are notified about
interface status changes asynchronously (such as newer versions of interface status changes asynchronously (such as newer versions of
Linux), we need to scan the list only to avoid confusion by lost Linux), we need to scan the list only in order to avoid confusion by lost
notifications, so the default time is set to a large value. notification messages, so the default time is set to a large value.
</descrip> </descrip>
<p>As the Device protocol doesn't generate any routes, it cannot have <p>As the Device protocol doesn't generate any routes, it cannot have
@ -802,10 +880,10 @@ by the kernel via the Device protocol.
<p>It's highly recommended to include this protocol in your configuration <p>It's highly recommended to include this protocol in your configuration
unless you want to use BIRD as a route server or a route reflector, that is unless you want to use BIRD as a route server or a route reflector, that is
on a machine which doesn't forward packets and only participates in on a machine which doesn't forward packets itself and only participates in
distribution of routing information. distribution of routing information.
<p>Only configurable thing about direct is what interfaces it watches: <p>The only configurable thing about direct is what interfaces it watches:
<p><descrip> <p><descrip>
<tag>interface <m/pattern [, ...]/</tag> By default, the Direct <tag>interface <m/pattern [, ...]/</tag> By default, the Direct
@ -829,17 +907,17 @@ protocol direct {
<sect>Kernel <sect>Kernel
<p>The Kernel protocol is not a real routing protocol. Instead of communicating <p>The Kernel protocol is not a real routing protocol. Instead of communicating
with other routers in the network, it performs synchronization of BIRD's routing the with other routers in the network, it performs synchronization of BIRD's routing
tables with OS kernel. Basically, it sends all routing table updates to the kernel tables with the OS kernel. Basically, it sends all routing table updates to the kernel
and from time to time it scans the kernel tables to see whether some routes have and from time to time it scans the kernel tables to see whether some routes have
disappeared (for example due to unnoticed up/down transition of an interface) disappeared (for example due to unnoticed up/down transition of an interface)
or whether an `alien' route has been added by someone else (depending on the or whether an `alien' route has been added by someone else (depending on the
<cf/learn/ switch, such routes are either deleted or we accept them to our <cf/learn/ switch, such routes are either deleted or accepted to our
table). table).
<p>If your OS supports only a single routing table, you can configure only one <p>If your OS supports only a single routing table, you can configure only one
instance of the Kernel protocol. If it supports multiple tables (in order to instance of the Kernel protocol. If it supports multiple tables (in order to
allow policy routing), you can run as many instances as you want, but each of allow policy routing; such an OS is for example Linux 2.2), you can run as many instances as you want, but each of
them must be connected to a different BIRD routing table and to a different them must be connected to a different BIRD routing table and to a different
kernel table. kernel table.
@ -848,7 +926,7 @@ kernel table.
<p><descrip> <p><descrip>
<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the <tag>persist <m/switch/</tag> 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).
<tag>scan time <m/number/</tag> Time in seconds between two scans of the <tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
kernel routing table. kernel routing table.
<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel <tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
routing tables by other routing daemons or by the system administrator. routing tables by other routing daemons or by the system administrator.
@ -859,6 +937,7 @@ kernel table.
only on systems supporting multiple routing tables. only on systems supporting multiple routing tables.
</descrip> </descrip>
<p>The Kernel protocol doesn't define any route attributes.
<p>A simple configuration can look this way: <p>A simple configuration can look this way:
<p><code> <p><code>
@ -886,8 +965,6 @@ protocol kernel { # Secondary routing table
} }
</code> </code>
<p>The Kernel protocol doesn't define any route attributes.
<sect>OSPF <sect>OSPF
<sect1>Introduction <sect1>Introduction
@ -1025,10 +1102,10 @@ protocol ospf &lt;name&gt; {
lacking this password are ignored. This authentication mechanism is lacking this password are ignored. This authentication mechanism is
very weak. very weak.
<tag>password <M>text</M></tag> <tag>password "<M>text</M>"</tag>
An 8-byte password used for authentication. An 8-byte password used for authentication.
<tag>neighbors</tag> <tag>neighbors { <m/set/ } </tag>
A set of neighbors to which Hello messages on nonbroadcast networks A set of neighbors to which Hello messages on nonbroadcast networks
are to be sent. are to be sent.
</descrip> </descrip>
@ -1094,21 +1171,21 @@ protocol ospf MyOSPF {
<sect1>Introduction <sect1>Introduction
<p>The Pipe protocol serves as a link between two routing tables, allowing routes to be <p>The Pipe protocol serves as a link between two routing tables, allowing routes to be
passed from a table declared as primary (i.e., the one the pipe is connected using the passed from a table declared as primary (i.e., the one the pipe is connected to using the
<cf/table/ configuration keyword) to the secondary one (declared using <cf/peer table/) <cf/table/ configuration keyword) to the secondary one (declared using <cf/peer table/)
and vice versa, depending on what's allowed by the filters. Export filters control export and vice versa, depending on what's allowed by the filters. Export filters control export
of routes from the primary table to the secondary one, import filters control the opposite of routes from the primary table to the secondary one, import filters control the opposite
direction. direction.
<p>The primary use of multiple routing tables and the pipe protocol is for policy routing, <p>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 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. on its source address, source interface, protocol type and other similar parameters.
In many systems (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 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 according to its parameters. Setting of these rules is outside the scope of BIRD's work
(you can use the <tt/ip/ command), but you can create several routing tables in BIRD, (on Linux, you can use the <tt/ip/ command), but you can create several routing tables in BIRD,
connect them to the kernel ones, use filters to control which routes appear in which tables connect them to the kernel ones, use filters to control which routes appear in which tables
and also you can employ the Pipe protocol to export a selected subset of one table in and also you can employ the Pipe protocol for exporting a selected subset of one table to
another one. another one.
<sect1>Configuration <sect1>Configuration
@ -1136,7 +1213,7 @@ and similarly for the second AS. Thus we have split our router to two logical ro
each one acting on its own routing table, having its own routing protocols on its own each one acting on its own routing table, having its own routing protocols on its own
interfaces. In order to use the other AS's routes for backup purposes, we can pass interfaces. In order to use the other AS's routes for backup purposes, we can pass
the routes between the tables through a Pipe protocol while decreasing their preferences the routes between the tables through a Pipe protocol while decreasing their preferences
and correcting their BGP paths to reflect AS boundary crossing. and correcting their BGP paths to reflect the AS boundary crossing.
<code> <code>
table as1; # Define the tables table as1; # Define the tables
@ -1222,12 +1299,12 @@ because there are no good implementations of OSPFv3.
packets are not authenticated at all, <cf/password/ means that a plaintext password is embedded packets are not authenticated at all, <cf/password/ means that a plaintext password is embedded
into each packet, and <cf/md5/ means that packets are authenticated using a md5 cryptographic into each packet, and <cf/md5/ means that packets are authenticated using a md5 cryptographic
hash. If you set authentication to not-none, it is a good idea to add <cf>passwords { }</cf> hash. If you set authentication to not-none, it is a good idea to add <cf>passwords { }</cf>
section. section. Default: none.
<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table <tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
be honored. (Always, when sent from a host on a directly connected be honored. (Always, when sent from a host on a directly connected
network or never.) Routing table updates are honored only from network or never.) Routing table updates are honored only from
neighbors, that is not configurable. neighbors, that is not configurable. Default: never.
</descrip> </descrip>
<p>There are two options that can be specified per-interface. First is <cf>metric</cf>, with <p>There are two options that can be specified per-interface. First is <cf>metric</cf>, with
@ -1271,10 +1348,11 @@ other than equally configured BIRD. I have warned you.
<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/). <tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
When routes from different RIP instances are available and all of them have the same When routes from different RIP instances are available and all of them have the same
preference, BIRD prefers the route with lowest <cf/rip_metric/. preference, BIRD prefers the route with lowest <cf/rip_metric/.
When importing a non-RIP route, the metric defaults to 5.
<tag>int <cf/rip_tag/</tag> RIP route tag: a 16-bit number which can be used <tag>int <cf/rip_tag/</tag> RIP route tag: a 16-bit number which can be used
to carry additional information with the route (for example, an originating AS number to carry additional information with the route (for example, an originating AS number
in case of external routes). in case of external routes). When importing a non-RIP route, the tag defaults to 0.
</descrip> </descrip>
<sect1>Example <sect1>Example
@ -1360,12 +1438,13 @@ relevant reading; you can get them from <HTMLURL URL="ftp://ftp.rfc-editor.org/"
<!-- <!--
LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps
LocalWords: router's eval expr num birdc ctl unix if's enums bool int ip GCC LocalWords: router's eval expr num birdc ctl UNIX if's enums bool int ip GCC
LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth 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 RTC LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC
LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU
LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc
LocalWords: compat multicasts nonbroadcast pointopoint LocalWords: compat multicasts nonbroadcast pointopoint loopback sym stats
LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt
LocalWords: proto wildcard
--> -->