Commit b9864aa8 authored by Pavel Tvrdik's avatar Pavel Tvrdik
Browse files

Doc: Add labels to all chapters and options

parent a2df7c03
......@@ -39,11 +39,12 @@ This document contains user documentation for the BIRD Internet Routing Daemon p
<chapt>Introduction
<label id="intro">
<sect>What is BIRD
<label id="what-is-bird">
<p><label id="intro">
The name `BIRD' is actually an acronym standing for `BIRD Internet Routing
<p>The name `BIRD' is actually an acronym standing for `BIRD Internet Routing
Daemon'. Let's take a closer look at the meaning of the name:
<p><em/BIRD/: Well, we think we have already explained that. It's an acronym
......@@ -118,6 +119,7 @@ files, tools ...).
<sect>Installing BIRD
<label id="install">
<p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make)
and Perl, installing BIRD should be as easy as:
......@@ -138,45 +140,46 @@ BIRD executable by configuring out routing protocols you don't use, and
<sect>Running BIRD
<label id="argv">
<p>You can pass several command-line options to bird:
<descrip>
<tag>-c <m/config name/</tag>
<tag><label id="argv-config">-c <m/config name/</tag>
use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
<tag>-d</tag>
<tag><label id="argv-debug">-d</tag>
enable debug messages and run bird in foreground.
<tag>-D <m/filename of debug log/</tag>
<tag><label id="argv-log-file">-D <m/filename of debug log/</tag>
log debugging information to given file instead of stderr.
<tag>-p</tag>
<tag><label id="argv-parse">-p</tag>
just parse the config file and exit. Return value is zero if the config
file is valid, nonzero if there are some errors.
<tag>-s <m/name of communication socket/</tag>
<tag><label id="argv-socket">-s <m/name of communication socket/</tag>
use given filename for a socket for communications with the client,
default is <it/prefix/<file>/var/run/bird.ctl</file>.
<tag>-P <m/name of PID file/</tag>
<tag><label id="argv-pid">-P <m/name of PID file/</tag>
create a PID file with given filename.
<tag>-u <m/user/</tag>
<tag><label id="argv-user">-u <m/user/</tag>
drop privileges and use that user ID, see the next section for details.
<tag>-g <m/group/</tag>
<tag><label id="argv-group">-g <m/group/</tag>
use that group ID, see the next section for details.
<tag>-f</tag>
<tag><label id="argv-foreground">-f</tag>
run bird in foreground.
<tag>-l</tag>
<tag><label id="argv-local">-l</tag>
look for a configuration file and a communication socket in the current
working directory instead of in default system locations. However, paths
specified by options <cf/-c/, <cf/-s/ have higher priority.
<tag>-R</tag>
<tag><label id="argv-recovery">-R</tag>
apply graceful restart recovery after start.
</descrip>
......@@ -184,6 +187,7 @@ BIRD executable by configuring out routing protocols you don't use, and
<sect>Privileges
<label id="privileges">
<p>BIRD, as a routing daemon, uses several privileged operations (like setting
routing table and using raw sockets). Traditionally, BIRD is executed and runs
......@@ -208,6 +212,7 @@ the config file and create the control socket and the CAP_NET_* capabilities.
<chapt>About routing tables
<label id="routing-tables">
<p>BIRD has one or more routing tables which may or may not be synchronized with
OS kernel and which may or may not be synchronized with each other (see the Pipe
......@@ -245,7 +250,7 @@ network. Note that although most protocols are interested in receiving just
selected routes, some protocols (e.g. the <cf/Pipe/ protocol) receive and
process all entries in routing tables (accepted by filters).
<p><label id="dsc-sorted">Usually, a routing table just chooses a selected route
<p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected route
from a list of entries for one network. But if the <cf/sorted/ option is
activated, these lists of entries are kept completely sorted (according to
preference or some protocol-dependent metric). This is needed for some features
......@@ -259,6 +264,7 @@ is that it is slightly more computationally expensive.
<sect>Graceful restart
<label id="graceful-restart">
<p>When BIRD is started after restart or crash, it repopulates routing tables in
an uncoordinated manner, like after clean start. This may be impractical in some
......@@ -274,8 +280,10 @@ particular boot by option <cf/-R/.
<chapt>Configuration
<label id="config">
<sect>Introduction
<label id="config-intro">
<p>BIRD is configured using a text configuration file. Upon startup, BIRD reads
<it/prefix/<file>/etc/bird.conf</file> (unless the <tt/-c/ command line option
......@@ -319,15 +327,16 @@ protocol rip {
<sect>Global options
<label id="global-opts">
<p><descrip>
<tag>include "<m/filename/"</tag>
<tag><label id="opt-include">include "<m/filename/"</tag>
This statement causes inclusion of a new file. <m/Filename/ could also
be a wildcard, in that case matching files are included in alphabetic
order. The maximal depth is 8. Note that this statement could be used
anywhere in the config file, not just as a top-level option.
<tag><label id="dsc-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag>
<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 }/ etc.) into selected destination (a file specified
as a filename string, syslog with optional name argument, or the stderr
......@@ -341,48 +350,48 @@ protocol rip {
You may specify more than one <cf/log/ line to establish logging to
multiple destinations. Default: log everything to the system log.
<tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
<tag><label id="opt-debug-protocols">debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
Set global defaults of protocol debugging options. See <cf/debug/ in the
following section. Default: off.
<tag>debug commands <m/number/</tag>
<tag><label id="opt-debug-commands">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>debug latency <m/switch/</tag>
<tag><label id="opt-debug-latency">debug latency <m/switch/</tag>
Activate tracking of elapsed time for internal events. Recent events
could be examined using <cf/dump events/ command. Default: off.
<tag>debug latency limit <m/time/</tag>
<tag><label id="opt-debug-latency-limit">debug latency limit <m/time/</tag>
If <cf/debug latency/ is enabled, this option allows to specify a limit
for elapsed time. Events exceeding the limit are logged. Default: 1 s.
<tag>watchdog warning <m/time/</tag>
<tag><label id="opt-watchdog-warn">watchdog warning <m/time/</tag>
Set time limit for I/O loop cycle. If one iteration took more time to
complete, a warning is logged. Default: 5 s.
<tag>watchdog timeout <m/time/</tag>
<tag><label id="opt-watchdog-timeout">watchdog timeout <m/time/</tag>
Set time limit for I/O loop cycle. If the limit is breached, BIRD is
killed by abort signal. The timeout has effective granularity of
seconds, zero means disabled. Default: disabled (0).
<tag>mrtdump "<m/filename/"</tag>
<tag><label id="opt-mrtdump">mrtdump "<m/filename/"</tag>
Set MRTdump file name. This option must be specified to allow MRTdump
feature. Default: no dump file.
<tag>mrtdump protocols all|off|{ states, messages }</tag>
<tag><label id="opt-mrtdump-protocols">mrtdump protocols all|off|{ states, messages }</tag>
Set global defaults of MRTdump options. See <cf/mrtdump/ in the
following section. Default: off.
<tag>filter <m/name local variables/{ <m/commands/ }</tag>
<tag><label id="opt-filter">filter <m/name local variables/{ <m/commands/ }</tag>
Define a filter. You can learn more about filters in the following
chapter.
<tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag>
<tag><label id="opt-function">function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag>
Define a function. You can learn more about functions in the following chapter.
<tag>protocol rip|ospf|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
<tag><label id="opt-protocol">protocol rip|ospf|bgp|... [<m/name/ [from <m/name2/]] { <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 any
<cf><m/name/</cf>). You can learn more about configuring protocols in
......@@ -391,7 +400,7 @@ protocol rip {
<cf><m/name2/</cf> You can run more than one instance of most protocols
(like RIP or BGP). By default, no instances are configured.
<tag>template rip|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
<tag><label id="opt-template">template rip|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
Define a protocol template instance called <m/name/ (or with a name like
"bgp1" generated automatically if you don't specify any <m/name/).
Protocol templates can be used to group common options when many
......@@ -400,25 +409,25 @@ protocol rip {
expression and the name of the template. At the moment templates (and
<cf/from/ expression) are not implemented for OSPF protocol.
<tag>define <m/constant/ = <m/expression/</tag>
<tag><label id="opt-define">define <m/constant/ = <m/expression/</tag>
Define a constant. You can use it later in every place you could use a
value of the same type. Besides, there are some predefined numeric
constants based on /etc/iproute2/rt_* files. A list of defined constants
can be seen (together with other symbols) using 'show symbols' command.
<tag>router id <m/IPv4 address/</tag>
Set BIRD's router ID. It's a world-wide unique identification of your
<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: in IPv4
version, the lowest IP address of a non-loopback interface. In IPv6
version, this option is mandatory.
<tag>router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...]</tag>
<tag><label id="opt-router-id-from">router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...]</tag>
Set BIRD's router ID based on an IP address of an interface specified by
an interface pattern. The option is applicable for IPv4 version only.
See <ref id="dsc-iface" name="interface"> section for detailed
See <ref id="proto-iface" name="interface"> section for detailed
description of interface patterns with extended clauses.
<tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
<tag><label id="opt-listen-bgp">listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
This option allows to specify address and port where BGP protocol should
listen. It is global option as listening socket is common to all BGP
instances. Default is to listen on all addresses (0.0.0.0) and port 179.
......@@ -427,13 +436,13 @@ protocol rip {
BIRD would accept IPv6 routes only). Such behavior was default in older
versions of BIRD.
<tag>graceful restart wait <m/number/</tag>
<tag><label id="opt-graceful-restart">graceful restart wait <m/number/</tag>
During graceful restart recovery, BIRD waits for convergence of routing
protocols. This option allows to specify a timeout for the recovery to
prevent waiting indefinitely if some protocols cannot converge. Default:
240 seconds.
<tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
<tag><label id="opt-timeformat">timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
This option allows to specify a format of date/time used by BIRD. The
first argument specifies for which purpose such format is used.
<cf/route/ is a format used in 'show route' command output,
......@@ -459,13 +468,13 @@ protocol rip {
hh:mm:ss) for <cf/base/ and <cf/log/. These timeformats could be set by
<cf/old short/ and <cf/old long/ compatibility shorthands.
<tag>table <m/name/ [sorted]</tag>
<tag><label id="opt-table">table <m/name/ [sorted]</tag>
Create a new routing table. The default routing table is created
implicitly, other routing tables have to be added by this command.
Option <cf/sorted/ can be used to enable sorting of routes, see
<ref id="dsc-sorted" name="sorted table"> description for details.
<ref id="dsc-table-sorted" name="sorted table"> description for details.
<tag>roa table <m/name/ [ { roa table options ... } ]</tag>
<tag><label id="opt-roa-table">roa table <m/name/ [ { roa table options ... } ]</tag>
Create a new ROA (Route Origin Authorization) table. ROA tables can be
used to validate route origination of BGP routes. A ROA table contains
ROA entries, each consist of a network prefix, a max prefix length and
......@@ -479,12 +488,13 @@ protocol rip {
ROA entries. The option may be used multiple times. Other entries can be
added dynamically by <cf/add roa/ command.
<tag>eval <m/expr/</tag>
<tag><label id="opt-eval">eval <m/expr/</tag>
Evaluates given filter expression. It is used by us for testing of filters.
</descrip>
<sect>Protocol options
<label id="protocol-opts">
<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
......@@ -497,16 +507,16 @@ disable it. An empty <m/switch/ is equivalent to <cf/on/ ("silence means
agreement").
<descrip>
<tag>preference <m/expr/</tag>
<tag><label id="proto-preference">preference <m/expr/</tag>
Sets the preference of routes generated by this protocol. Default:
protocol dependent.
<tag>disabled <m/switch/</tag>
<tag><label id="proto-disabled">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 protocols are not activated. Default: protocol is enabled.
<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
<tag><label id="proto-debug">debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
Set protocol debugging options. If asked, each protocol is capable of
writing trace messages about its work to the log (with category
<cf/trace/). You can either request printing of <cf/all/ trace messages
......@@ -517,7 +527,7 @@ agreement").
protocol, <cf/events/ for events internal to the protocol and <cf/packets/
for packets sent and received by the protocol. Default: off.
<tag>mrtdump all|off|{ states, messages }</tag>
<tag><label id="proto-mrtdump">mrtdump all|off|{ states, messages }</tag>
Set protocol MRTdump flags. MRTdump is a standard binary format for
logging information from routing protocols and daemons. These flags
control what kind of information is logged from the protocol to the
......@@ -527,27 +537,27 @@ agreement").
BGP protocol, <cf/states/ logs BGP state changes and <cf/messages/ logs
received BGP messages. Other protocols does not support MRTdump yet.
<tag>router id <m/IPv4 address/</tag>
<tag><label id="proto-router-id">router id <m/IPv4 address/</tag>
This option can be used to override global router id for a given
protocol. Default: uses global router id.
<tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag>
<tag><label id="proto-import">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 the
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>
<tag><label id="proto-export">export <m/filter/</tag>
This is similar to the <cf>import</cf> keyword, except that it works in
the direction from the routing table to the protocol. Default: <cf/none/.
<tag>import keep filtered <m/switch/</tag>
<tag><label id="proto-import-keep-filtered">import keep filtered <m/switch/</tag>
Usually, if an import filter rejects a route, the route is forgotten.
When this option is active, these routes are kept in the routing table,
but they are hidden and not propagated to other protocols. But it is
possible to show them using <cf/show route filtered/. Note that this
option does not work for the pipe protocol. Default: off.
<tag><label id="import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
<tag><label id="proto-import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
Specify an import route limit (a maximum number of routes imported from
the protocol) and optionally the action to be taken when the limit is
hit. Warn action just prints warning log message. Block action discards
......@@ -556,7 +566,7 @@ agreement").
action if an action is not explicitly specified. Note that limits are
reset during protocol reconfigure, reload or restart. Default: <cf/off/.
<tag>receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
<tag><label id="proto-receive-limit">receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
Specify an receive route limit (a maximum number of routes received from
the protocol and remembered). It works almost identically to <cf>import
limit</cf> option, the only difference is that if <cf/import keep
......@@ -566,7 +576,7 @@ agreement").
on the contrary, counts accepted routes only and routes blocked by the
limit are handled like filtered routes. Default: <cf/off/.
<tag>export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
<tag><label id="proto-export-limit">export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
Specify an export route limit, works similarly to the <cf>import
limit</cf> option, but for the routes exported to the protocol. This
option is experimental, there are some problems in details of its
......@@ -576,18 +586,18 @@ agreement").
updates of already accepted routes -- and these details will probably
change in the future. Default: <cf/off/.
<tag>description "<m/text/"</tag>
<tag><label id="proto-description">description "<m/text/"</tag>
This is an optional description of the protocol. It is displayed as a
part of the output of 'show route all' command.
<tag>table <m/name/</tag>
<tag><label id="proto-table">table <m/name/</tag>
Connect this protocol to a non-default routing table.
</descrip>
<p>There are several options that give sense only with certain protocols:
<descrip>
<tag><label id="dsc-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...] [ { <m/option/ ; [...] } ]</tag>
<tag><label id="proto-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...] [ { <m/option/ ; [...] } ]</tag>
Specifies a set of interfaces on which the protocol is activated with
given interface-specific options. A set of interfaces specified by one
interface option is described using an interface pattern. The interface
......@@ -634,7 +644,7 @@ agreement").
<cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all
ethernet interfaces that have address from 192.168.1.0/24.
<tag><label id="dsc-prio">tx class|dscp <m/num/</tag>
<tag><label id="proto-tx-class">tx class|dscp <m/num/</tag>
This option specifies the value of ToS/DS/Class field in IP headers of
the outgoing protocol packets. This may affect how the protocol packets
are processed by the network relative to the other network traffic. With
......@@ -643,12 +653,12 @@ agreement").
keyword, the value (0-63) is used just for the DS field in the octet.
Default value is 0xc0 (DSCP 0x30 - CS6).
<tag>tx priority <m/num/</tag>
<tag><label id="proto-tx-priority">tx priority <m/num/</tag>
This option specifies the local packet priority. This may affect how the
protocol packets are processed in the local TX queues. This option is
Linux specific. Default value is 7 (highest priority, privileged traffic).
<tag><label id="dsc-pass">password "<m/password/" [ { id <m/num/; generate from <m/time/; generate to <m/time/; accept from <m/time/; accept to <m/time/; } ]</tag>
<tag><label id="proto-pass">password "<m/password/" [ { id <m/num/; generate from <m/time/; generate to <m/time/; accept from <m/time/; accept to <m/time/; } ]</tag>
Specifies a password that can be used by the protocol. Password option
can be used more times to specify more passwords. If more passwords are
specified, it is a protocol-dependent decision which one is really
......@@ -659,35 +669,35 @@ agreement").
This option is allowed in OSPF and RIP protocols. BGP has also
<cf/password/ option, but it is slightly different and described
separately.
Default: none.
</descrip>
<p>Password option can contain section with some (not necessary all) password sub-options:
<descrip>
<tag>id <M>num</M></tag>
<tag><label id="proto-pass-id">id <M>num</M></tag>
ID of the password, (1-255). If it is not used, BIRD will choose ID based
on an order of the password item in the interface. For example, second
password item in one interface will have default ID 2. ID is used by
some routing protocols to identify which password was used to
authenticate protocol packets.
<tag>generate from "<m/time/"</tag>
<tag><label id="proto-pass-gen-from">generate from "<m/time/"</tag>
The start time of the usage of the password for packet signing.
The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
<tag>generate to "<m/time/"</tag>
<tag><label id="proto-pass-gen-to">generate to "<m/time/"</tag>
The last time of the usage of the password for packet signing.
<tag>accept from "<m/time/"</tag>
<tag><label id="proto-pass-accept-from">accept from "<m/time/"</tag>
The start time of the usage of the password for packet verification.
<tag>accept to "<m/time/"</tag>
<tag><label id="proto-pass-accept-to">accept to "<m/time/"</tag>
The last time of the usage of the password for packet verification.
</descrip>
<chapt>Remote control
<label id="remote-control">
<p>You can use the command-line client <file>birdc</file> to talk with a running
BIRD. Communication is done using a <file/bird.ctl/ UNIX domain socket (unless
......@@ -713,26 +723,26 @@ This argument can be omitted if there exists only a single instance.
<p>Here is a brief list of supported functions:
<descrip>
<tag>show status</tag>
<tag><label id="cli-show-status">show status</tag>
Show router status, that is BIRD version, uptime and time from last
reconfiguration.
<tag>show interfaces [summary]</tag>
<tag><label id="cli-show-interfaces">show interfaces [summary]</tag>
Show the list of interfaces. For each interface, print its type, state,
MTU and addresses assigned.
<tag>show protocols [all]</tag>
<tag><label id="cli-show-protocols">show protocols [all]</tag>
Show list of protocol instances along with tables they are connected to
and protocol status, possibly giving verbose information, if <cf/all/ is
specified.
<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
<tag><label id="cli-show-ospf-iface">show ospf interface [<m/name/] ["<m/interface/"]</tag>
Show detailed information about OSPF interfaces.
<tag>show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
<tag><label id="cli-show-ospf-neighbors">show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
Show a list of OSPF neighbors and a state of adjacency to them.
<tag>show ospf state [all] [<m/name/]</tag>
<tag><label id="cli-show-ospf-state">show ospf state [all] [<m/name/]</tag>
Show detailed information about OSPF areas based on a content of the
link-state database. It shows network topology, stub networks,
aggregated networks and routers from other areas and external routes.
......@@ -740,31 +750,31 @@ This argument can be omitted if there exists only a single instance.
<cf/all/ to show information about all network nodes in the link-state
database.
<tag>show ospf topology [all] [<m/name/]</tag>
<tag><label id="cli-show-ospf-topology">show ospf topology [all] [<m/name/]</tag>
Show a topology of OSPF areas based on a content of the link-state
database. It is just a stripped-down version of 'show ospf state'.
<tag>show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag>
<tag><label id="cli-show-ospf-lsadb">show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag>
Show contents of an OSPF LSA database. Options could be used to filter
entries.
<tag>show rip interfaces [<m/name/] ["<m/interface/"]</tag>
<tag><label id="cli-show-rip-interfaces">show rip interfaces [<m/name/] ["<m/interface/"]</tag>
Show detailed information about RIP interfaces.
<tag>show rip neighbors [<m/name/] ["<m/interface/"]</tag>
<tag><label id="cli-show-rip-neighbors">show rip neighbors [<m/name/] ["<m/interface/"]</tag>
Show a list of RIP neighbors and associated state.
<tag>show static [<m/name/]</tag>
<tag><label id="cli-show-static">show static [<m/name/]</tag>
Show detailed information about static routes.
<tag>show bfd sessions [<m/name/]</tag>
<tag><label id="cli-show-bfd-sessions">show bfd sessions [<m/name/]</tag>
Show information about BFD sessions.
<tag>show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag>
<tag><label id="cli-show-symbols">show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag>
Show the list of symbols defined in the configuration (names of
protocols, routing tables etc.).
<tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [<m/options/]</tag>
<tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [<m/options/]</tag>
Show contents of a routing table (by default of the main one or the
table attached to a respective protocol), that is routes, their metrics
and (in case the <cf/all/ switch is given) all their attributes.
......@@ -799,7 +809,7 @@ This argument can be omitted if there exists only a single instance.
number of networks, number of routes before and after filtering). If
you use <cf/count/ instead, only the statistics will be printed.
<tag>show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/>]</tag>
<tag><label id="cli-show-roa">show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/>]</tag>
Show contents of a ROA table (by default of the first one). You can
specify a <m/prefix/ to print ROA entries for a specific network. If you
use <cf>for <m/prefix/</cf>, you'll get all entries relevant for route
......@@ -808,19 +818,19 @@ This argument can be omitted if there exists only a single instance.
entries covered by the network prefix. You could also use <cf/as/ option
to show just entries for given AS.
<tag>add roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
<tag><label id="cli-add-roa">add roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
Add a new ROA entry to a ROA table. Such entry is called <it/dynamic/
compared to <it/static/ entries specified in the config file. These
dynamic entries survive reconfiguration.
<tag>delete roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
<tag><label id="cli-delete-roa">delete roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
Delete the specified ROA entry from a ROA table. Only dynamic ROA
entries (i.e., the ones added by <cf/add roa/ command) can be deleted.
<tag>flush roa [table <m/t/>]</tag>
<tag><label id="cli-flush-roa">flush roa [table <m/t/>]</tag>
Remove all dynamic ROA entries from a ROA table.
<tag>configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
<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,
restarted otherwise. Changes in filters usually lead to restart of
......@@ -839,11 +849,11 @@ This argument can be omitted if there exists only a single instance.
config timeout expiration is equivalent to <cf/configure undo/
command. The timeout duration could be specified, default is 300 s.
<tag>configure confirm</tag>
<tag><label id="cli-configure-confirm">configure confirm</tag>
Deactivate the config undo timer and therefore confirm the current
configuration.
<tag>configure undo</tag>
<tag><label id="cli-configure-undo">configure undo</tag>
Undo the last configuration change and smoothly switch back to the
previous (stored) configuration. If the last configuration change was
soft, the undo change is also soft. There is only one level of undo, but
......@@ -851,15 +861,15 @@ This argument can be omitted if there exists only a single instance.
immediately in a row and the intermediate ones are skipped then the undo
also skips them back.
<tag>configure check ["<m/config file/"]</tag>
<tag><label id="cli-configure-check">configure check ["<m/config file/"]</tag>
Read and parse given config file, but do not use it. useful for checking
syntactic and some semantic validity of an config file.
<tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
<tag><label id="cli-enable-disable-restart">enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
Enable, disable or restart a given protocol instance, instances matching
the <cf><m/pattern/</cf> or <cf/all/ instances.
<tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
<tag><label id="cli-reload">reload [in|out] <m/name/|"<m/pattern/"|all</tag>
Reload a given protocol instance, that means re-import routes from the
protocol instance and re-export preferred routes to the instance. If
<cf/in/ or <cf/out/ options are used, the command is restricted to one
......@@ -876,27 +886,29 @@ This argument can be omitted if there exists only a single instance.
pipe protocol, both directions are always reloaded together (<cf/in/ or
<cf/out/ options are ignored in that case).
<tag/down/
<tag><label id="cli-down">down</tag>
Shut BIRD down.
<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
<tag><label id="cli-debug">debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
Control protocol debugging.
<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
<tag><label id="cli-dump">dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
Dump contents of internal data structures to the debugging output.
<tag>echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag>
<tag><label id="cli-echo">echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag>
Control echoing of log messages to the command-line output.
See <ref id="dsc-log" name="log option"> for a list of log classes.
See <ref id="opt-log" name="log option"> for a list of log classes.
<tag>eval <m/expr/</tag>
<tag><label id="cli-eval">eval <m/expr/</tag>
Evaluate given expression.
</descrip>
<chapt>Filters
<label id="filters">
<sect>Introduction
<label id="filters-intro">
<p>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
......@@ -984,33 +996,34 @@ bird>
<sect>Data types
<label id="data-types">
<p>Each variable and each value has certain type. Booleans, integers and enums
are incompatible with each other (that is to prevent you from shooting in the
foot).
<descrip>
<tag/bool/
<tag><label id="type-bool">bool</tag>
This is a boolean type, it can have only two values, <cf/true/ and
<cf/false/. Boolean is the only type you can use in <cf/if/ statements.
<tag/int/
<tag><label id="type-int">int</tag>
This is a general integer type. It is an unsigned 32bit type; i.e., you
can expect it to store values from 0 to 4294967295. Overflows are not
checked. You can use <cf/0x1234/ syntax to write hexadecimal values.
<tag/pair/
<tag><label id="type-pair">pair</tag>
This is a pair of two short integers. Each component can have values
from 0 to 65535. Literals of this type are written as <cf/(1234,5678)/.
The same syntax can also be used to construct a pair from two arbitrary
integer expressions (for example <cf/(1+2,a)/).
<tag/quad/
<tag><label id="type-quad">quad</tag>
This is a dotted quad of numbers used to represent router IDs (and
others). Each component can have a value from 0 to 255. Literals of
this type are written like IPv4 addresses.
<tag/string/
<tag><label id="type-string">string</tag>
This is a string of characters. There are no ways to modify strings in
filters. You can pass them between functions, assign them to variables
of type <cf/string/, print such variables, use standard string
......@@ -1020,7 +1033,7 @@ foot).
!&tilde;/) operators could be used to match a string value against
a shell pattern (represented also as a string).
<tag/ip/
<tag><label id="type-ip">ip</tag>
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. IP addresses are written in the standard notation
......@@ -1029,7 +1042,7 @@ foot).
first <cf><M>num</M></cf> bits from the IP address. So
<cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.