path: root/bird-openwrt/DOCUMENTATION

---------------------------------------------------------------------

Copyright (C) 2014 - Eloi Carbó Solé (GSoC2014) 
BGP/Bird integration with OpenWRT

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

---------------------------------------------------------------------

*** Original documentation for BIRD Daemon can be found here: http://bird.network.cz/?get_doc
*** Some interesting examples are placed in BIRD daemon Gitlab page: https://gitlab.labs.nic.cz/labs/bird/wikis/home
*** If you want to add new options to bird*-openwrt packages,
*** feel free to make a pull request it in: https://github.com/openwrt-routing/packages/bird-openwrt
*** or email me and ask for it: eloicaso@openmailbox.org

- Options used in /etc/config/birdX -

---------------------------------------------------------------------
CONFIGURATION SECTION 1: 'bird'
---------------------------------------------------------------------

Example 
--
config bird 'bird'
    option use_UCI_config '1'
    option UCI_config_file '/tmp/bird4.conf'
--

* use_UCI_config: Boolean
This option allows you to use UCI configuration translation file instead of the original Bird one. If true/1, birdX init.d script will use the translation placed in "UCI_config_file". Otherwise, it will use the default "/etc/birdX.conf" configuration.
[Hint] This could be used to allow multiple configurations and swap them easily.
Default: 0

* UCI_config_file: String (File path)
This option sets where will be placed the translation of the UCI configuration file. 
Default: /tmp/birdX.conf



---------------------------------------------------------------------
CONFIGURATION SECTION 2: 'global NAME'
---------------------------------------------------------------------

Example
--
config global 'global'
    option log_file '/tmp/bird4.log'
    option log 'all'
    option debug 'off'
    option router_id '172.16.1.6'
--

* log_file: String (File path)
This option sets the path of the file used to save Bird Log and Debug's information.
Default: /tmp/birdX.log

* log: String/Enumeration (all/off, info, warning, error, fatal, debug, trace, remote, auth, bug)
This option allows you to set which information you want to save in the 
[HINT] Use the enumeration like: { info, waning, error }
Default: all

* debug: String/Enumeration ( all/off, states, routes, filters, interfaces, events, packets)
This option allows you to set which debug information will be saved in the "log_file" file.
[HINT] Use the enumeration like: { info, waning, error }
Default: off

* router_id: IP Address
This option sets which will be the Router ID. Usually is the lowest IP address (not loopback) among the existing interfaces.
[HINT] In IPv4 this field is optional. In IPv6 is mandatory.

* listen_bgp_addr: IP Address
This option sets the IP address that Bird BGP instances will listen by default.
Default: 0.0.0.0

* listen_bgp_port: Integer (Port)
This option sets the port that Bird BGP instances will listen by default.
Default: 179

[IPv6 only]
* listen_bgp_dual: Boolean
This option sets if Bird6 BGP instances will listen only to IPv6 or IPv4/6 BGP routes.



---------------------------------------------------------------------
CONFIGURATION SECTION 3: 'table'
---------------------------------------------------------------------

Example
--
config table
    option name 'aux'
--

* name: String
This option allows you to set the name of the auxiliar kernel tables used for Bird.



---------------------------------------------------------------------
CONFIGURATION SECTION 4: 'kernel NAME'
---------------------------------------------------------------------

Example
--
config kernel kernel1
    option table 'aux'
    option import 'all'
    option export 'all'
    option kernel_table '100'
    option scan_time '10'
    option learn '1'
    option persist '0'
    option disabled '0'
--

* table: String
Set an auxiliary table for the current kernel routing instance. This table MUST exist as a SECTION 3 instance.
[HINT] If there is an Kernel protocol instance that uses the "main" kernel table (not using table/kernel_table options), this should be included before the rest of Kernel instances (which will use auxiliary tables).

* import: String/Filter function
This option delimits which routes coming from other protocols will be accepted. This option allows filters in different manners:
1. All/none: allows to import all the routes or none of them.
2. Filter name: [import 'bgp_filter_in'] the protocol will use the filter with the Filter name. (Needs an existing filter declared in the UCI configuration file)

* export: String/Filter function
This option delimits which routes going out from the protocol. This option allows filters in different manners:
1. All/none: allows to export all the routes or none of them.
2. Filter name: [export 'bgp_filter_out'] the protocol will use the filter with the 'Filter name'. (Needs an existing filter declared in the UCI configuration file)

* kernel_table: Integer
This option sets the identification number of the Kernel table that will be used instead of the main one.
Default: main table (254)

* scan_time: Integer
This option sets the time between checks to the selected kernel table.

* learn: Boolean
Set if the kernel table will add the routes from other routing protocols or the system administrator.

* persist: Boolean
Set if Bird Daemon will save the known routes when exiting or if it will clean the routing table.

* disable: Boolean
This option sets if the protocol will be used or dismissed.
Default: 0



