Next Previous Contents

## 4. Remote control

## 4.1 Overview

You can use the command-line client `birdc` to talk with a running BIRD. Communication is done using the appropriate UNIX domain socket. The commands can perform simple actions such as enabling/disabling of protocols, telling BIRD to show various information, telling it to show routing table filtered by filter, or asking BIRD to reconfigure. Press `?` at any time to get online help. Option `-r` can be used to enable a restricted mode of BIRD client, which allows just read-only commands (`show ...`). Option `-v` can be passed to the client, to make it dump numeric return codes along with the messages. You do not necessarily need to use `birdc` to talk to BIRD, your own applications could do that, too -- the format of communication between BIRD and `birdc` is stable (see the programmer's documentation).

There is also lightweight variant of BIRD client called `birdcl`, which does not support command line editing and history and has minimal dependencies. This is useful for running BIRD in resource constrained environments, where Readline library (required for regular BIRD client) is not available.

## 4.2 Configuration

By default, BIRD opens `bird.ctl` UNIX domain socket and the CLI tool connects to it. If changed on the command line by the `-s` option, BIRD or the CLI tool connects there instead.

It's also possible to configure additional remote control sockets in the configuration file by `cli "name" { options };` and you can open how many sockets you wish. There are no checks whether the user configured the same socket multiple times and BIRD may behave weirdly if this happens. On shutdown, the additional sockets get removed immediately and only the main socket stays until the very end. If there are no options, the braces may be omitted.

Options:

`restrict`

  Set the socket to be restricted as if the user always sent the `restrict` command after connecting. The user may still overload the daemon by requesting insanely complex filters so you shouldn't expose this socket to public even if restricted.

`v2 attributes`

  Display the names and composition of route attributes the same way as BIRD 2 does. This is a compatibility option for easier transition from BIRD 2 to BIRD 3.

## 4.3 Usage

Here is a brief list of supported functions.

Note: Many commands have the name of the protocol instance as an argument. This argument can be omitted if there exists only a single instance.

`show status`

  Show router status, that is BIRD version, uptime and time from last reconfiguration.

`show memory`

  Show BIRD memory statistics. BIRD does not stop other computations in order to measure the used memory, hence the measured memory usage may differ from the real memory usage.

`show interfaces [summary]`

  Show the list of interfaces. For each interface, print its type, state, MTU and addresses assigned.

`show protocols [all]`

  Show list of protocol instances along with tables they are connected to and protocol status, possibly giving verbose information, if `all` is specified.

`reload bgp [in|out] [name]`

  Manually request (in) or send (out) route refresh (or both) on the given BGP protocol(s).

`show ospf interface [name] ["interface"]`

  Show detailed information about OSPF interfaces.

`show ospf neighbors [name] ["interface"]`

  Show a list of OSPF neighbors and a state of adjacency to them.

`show ospf state [all] [name]`

  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. The command shows information about reachable network nodes, use option `all` to show information about all network nodes in the link-state database.

`show ospf topology [all] [name]`

  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'.

`show ospf lsadb [global | area id | link] [type number] [lsid id] [self | router id] [name]`

  Show contents of an OSPF LSA database. Options could be used to filter entries.

`show rip interfaces [name] ["interface"]`

  Show detailed information about RIP interfaces.

`show rip neighbors [name] ["interface"]`

  Show a list of RIP neighbors and associated state.

`show static [name]`

  Show detailed information about static routes.

`show bfd sessions [name] [address (IP|prefix)] [(interface|dev) "name"] [ipv4|ipv6] [direct|multihop] [all]`

  Show information about BFD sessions. Options could be used to filter entries, or in the case of the option `all` to give verbose output.

`show symbols [table|filter|function|protocol|template|roa|symbol]`

  Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).

