bird-openwrt/DOCUMENTATION

   1 ---------------------------------------------------------------------
   2
   3 Copyright (C) 2014 - Eloi Carbó Solé (GSoC2014)
   4 BGP/Bird integration with OpenWRT
   5
   6 This program is free software: you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation, either version 3 of the License, or
   9 (at your option) any later version.
  10
  11 This program is distributed in the hope that it will be useful,
  12 but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 GNU General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 ---------------------------------------------------------------------
  20
  21 *** Original documentation for BIRD Daemon can be found here: http://bird.network.cz/?get_doc
  22 *** Some interesting examples are placed in BIRD daemon Gitlab page: https://gitlab.labs.nic.cz/labs/bird/wikis/home
  23 *** If you want to add new options to bird*-openwrt packages,
  24 *** feel free to make a pull request it in: https://github.com/openwrt-routing/packages/bird-openwrt
  25 *** or email me and ask for it: eloicaso@openmailbox.org
  26
  27 - Options used in /etc/config/birdX -
  28
  29 ---------------------------------------------------------------------
  30 CONFIGURATION SECTION 1: 'bird'
  31 ---------------------------------------------------------------------
  32
  33 Example
  34 --
  35 config bird 'bird'
  36     option use_UCI_config '1'
  37     option UCI_config_file '/tmp/bird4.conf'
  38 --
  39
  40 * use_UCI_config: Boolean
  41 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.
  42 [Hint] This could be used to allow multiple configurations and swap them easily.
  43 Default: 0
  44
  45 * UCI_config_file: String (File path)
  46 This option sets where will be placed the translation of the UCI configuration file.
  47 Default: /tmp/birdX.conf
  48
  49
  50
  51 ---------------------------------------------------------------------
  52 CONFIGURATION SECTION 2: 'global NAME'
  53 ---------------------------------------------------------------------
  54
  55 Example
  56 --
  57 config global 'global'
  58     option log_file '/tmp/bird4.log'
  59     option log 'all'
  60     option debug 'off'
  61     option router_id '172.16.1.6'
  62 --
  63
  64 * log_file: String (File path)
  65 This option sets the path of the file used to save Bird Log and Debug's information.
  66 Default: /tmp/birdX.log
  67
  68 * log: String/Enumeration (all/off, info, warning, error, fatal, debug, trace, remote, auth, bug)
  69 This option allows you to set which information you want to save in the
  70 [HINT] Use the enumeration like: { info, waning, error }
  71 Default: all
  72
  73 * debug: String/Enumeration ( all/off, states, routes, filters, interfaces, events, packets)
  74 This option allows you to set which debug information will be saved in the "log_file" file.
  75 [HINT] Use the enumeration like: { info, waning, error }
  76 Default: off
  77
  78 * router_id: IP Address
  79 This option sets which will be the Router ID. Usually is the lowest IP address (not loopback) among the existing interfaces.
  80 [HINT] In IPv4 this field is optional. In IPv6 is mandatory.
  81
  82 * listen_bgp_addr: IP Address
  83 This option sets the IP address that Bird BGP instances will listen by default.
  84 Default: 0.0.0.0
  85
  86 * listen_bgp_port: Integer (Port)
  87 This option sets the port that Bird BGP instances will listen by default.
  88 Default: 179
  89
  90 [IPv6 only]
  91 * listen_bgp_dual: Boolean
  92 This option sets if Bird6 BGP instances will listen only to IPv6 or IPv4/6 BGP routes.
  93
  94
  95
  96 ---------------------------------------------------------------------
  97 CONFIGURATION SECTION 3: 'table'
  98 ---------------------------------------------------------------------
  99
 100 Example
 101 --
 102 config table
 103     option name 'aux'
 104 --
 105
 106 * name: String
 107 This option allows you to set the name of the auxiliar kernel tables used for Bird.
 108
 109
 110
 111 ---------------------------------------------------------------------
 112 CONFIGURATION SECTION 4: 'kernel NAME'
 113 ---------------------------------------------------------------------
 114
 115 Example
 116 --
 117 config kernel kernel1
 118     option table 'aux'
 119     option import 'all'
 120     option export 'all'
 121     option kernel_table '100'
 122     option scan_time '10'
 123     option learn '1'
 124     option persist '0'
 125     option disabled '0'
 126 --
 127
 128 * table: String
 129 Set an auxiliary table for the current kernel routing instance. This table MUST exist as a SECTION 3 instance.
 130 [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).
 131
 132 * import: String/Filter function
 133 This option delimits which routes coming from other protocols will be accepted. This option allows filters in different manners:
 134 1. All/none: allows to import all the routes or none of them.
 135 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)
 136
 137 * export: String/Filter function
 138 This option delimits which routes going out from the protocol. This option allows filters in different manners:
 139 1. All/none: allows to export all the routes or none of them.
 140 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)
 141
 142 * kernel_table: Integer
 143 This option sets the identification number of the Kernel table that will be used instead of the main one.
 144 Default: main table (254)
 145
 146 * scan_time: Integer
 147 This option sets the time between checks to the selected kernel table.
 148
 149 * learn: Boolean
 150 Set if the kernel table will add the routes from other routing protocols or the system administrator.
 151
 152 * persist: Boolean
 153 Set if Bird Daemon will save the known routes when exiting or if it will clean the routing table.
 154
 155 * disable: Boolean
 156 This option sets if the protocol will be used or dismissed.
 157 Default: 0
 158
 159
 160
 161 ---------------------------------------------------------------------
 162 CONFIGURATION SECTION 5: 'device NAME'
 163 ---------------------------------------------------------------------
 164
 165 Example
 166 --
 167 config device device1
 168     option scan_time '10'
 169     option disabled '0'
 170 --
 171
 172 * scan_time: Integer
 173 This option sets the time between checks to the selected kernel table.
 174
 175 * disable: Boolean
 176 This option sets if the protocol will be used or dismissed.
 177 Default: 0
 178
 179
 180
 181 CONFIGURATION SECTION 6: 'static NAME'
 182
 183 Example
 184 --
 185 config static static1
 186     option table 'aux'
 187     option disabled '0'
 188 --
 189
 190 * table: String
 191 Set an auxiliary table for the current static instance. This table MUST exist as a SECTION 3 instance.
 192 [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).
 193
 194 * disable: Boolean
 195 This option sets if the protocol will be used or dismissed.
 196 Default: 0
 197
 198
 199
 200 ---------------------------------------------------------------------
 201 CONFIGURATION SECTION 7 & 8: 'bgp NAME' & 'bgp_template NAME'
 202 ---------------------------------------------------------------------
 203
 204 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.
 205
 206 Examples
 207
 208 -- instance --
 209 config bgp bgp1
 210     option template 'bgp_common'
 211     option description 'Description of the BGP instance'
 212     option neighbor_address '172.16.1.5'
 213     option neighbor_as '65530'
 214     option source_address '172.16.1.6'
 215     option next_hop_self '0'
 216     option next_hop_keep '0'
 217     option rr_client '1'
 218     option rr_cluster_id '172.16.1.6'
 219 --
 220 -- template --
 221 config bgp_template bgp_common
 222     option table 'aux'
 223     option import 'all'
 224     option export 'all'
 225     option local_address '172.16.1.6'
 226     option local_as '65001'
 227     option import_limit '100'
 228     option import_limit_action 'warn'
 229     option export_limit '100'
 230     option export_limit_action 'warn'
 231     option receive_limit '100'
 232     option receive_limit_action 'warn'
 233     option disabled '0'
 234 --
 235
 236 * template: String
 237 This option states the template used for current BGP instance. This template MUST exist as a SECTION 8 instance.
 238
 239 * description: String
 240 This option allows to add a description of the bgp instance and its function
 241
 242 * local_addr: IP address
 243 This optional option allows to set the IP source of our Autonomous System (AS).
 244
 245 * local_as: Integer
 246 This option allows to set the identification number of our AS number. This option is mandatory for each BGP instance.
 247
 248 * neighbor_addr: IP address
 249 Each BGP instance has a neighbor connected to. This option allows to set its IP address
 250
 251 * neighbor_as: Integer
 252 Each BGP instance has a neighbor connected to. This option allows to set its AS ID.
 253
 254 * next_hop_self: Boolean
 255 If this option is true, BGP protocol will avoid to calculate the next hop and always advertise own "Router id" IP .
 256 Default: 0
 257
 258 * next_hop_keep: Boolean
 259 If this option is true, BGP will always use the received next_hop information to redirect the route.
 260 Default: 0
 261
 262 * rr_client: Boolean
 263 IF this option is true, the router will be set as Route Reflector and will treat the rest of the routers as RR clients.
 264 Default: 0
 265
 266 * rr_cluster_id: Integer
 267 This option sets the identification number of the RR cluster. All the nodes in a cluster needs this option and share the same number.
 268 Default: Router id
 269
 270 * import_limit: Integer
 271 This option sets the limit of routes that a protocol can import until take the action indicated in the import_limit_action.
 272 import_limit also counts filtered routes (even dropped).
 273 Default: 0 (no limit)
 274
 275 * import_limit_action: String
 276 This option allows to decide the action to take when reached the limit of imported routes.
 277 Actions are: warn, block, restart, disable
 278
 279 * export_limit: Integer
 280 This option sets the limit of routes that a protocol can export until take the action indicated in the export_limit_action.
 281 Default: 0 (no limit)
 282
 283 * export_limit_action: String
 284 This option allows to decide the action to take when reached the limit of exported routes.
 285 Actions are: warn, block, restart, disable
 286
 287 * receive_limit: Integer
 288 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.
 289 Default: 0 (no limit)
 290
 291 * receive_limit_action: String
 292 This option allows to decide the action to take when reached the limit of received routes.
 293 Actions are: warn, block, restart, disable
 294
 295 * disable: Boolean
 296 This option sets if the protocol will be used or dismissed.
 297 Default: 0
 298
 299
 300
 301 ---------------------------------------------------------------------
 302 CONFIGURATION SECTION 9: 'route'
 303 ---------------------------------------------------------------------
 304
 305 Example
 306 --
 307 config route
 308     option instance 'static1'
 309     option type 'router'
 310     option prefix '192.168.9.0/24'
 311     option via '10.99.105.159'
 312
 313 config route
 314     option instance 'static1'
 315     option type 'special'
 316     option prefix '192.168.2.0/24'
 317     option attribute 'unreachable'
 318
 319 config route
 320     option instance 'static1'
 321     option type 'iface'
 322     option prefix '192.168.3.0/24'
 323     option iface 'mgmt0'
 324
 325 config route
 326     option instance 'static1'
 327     option type 'recursive'
 328     option prefix '192.168.4.0/24'
 329     option ip '192.168.1.1'
 330
 331 config route
 332     option instance 'static1'
 333     option type 'multipath'
 334     option prefix '192.168.30.0/24'
 335     list l_via '172.16.1.5'
 336     list l_via '172.16.1.6'
 337 --
 338
 339 * instance: String
 340 This option indicates the route that the static protocol instance will apply.
 341
 342 * type: String
 343 This option states the type of route that will be applied. Also defines the options available for it.
 344 Types are: 'router', 'special', 'iface', 'recursive' or 'multipath'.
 345
 346 * prefix: IP address/network
 347 This option allows to define the network that you want to define.
 348
 349 [router only]
 350 * via: IP Address
 351 This option indicates the IP address of the neighbor router where the routes will pass through.
 352
 353 [special only]
 354 * attribute: String
 355 This option will mark the behaviour of the route.
 356 Attribures are: 'blackhole', 'unreachable' or 'prohibit'.
 357
 358 [iface only]
 359 * iface: String
 360 This option indicates the interface used to redirect the BGP routes. Careful, the interface MUST exist, or Bird will fail to start.
 361
 362 [recursive only]
 363 * ip: IP address
 364 This option states the IP address which the next hop will depend on.
 365
 366 [multipath only][This is a list, not an option. Use it as in the example, or check the UCI configuration documentation.]
 367 * l_via: IP address
 368 This list of IPs specifies the list (following the sequence) of routers that the route will follow as next hops.
 369
 370
 371
 372 ---------------------------------------------------------------------
 373 CONFIGURATION SECTION 10: 'filter NAME'
 374 ---------------------------------------------------------------------
 375
 376 Filters are written in separated files. Its syntax can be found in http://bird.network.cz/?get_doc&f=bird-5.html
 377 The content of each filter file is copied in the birdX.conf file without checking its syntax.
 378
 379 Example
 380 --
 381 config filter 'firstFilter'
 382     option type 'bgp'
 383     option instance 'bgp1'
 384     option file_path '/var/filters/f1'
 385 --
 386
 387 * type: String
 388 The type indicates to which routing protocol is the filter directed to. Currently only BGP is available.
 389
 390 * instance: String
 391 This option indicates the filter that the routing protocol instance will apply.
 392
 393 * file_path: String (File path)
 394 This option specifies the path to the filter file to be used in the routing protocol.
 395
 396
 397
 398 ---------------------------------------------------------------------
 399 COMPLETE CONFIGURATION EXAMPLE:
 400 ---------------------------------------------------------------------
 401
 402 config bird 'bird'
 403     option use_UCI_config '1'
 404         #Caution! Enabling this option, Bird will translate this
 405         #UCI file and use it instead of /etc/bird4.conf
 406     option UCI_config_file '/tmp/bird4.conf'
 407         #If you enable useUCIconfig, UCIconfigFile will be Bird's
 408         #configuration file location.
 409
 410 config global 'global'
 411     option log_file '/tmp/bird4.log'
 412     option log 'all'
 413     option debug 'off'
 414     option router_id '172.16.1.6'
 415
 416 config table
 417     option name 'aux'
 418
 419 config kernel kernel1
 420     option table 'aux'
 421     option import 'all'
 422     option export 'all'
 423     option kernel_table '100'
 424     option scan_time '10'
 425     option learn '1'
 426     option persist '0'
 427     option disabled '0'
 428
 429 config device device1
 430     option scan_time '10'
 431     option disabled '0'
 432
 433 config static static1
 434     option table 'aux'
 435     option disabled '0'
 436
 437 config bgp bgp1
 438     option template 'bgp_common'
 439     option description 'Description of the BGP instance'
 440     option neighbor_address '172.16.1.5'
 441     option neighbor_as '65530'
 442     option source_address '172.16.1.6'
 443     option next_hop_self '0'
 444     option next_hop_keep '0'
 445     option rr_client '1'
 446     option rr_cluster_id '172.16.1.6'
 447
 448 config bgp_template bgp_common
 449     option table 'aux'
 450     option import 'all'
 451     option export 'all'
 452     option local_address '172.16.1.6'
 453     option local_as '65001'
 454     option import_limit '100'
 455     option import_limit_action 'warn'
 456     option export_limit '100'
 457     option export_limit_action 'warn'
 458     option receive_limit '100'
 459     option receive_limit_action 'warn'
 460     option disabled '0'
 461
 462 #config ospf ospf1
 463 #    option cfg1583compat '1'
 464 #
 465 #config ospf_area '0.0.0.0'
 466 #    option instance 'ospf1'
 467 #    option stub '0'
 468 #
 469 #config ospf_interface '*'
 470 #    option area '0.0.0.0'
 471 #    option cost '100'
 472 #    option type 'broadcast'
 473 #    option hello '5'
 474 #    option password '1'
 475 #
 476 #config ospf_password '1'
 477 #    option authentication 'cryptographic'
 478 #    option passphrase '1234'
 479 #
 480 #config ospf_networks
 481 #    option area '0.0.0.0'
 482 #    list prefix '10.0.0.0/24'
 483 #
 484 #config ospf_hidden_networks
 485 #    option area '0.0.0.0'
 486 #    option prefix '12.0.0.0/24'
 487 #
 488 #config ospf_stubnet '11.0.0.0/24'
 489 #    option area '0.0.0.0'
 490 #    option hidden '0'
 491 #    option summary '0'
 492 #    option cost '101'
 493 #
 494
 495 config route
 496     option instance 'static1'
 497     option type 'router'
 498     option prefix '192.168.9.0/24'
 499     option via '10.99.105.159'
 500
 501 config route
 502     option instance 'static1'
 503     option type 'special'
 504     option prefix '192.168.2.0/24'
 505     option attribute 'unreachable'
 506
 507 config route
 508     option instance 'static1'
 509     option type 'iface'
 510     option prefix '192.168.3.0/24'
 511     option iface 'mgmt0'
 512
 513 config route
 514     option instance 'static1'
 515     option type 'recursive'
 516     option prefix '192.168.4.0/24'
 517     option ip '192.168.1.1'
 518
 519 config route
 520     option instance 'static1'
 521     option type 'multipath'
 522     option prefix '192.168.30.0/24'
 523     list l_via '172.16.1.5'
 524     list l_via '172.16.1.6'
 525
 526 config filter 'firstFilter'
 527     option type 'bgp'
 528     option instance 'bgp1'
 529     option file_path '/var/filters/f1'
 530
 531