---------------------------------------------------------------------
CONFIGURATION SECTION 5: 'device NAME'
---------------------------------------------------------------------

Example
--
config device device1
    option scan_time '10'
    option disabled '0'
--

* scan_time: Integer
This option sets the time between checks to the selected kernel table.

* disable: Boolean
This option sets if the protocol will be used or dismissed.
Default: 0



CONFIGURATION SECTION 6: 'static NAME'

Example
--
config static static1
    option table 'aux'
    option disabled '0'
--

* table: String
Set an auxiliary table for the current static instance. This table MUST exist as a SECTION 3 instance.
[HINT] If there is an static instance that uses the "main" kernel table (not using table/kernel_table options), this should be included before the rest of static instances (which will use auxiliary tables).

* disable: Boolean
This option sets if the protocol will be used or dismissed.
Default: 0



---------------------------------------------------------------------
CONFIGURATION SECTION 7 & 8: 'bgp NAME' & 'bgp_template NAME'
---------------------------------------------------------------------

This section merges two different configuration sections: bgp instances and templates. The first one is the basic bgp configuration part and the second one is the template used to minimize the number of options written in the configuration file. Both configuration sections has the same options, but when Bird found duplicities, the bgp instance has priority over the template.

Examples

-- instance --
config bgp bgp1
    option template 'bgp_common'
    option description 'Description of the BGP instance'
    option neighbor_address '172.16.1.5'
    option neighbor_as '65530'
    option source_address '172.16.1.6'
    option next_hop_self '0'
    option next_hop_keep '0'
    option rr_client '1'
    option rr_cluster_id '172.16.1.6'
--
-- template --
config bgp_template bgp_common
    option table 'aux'
    option import 'all'
    option export 'all'
    option local_address '172.16.1.6'
    option local_as '65001'
    option import_limit '100'
    option import_limit_action 'warn'
    option export_limit '100'
    option export_limit_action 'warn'
    option receive_limit '100'
    option receive_limit_action 'warn'
    option disabled '0'
--

* template: String
This option states the template used for current BGP instance. This template MUST exist as a SECTION 8 instance.

* description: String
This option allows to add a description of the bgp instance and its function

* local_addr: IP address
This optional option allows to set the IP source of our Autonomous System (AS).

* local_as: Integer
This option allows to set the identification number of our AS number. This option is mandatory for each BGP instance.

* neighbor_addr: IP address 
Each BGP instance has a neighbor connected to. This option allows to set its IP address

* neighbor_as: Integer
Each BGP instance has a neighbor connected to. This option allows to set its AS ID.

* next_hop_self: Boolean
If this option is true, BGP protocol will avoid to calculate the next hop and always advertise own "Router id" IP .
Default: 0

* next_hop_keep: Boolean
If this option is true, BGP will always use the received next_hop information to redirect the route.
Default: 0

* rr_client: Boolean
IF this option is true, the router will be set as Route Reflector and will treat the rest of the routers as RR clients.
Default: 0

* rr_cluster_id: Integer
This option sets the identification number of the RR cluster. All the nodes in a cluster needs this option and share the same number.
Default: Router id

* import_limit: Integer
This option sets the limit of routes that a protocol can import until take the action indicated in the import_limit_action.
import_limit also counts filtered routes (even dropped).
Default: 0 (no limit)

* import_limit_action: String
This option allows to decide the action to take when reached the limit of imported routes.
Actions are: warn, block, restart, disable

* export_limit: Integer
This option sets the limit of routes that a protocol can export until take the action indicated in the export_limit_action.
Default: 0 (no limit)

* export_limit_action: String
This option allows to decide the action to take when reached the limit of exported routes.
Actions are: warn, block, restart, disable

* receive_limit: Integer
This option sets the limit of routes that a protocol can receive until take the action indicated in the receive_limit_action. receive_limit only counts accepted routes from the protocol.
Default: 0 (no limit)

* receive_limit_action: String
This option allows to decide the action to take when reached the limit of received routes.
Actions are: warn, block, restart, disable

* disable: Boolean
This option sets if the protocol will be used or dismissed.
Default: 0



---------------------------------------------------------------------
CONFIGURATION SECTION 9: 'route' 
---------------------------------------------------------------------

Example
--
config route
    option instance 'static1'
    option type 'router'
    option prefix '192.168.9.0/24'
    option via '10.99.105.159'

config route
    option instance 'static1'
    option type 'special'
    option prefix '192.168.2.0/24'
    option attribute 'unreachable'

config route
    option instance 'static1'
    option type 'iface'
    option prefix '192.168.3.0/24'
    option iface 'mgmt0'

config route
    option instance 'static1'
    option type 'recursive'
    option prefix '192.168.4.0/24'
    option ip '192.168.1.1'

config route
    option instance 'static1'
    option type 'multipath'
    option prefix '192.168.30.0/24'
    list l_via '172.16.1.5'
    list l_via '172.16.1.6'
--

* instance: String
This option indicates the route that the static protocol instance will apply.