`show route [[(for|in)] prefix|for IP] [table (t|all)] [(import|export) table p.c] [filter f|where cond] [(export|preexport|noexport) p] [protocol p] [(stats|count)] [options]`

  Show contents of specified routing tables, that is routes, their metrics and (in case the `all` switch is given) all their attributes.

  You can specify a prefix if you want to print routes for a specific network. If you use `for prefix or IP`, you'll get the entry which will be used for forwarding of packets to the given destination. Finally, if you use `in prefix`, you get all prefixes covered by the given prefix. By default, all routes for each network are printed with the selected one at the top, unless `primary` is given in which case only the selected route is shown.

  The `show route` command can process one or multiple routing tables. The set of selected tables is determined on three levels: First, tables can be explicitly selected by `table` switch, which could be used multiple times, all tables are specified by `table all`. Second, tables can be implicitly selected by channels or protocols that are arguments of several other switches (e.g., `export`, `protocol`). Last, the set of default tables is used: `master4`, `master6` and each first table of any other network type.

  There are internal tables when `(import|export) table` options are used for some channels. They can be selected explicitly with `(import|export) table` switch, specifying protocol p and channel name c.

  You can also ask for printing only routes processed and accepted by a given filter (`filter name` or `filter { filter }` or matching a given condition (`where condition`).

  The `export`, `preexport` and `noexport` switches ask for printing of routes that are exported to the specified protocol or channel. With `preexport`, the export filter of the channel is skipped. With `noexport`, routes rejected by the export filter are printed instead. Note that routes not exported for other reasons (e.g. secondary routes or routes imported from that protocol) are not printed even with `noexport`. These switches also imply that associated routing tables are selected instead of default ones.

  You can also select just routes added by a specific protocol. `protocol p`. This switch also implies that associated routing tables are selected instead of default ones.

  If BIRD is configured to keep filtered routes (see `import keep filtered` option), you can show them instead of routes by using `filtered` switch.

  The `stats` switch requests showing of route statistics (the number of networks, number of routes before and after filtering). If you use `count` instead, only the statistics will be printed.

`mrt dump table name|"pattern" to "filename" [filter f|where c]`

  Dump content of a routing table to a specified file in MRT table dump format. See MRT protocol for details.

`configure [soft] ["config file"] [timeout [number]]`

  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 affected protocols.

  The previous configuration is saved and the user can switch back to it with configure undo command. The old saved configuration is released (even if the reconfiguration attempt fails due to e.g. a syntax error).

  If `soft` option is used, changes in filters does not cause BIRD to restart affected protocols, therefore already accepted routes (according to old filters) would be still propagated, but new routes would be processed according to the new filters.

  If `timeout` option is used, config timer is activated. The new configuration could be either confirmed using `configure confirm` command, or it will be reverted to the old one when the config timer expires. This is useful for cases when reconfiguration breaks current routing and a router becomes inaccessible for an administrator. The config timeout expiration is equivalent to `configure undo` command. The timeout duration could be specified, default is 300 s.

`configure confirm`

  Deactivate the config undo timer and therefore confirm the current configuration.

`configure undo`

  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 in some specific cases when several reconfiguration requests are given immediately in a row and the intermediate ones are skipped then the undo also skips them back.

`configure check ["config file"]`

  Read and parse given config file, but do not use it. useful for checking syntactic and some semantic validity of an config file.

`enable|disable|restart name|"pattern"|all`

  Enable, disable or restart a given protocol instance, instances matching the `pattern` or `all` instances.

`reload filters [in|out] (name|"pattern"|all) [partial prefix]`

  Reload a given protocol instance, that means re-import routes from the protocol instance and re-export preferred routes to the instance. If `in` or `out` options are used, the command is restricted to one direction (re-import or re-export).

  This command is useful if appropriate filters have changed but the protocol instance was not restarted (or reloaded), therefore it still propagates the old set of routes. For example when `configure soft` command was used to change filters.

  If `partial prefix` option is used, only corresponding routes are reloaded. Protocol BGP does partial reload only if it has import table enabled, otherwise partial reload for BGP is refused.

  Re-export always succeeds, but re-import is protocol-dependent and might fail (for example, if BGP neighbor does not support route-refresh extension). In that case, re-export is also skipped. Note that for the pipe protocol, both directions are always reloaded together (`in` or `out` options are ignored in that case).

`timeformat "format1" [limit "format2"]`

  Override format of date/time used by BIRD in this CLI session.

  Meaning of "format1", limit, and "format2" is the same as in the timeformat configuration option. Also, the same `iso ...` shorthands may be used.

`down`

  Shut BIRD down.

`graceful restart`

  Shut BIRD down for graceful restart. See graceful restart section for details.

`debug protocol|pattern|all all|off|{ states|routes|filters|events|packets [, ...] }`

  Control protocol debugging.

`dump resources|sockets|ao keys|events|interfaces|neighbors|attributes|attribute stats|routes|protocols "file"`

  Creates the given file (it must not exist) and dumps contents of internal data structures there. By sending SIGUSR1, you get all of these concatenated to `bird.dump` in the current directory. The file is only readable for the user running the daemon. The format of dump files is internal and could change in the future without any notice.

`echo all|off|{ list of log classes } [ buffer-size ]`

  Control echoing of log messages to the command-line output. See log option for a list of log classes.

`eval expr`

  Evaluate given expression.

Next Previous Contents