Ondrej Filip <it/<feela@network.cz>/,
Pavel Machek <it/<pavel@ucw.cz>/,
Martin Mares <it/<mj@ucw.cz>/,
-Jan Matejka <it/<mq@jmq.cz>/,
+Maria Matejka <it/<mq@jmq.cz>/,
Ondrej Zajicek <it/<santiago@crfreenet.org>/
</author>
use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
<tag><label id="argv-debug">-d</tag>
- enable debug messages and run bird in foreground.
+ enable debug messages to stderr, and run bird in foreground.
- <tag><label id="argv-log-file">-D <m/filename of debug log/</tag>
- log debugging information to given file instead of stderr.
+ <tag><label id="argv-debug-file">-D <m/filename of debug log/</tag>
+ enable debug messages to given file.
<tag><label id="argv-foreground">-f</tag>
run bird in foreground.
include "tablename.conf";;
</code>
- <tag><label id="opt-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag>
- Set logging of messages having the given class (either <cf/all/ or
- <cf/{ error|trace [, <m/.../] }/ etc.) into selected destination (a file specified
- as a filename string, syslog with optional name argument, or the stderr
- output). Classes are:
+ <tag><label id="opt-log">log "<m/filename/" [<m/limit/ "<m/backup/"] | syslog [name <m/name/] | stderr all|{ <m/list of classes/ }</tag>
+ Set logging of messages having the given class (either <cf/all/ or <cf>{
+ error|trace [, <m/.../] }</cf> etc.) into selected destination - a file
+ specified as a filename string (with optional log rotation information),
+ syslog (with optional name argument), or the stderr output.
+
+ Classes are:
<cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
<cf/debug/ for debugging messages,
<cf/trace/ when you want to know what happens in the network,
<cf/remote/ for messages about misbehavior of remote machines,
<cf/auth/ about authentication failures,
<cf/bug/ for internal BIRD bugs.
+
+ Logging directly to file supports basic log rotation -- there is an
+ optional log file limit and a backup filename, when log file reaches the
+ limit, the current log file is renamed to the backup filename and a new
+ log file is created.
+
You may specify more than one <cf/log/ line to establish logging to
- multiple destinations. Default: log everything to the system log.
+ multiple destinations. Default: log everything to the system log, or
+ to the debug output if debugging is enabled by <cf/-d//<cf/-D/
+ command-line option.
<tag><label id="opt-debug-protocols">debug protocols all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag>
Set global defaults of protocol debugging options. See <cf/debug/ in the
constants based on /etc/iproute2/rt_* files. A list of defined constants
can be seen (together with other symbols) using 'show symbols' command.
+ <tag><label id="opt-attribute">attribute <m/type/ <m/name/</tag>
+ Define a custom route attribute. You can set and get it in filters like
+ any other route atribute. This feature is intended for marking routes
+ in import filters for export filtering purposes instead of locally
+ assigned BGP communities which have to be deleted in export filters.
+
<tag><label id="opt-router-id">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: the lowest
number of networks, number of routes before and after filtering). If
you use <cf/count/ instead, only the statistics will be printed.
+ <tag><label id="cli-mrt-dump">mrt dump table <m/name/|"<m/pattern/" to "<m/filename/" [filter <m/f/|where <m/c/]</tag>
+ Dump content of a routing table to a specified file in MRT table dump
+ format. See <ref id="mrt" name="MRT protocol"> for details.
+
<tag><label id="cli-configure">configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
Reload configuration from a given file. BIRD will smoothly switch itself
to the new configuration, protocols are reconfigured if possible,
the number of hops is 2. Default: enabled for iBGP.
<tag><label id="bgp-source-address">source address <m/ip/</tag>
- Define local address we should use for next hop calculation and as a
- source address for the BGP session. Default: the address of the local
- end of the interface our neighbor is connected to.
+ Define local address we should use as a source address for the BGP
+ session. Default: the address of the local end of the interface our
+ neighbor is connected to.
<tag><label id="bgp-strict-bind">strict bind <m/switch/</tag>
Specify whether BGP listening socket should be bound to a specific local
<p>BGP channels have additional config options (together with the common ones):
<descrip>
- <tag><label id="bgp-next-hop-keep">next hop keep</tag>
- Forward the received Next Hop attribute even in situations where the
- local address should be used instead, like when the route is sent to an
- interface with a different subnet. Default: disabled.
-
- <tag><label id="bgp-next-hop-self">next hop self</tag>
- Avoid calculation of the Next Hop attribute and always advertise our own
- source address as a next hop. This needs to be used only occasionally to
- circumvent misconfigurations of other routers. Default: disabled.
+ <tag><label id="bgp-next-hop-keep">next hop keep <m/switch/|ibgp|ebgp</tag>
+ Do not modify the Next Hop attribute and advertise the current one
+ unchanged even in cases where our own local address should be used
+ instead. This is necessary when the BGP speaker does not forward network
+ traffic (route servers and some route reflectors) and also can be useful
+ in some other cases (e.g. multihop EBGP sessions). Can be enabled for
+ all routes, or just for routes received from IBGP / EBGP neighbors.
+ Default: disabled for regular BGP, enabled for route servers,
+ <cf/ibgp/ for route reflectors.
+
+ <tag><label id="bgp-next-hop-self">next hop self <m/switch/|ibgp|ebgp</tag>
+ Always advertise our own local address as a next hop, even in cases
+ where the current Next Hop attribute should be used unchanged. This is
+ sometimes used for routes propagated from EBGP to IBGP when IGP routing
+ does not cover inter-AS links, therefore IP addreses of EBGP neighbors
+ are not resolvable through IGP. Can be enabled for all routes, or just
+ for routes received from IBGP / EBGP neighbors. Default: disabled.
<tag><label id="bgp-next-hop-address">next hop address <m/ip/</tag>
- Avoid calculation of the Next Hop attribute and always advertise this address
- as a next hop.
+ Specify which address to use when our own local address should be
+ announced in the Next Hop attribute. Default: the source address of the
+ BGP session (if acceptable), or the preferred address of an associated
+ interface.
<tag><label id="bgp-missing-lladdr">missing lladdr self|drop|ignore</tag>
Next Hop attribute in BGP-IPv6 sometimes contains just the global IPv6
for every allowed table type. Default: the same as the main table
the channel is connected to (if eligible).
+ <tag><label id="bgp-import-table">import table <m/switch/</tag>
+ A BGP import table contains all received routes from given BGP neighbor,
+ before application of import filters. It is also called <em/Adj-RIB-In/
+ in BGP terminology. BIRD BGP by default operates without import tables,
+ in which case received routes are just processed by import filters,
+ accepted ones are stored in the master table, and the rest is forgotten.
+ Enabling <cf/import table/ allows to store unprocessed routes, which can
+ be examined later by <cf/show route/, and can be used to reconfigure
+ import filters without full route refresh. Default: off.
+
<tag><label id="bgp-secondary">secondary <m/switch/</tag>
Usually, if an export filter rejects a selected route, no other route is
propagated for that network. This option allows to try the next route in
</code>
+<sect>MRT
+<label id="mrt">
+
+<sect1>Introduction
+<label id="mrt-intro">
+
+<p>The MRT protocol is a component responsible for handling the Multi-Threaded
+Routing Toolkit (MRT) routing information export format, which is mainly used
+for collecting and analyzing of routing information from BGP routers. The MRT
+protocol can be configured to do periodic dumps of routing tables, created MRT
+files can be analyzed later by other tools. Independent MRT table dumps can also
+be requested from BIRD client. There is also a feature to save incoming BGP
+messages in MRT files, but it is controlled by <ref id="proto-mrtdump"
+name="mrtdump"> options independently of MRT protocol, although that might
+change in the future.
+
+BIRD implements the main MRT format specification as defined in <rfc id="6396">
+and the ADD_PATH extension (<rfc id="8050">).
+
+<sect1>Configuration
+<label id="mrt-config">
+
+<p>MRT configuration consists of several statements describing routing table
+dumps. Multiple independent periodic dumps can be done as multiple MRT protocol
+instances. The MRT protocol does not use channels. There are two mandatory
+statements: <cf/filename/ and <cf/period/.
+
+The behavior can be modified by following configuration parameters:
+
+<descrip>
+ <tag><label id="mrt-table">table <m/name/ | "<m/pattern/"</tag>
+ Specify a routing table (or a set of routing tables described by a
+ wildcard pattern) that are to be dumped by the MRT protocol instance.
+ Default: the master table.
+
+ <tag><label id="mrt-filter">filter { <m/filter commands/ }</tag>
+ The MRT protocol allows to specify a filter that is applied to routes as
+ they are dumped. Rejected routes are ignored and not saved to the MRT
+ dump file. Default: no filter.
+
+ <tag><label id="mrt-where">where <m/filter expression/</tag>
+ An alternative way to specify a filter for the MRT protocol.
+
+ <tag><label id="mrt-filename">filename "<m/filename/"</tag>
+ Specify a filename for MRT dump files. The filename may contain time
+ format sequences with <it/strftime(3)/ notation (see <it/man strftime/
+ for details), there is also a sequence "%N" that is expanded to the name
+ of dumped table. Therefore, each periodic dump of each table can be
+ saved to a different file. Mandatory, see example below.
+
+ <tag><label id="mrt-period">period <m/number/</tag>
+ Specify the time interval (in seconds) between periodic dumps.
+ Mandatory.
+
+ <tag><label id="mrt-always-add-path">always add path <m/switch/</tag>
+ The MRT format uses special records (specified in <rfc id="8050">) for
+ routes received using BGP ADD_PATH extension to keep Path ID, while
+ other routes use regular records. This has advantage of better
+ compatibility with tools that do not know special records, but it loses
+ information about which route is the best route. When this option is
+ enabled, both ADD_PATH and non-ADD_PATH routes are stored in ADD_PATH
+ records and order of routes for network is preserved. Default: disabled.
+</descrip>
+
+<sect1>Example
+<label id="mrt-exam">
+
+<p><code>
+protocol mrt {
+ table "tab*";
+ where source = RTS_BGP;
+ filename "/var/log/bird/%N_%F_%T.mrt";
+ period 300;
+}
+</code>
+
+
<sect>OSPF
<label id="ospf">
Specifies interval in seconds between retransmissions of unacknowledged
updates. Default value is 5.
+ <tag><label id="ospf-transmit-delay">transmit delay <M>num</M></tag>
+ Specifies estimated transmission delay of link state updates send over
+ the interface. The value is added to LSA age of LSAs propagated through
+ it. Default value is 1.
+
<tag><label id="ospf-priority">priority <M>num</M></tag>
On every multiple access network (e.g., the Ethernet) Designated Router
and Backup Designated router are elected. These routers have some special
<m/dead/ seconds, it will consider the neighbor down. If both directives
<cf/dead count/ and <cf/dead/ are used, <cf/dead/ has precedence.
- <tag><label id="ospf-secondary">secondary <M>switch</M></tag>
- On BSD systems, older versions of BIRD supported OSPFv2 only for the
- primary IP address of an interface, other IP ranges on the interface
- were handled as stub networks. Since v1.4.1, regular operation on
- secondary IP addresses is supported, but disabled by default for
- compatibility. This option allows to enable it. The option is a
- transitional measure, will be removed in the next major release as the
- behavior will be changed. On Linux systems, the option is irrelevant, as
- operation on non-primary addresses is already the regular behavior.
-
<tag><label id="ospf-rx-buffer">rx buffer <M>num</M></tag>
This option allows to specify the size of buffers used for packet
processing. The buffer size should be bigger than maximal size of any
}
</code>
+<sect>Perf
+<label id="perf">
+
+<sect1>Introduction
+<label id="perf-intro">
+
+<p>The Perf protocol is a generator of fake routes together with a time measurement
+framework. Its purpose is to check BIRD performance and to benchmark filters.
+
+<p>Import mode of this protocol runs in several steps. In each step, it generates 2^x routes,
+imports them into the appropriate table and withdraws them. The exponent x is configurable.
+It runs the benchmark several times for the same x, then it increases x by one
+until it gets too high, then it stops.
+
+<p>Export mode of this protocol repeats route refresh from table and measures how long it takes.
+
+<p>Output data is logged on info level. There is a Perl script <cf>proto/perf/parse.pl</cf>
+which may be handy to parse the data and draw some plots.
+
+<p>Implementation of this protocol is experimental. Use with caution and do not keep
+any instance of Perf in production configs for long time. The config interface is also unstable
+and may change in future versions without warning.
+
+<sect1>Configuration
+<label id="perf-config">
+
+<p><descrip>
+ <tag><label id="perf-mode">mode import|export</tag>
+ Set perf mode. Default: import
+
+ <tag><label id="perf-repeat">repeat <m/number/</tag>
+ Run this amount of iterations of the benchmark for every amount step. Default: 4
+
+ <tag><label id="perf-from">exp from <m/number/</tag>
+ Begin benchmarking on this exponent for number of generated routes in one step.
+ Default: 10
+
+ <tag><label id="perf-to">exp to <m/number/</tag>
+ Stop benchmarking on this exponent. Default: 20
+
+ <tag><label id="perf-threshold-min">threshold min <m/time/</tag>
+ If a run for the given exponent took less than this time for route import,
+ increase the exponent immediately. Default: 1 ms
+
+ <tag><label id="perf-threshold-max">threshold max <m/time/</tag>
+ If every run for the given exponent took at least this time for route import,
+ stop benchmarking. Default: 500 ms
+</descrip>
<sect>Pipe
<label id="pipe">
projects / thirdparty / bird.git / blobdiff