* type: String
This option states the type of route that will be applied. Also defines the options available for it.
Types are: 'router', 'special', 'iface', 'recursive' or 'multipath'.

* prefix: IP address/network
This option allows to define the network that you want to define.

[router only]
* via: IP Address
This option indicates the IP address of the neighbor router where the routes will pass through.

[special only]
* attribute: String
This option will mark the behaviour of the route.
Attribures are: 'blackhole', 'unreachable' or 'prohibit'.

[iface only]
* iface: String
This option indicates the interface used to redirect the BGP routes. Careful, the interface MUST exist, or Bird will fail to start.

[recursive only]
* ip: IP address
This option states the IP address which the next hop will depend on.

[multipath only][This is a list, not an option. Use it as in the example, or check the UCI configuration documentation.]
* l_via: IP address
This list of IPs specifies the list (following the sequence) of routers that the route will follow as next hops.



---------------------------------------------------------------------
CONFIGURATION SECTION 10: 'filter NAME' 
---------------------------------------------------------------------

Filters are written in separated files. Its syntax can be found in http://bird.network.cz/?get_doc&f=bird-5.html
The content of each filter file is copied in the birdX.conf file without checking its syntax.

Example
--
config filter 'firstFilter'
    option type 'bgp'
    option instance 'bgp1'
    option file_path '/var/filters/f1'
--

* type: String
The type indicates to which routing protocol is the filter directed to. Currently only BGP is available.

* instance: String
This option indicates the filter that the routing protocol instance will apply.

* file_path: String (File path)
This option specifies the path to the filter file to be used in the routing protocol.



---------------------------------------------------------------------
COMPLETE CONFIGURATION EXAMPLE:
---------------------------------------------------------------------

config bird 'bird'
    option use_UCI_config '1'
        #Caution! Enabling this option, Bird will translate this
        #UCI file and use it instead of /etc/bird4.conf
    option UCI_config_file '/tmp/bird4.conf'
        #If you enable useUCIconfig, UCIconfigFile will be Bird's
        #configuration file location.

config global 'global'
    option log_file '/tmp/bird4.log'
    option log 'all'
    option debug 'off'
    option router_id '172.16.1.6'

config table
    option name 'aux'
    
config kernel kernel1
    option table 'aux'
    option import 'all'
    option export 'all'
    option kernel_table '100'
    option scan_time '10'
    option learn '1'
    option persist '0'
    option disabled '0'

config device device1
    option scan_time '10'
    option disabled '0'

config static static1
    option table 'aux'
    option disabled '0'

config bgp bgp1
    option template 'bgp_common'
    option description 'Description of the BGP instance'
    option neighbor_address '172.16.1.5'
    option neighbor_as '65530'
    option source_address '172.16.1.6'
    option next_hop_self '0'
    option next_hop_keep '0'
    option rr_client '1'
    option rr_cluster_id '172.16.1.6'

config bgp_template bgp_common
    option table 'aux'
    option import 'all'
    option export 'all'
    option local_address '172.16.1.6'
    option local_as '65001'
    option import_limit '100'
    option import_limit_action 'warn'
    option export_limit '100'
    option export_limit_action 'warn'
    option receive_limit '100'
    option receive_limit_action 'warn'
    option disabled '0'

#config ospf ospf1
#    option cfg1583compat '1'
#
#config ospf_area '0.0.0.0'
#    option instance 'ospf1'
#    option stub '0'
#
#config ospf_interface '*'
#    option area '0.0.0.0'
#    option cost '100'
#    option type 'broadcast'
#    option hello '5'
#    option password '1'
#
#config ospf_password '1'
#    option authentication 'cryptographic'
#    option passphrase '1234'
#
#config ospf_networks
#    option area '0.0.0.0'
#    list prefix '10.0.0.0/24'
#
#config ospf_hidden_networks
#    option area '0.0.0.0'
#    option prefix '12.0.0.0/24'
#
#config ospf_stubnet '11.0.0.0/24'
#    option area '0.0.0.0'
#    option hidden '0'
#    option summary '0'
#    option cost '101'
#

config route
    option instance 'static1'
    option type 'router'
    option prefix '192.168.9.0/24'
    option via '10.99.105.159'

config route
    option instance 'static1'
    option type 'special'
    option prefix '192.168.2.0/24'
    option attribute 'unreachable'

config route
    option instance 'static1'
    option type 'iface'
    option prefix '192.168.3.0/24'
    option iface 'mgmt0'

config route
    option instance 'static1'
    option type 'recursive'
    option prefix '192.168.4.0/24'
    option ip '192.168.1.1'

config route
    option instance 'static1'
    option type 'multipath'
    option prefix '192.168.30.0/24'
    list l_via '172.16.1.5'
    list l_via '172.16.1.6'

config filter 'firstFilter'
    option type 'bgp'
    option instance 'bgp1'
    option file_path '/var/filters/f1'