bird1-openwrt/UCI-DOCUMENTATION.md

   1 <!--
   2 ---------------------------------------------------------------------
   3 (C) 2014 - 2017 Eloi Carbo <eloicaso@openmailbox.org>
   4
   5 This program is free software: you can redistribute it and/or modify
   6 it under the terms of the GNU General Public License as published by
   7 the Free Software Foundation, either version 3 of the License, or
   8 (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU General Public License for more details.
  14
  15 You should have received a copy of the GNU General Public License
  16 along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 ---------------------------------------------------------------------
  18 -->
  19
  20 # Bird{4|6} UCI Packages Documentation
  21 *  BIRD Daemon's original documentation: http://bird.network.cz/?get_doc
  22 * Usage examples (Gitlab): https://gitlab.labs.nic.cz/labs/bird/wikis/home
  23 * Extra documentation in English & Catalan: https://github.com/eloicaso/bgp-bmx6-bird-docn
  24 * If you want to add new options to bird*-openwrt packages add a pull request or issue in: https://github.com/eloicaso/bird-openwrt
  25
  26 ### Options used in /etc/config/bird{4|6}
  27 > *Clarification*: Any reference to **{4|6}** in this document means that it applies to both Bird4 and Bird6 packages and configurations. Otherwise, the text will clarify which specific package is affected by it.
  28
  29 #### CONFIGURATION SECTION 1: 'bird'
  30 Usage example :
  31 ``` Bash
  32 config bird 'bird'
  33     option use_UCI_config '1'
  34     option UCI_config_file '/tmp/bird4.conf'
  35 ```
  36
  37 * **use_UCI_config**: *Boolean*
  38 This option allows you to use package's UCI configuration translation instead of using the original Bird config file (hand-edited). 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.
  39 **\[HINT**\] This could be used to allow multiple configurations and swap them easily.
  40 *Default: 0*
  41
  42 * **UCI_config_file**: *String* File_path
  43 This option sets where will be placed the translation of the UCI configuration file.
  44 *Default: /tmp/birdX.conf*
  45
  46
  47 #### CONFIGURATION SECTION 2: 'global NAME'
  48 Usage example:
  49 ```Bash
  50 config global 'global'
  51     option log_file '/tmp/bird4.log'
  52     option log 'all'
  53     option debug 'off'
  54     option router_id '172.16.1.6'
  55 ```
  56
  57 * **log_file**: *String* File_path
  58 This option sets the path of the file used to save Bird Log and Debug's information.
  59 *Default: /tmp/bird{4|6}.log*
  60
  61 * **log**: *String/Enumeration* (all/off, info, warning, error, fatal, debug, trace, remote, auth, bug)
  62 This option allows you to set which information you want to save in the Log file.
  63 **\[HINT\]** Use the enumeration like: { info, waning, error }. Do not enter any extra option if you select "all" (Bird will fail to start).
  64 *Default: all*
  65
  66 * **debug**: *String/Enumeration* ( all/off, states, routes, filters, interfaces, events, packets)
  67 This option allows you to set which **extra** debug information will be saved in the "log_file" file.
  68 **\[HINT\]** Use the enumeration like: { info, waning, error }. Do not enter any extra option if you select "all" (Bird will fail to start).
  69 *Default: off*
  70
  71 * **router_id**: IP Address
  72 This option sets which will be the Router ID.
  73 **\[HINT\]** In **Bird4** this field is the lowest IP address (not loopback) among the existing interfaces by default (Optional property).
  74 In **Bird6** there is no default value and it is mandatory.
  75
  76 * **listen_bgp_addr**: IP Address
  77 This option sets the IP address that Bird BGP instances will listen by default.
  78 *Default: 0.0.0.0*
  79
  80 * **listen_bgp_port**: *Integer* Port
  81 This option sets the port that Bird BGP instances will listen by default.
  82 *Default: IP 0.0.0.0 and Port 179*
  83
  84 * **listen_bgp_dual**: *Boolean*
  85 **\[Bird6\]** This option configures Bird6 BGP instances to listen only IPv6 or IPv4/6 BGP routes.
  86
  87
  88 #### <a name="table"></a>CONFIGURATION SECTION 3: 'table'
  89 Usage example:
  90 ``` Bash
  91 config table
  92     option name 'aux'
  93 ```
  94
  95 * **name**: *String*
  96 This option allows you to set the name of the auxiliar kernel tables used for Bird. This option is mandatory for most of the protocols.
  97
  98
  99 #### CONFIGURATION SECTION 4: 'kernel NAME'
 100 Usage example:
 101 ``` Bash
 102 config kernel kernel1
 103     option table 'aux'
 104     option import 'all'
 105     option export 'all'
 106     option kernel_table '100'
 107     option scan_time '10'
 108     option learn '1'
 109     option persist '0'
 110     option disabled '0'
 111 ```
 112
 113 * **table**: *String*
 114 Set an auxiliary table for the current kernel routing instance. This table **MUST** exist as a [table](#table) instance.
 115 **\[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).
 116
 117 * **import**: *String/Filter* function
 118 This option delimits which routes coming from other protocols will be accepted.
 119 Options are:
 120 **All/none**: allows to import all the routes or none of them.
 121 **Filter name**: \[import 'bgp_filter_in'\] the protocol will use the filter with the given name (Specified filter **must** exists in any file under /etc/bird{4|6}/filters/ folder).
 122
 123 * export: String/Filter function
 124 This option delimits which routes going out from the protocol. This option allows filters in different manners:
 125 **All/none**: allows to export all the routes or none of them.
 126 **Filter name**: \[export 'bgp_filter_out'\] the protocol will use the filter with the given name(Specified filter **must** exists in any file under /etc/bird{4|6}/filters/ folder).
 127
 128 * **kernel_table**: *Integer*
 129 This option sets the identification number of the Kernel table that will be used instead of the main one.
 130 *Default: main table (254)*
 131
 132 * **scan_time**: *Integer*
 133 This option sets the time between checks to target kernel table.
 134
 135 * **learn**: *Boolean*
 136 Set if kernel table will add the routes from other routing protocols or the system administrator.
 137
 138 * **persist**: *Boolean*
 139 Set if Bird Daemon will save the known routes when exiting or if it will clean the routing table.
 140
 141 * **disable**: *Boolean*
 142 This option sets if the protocol will be used or dismissed.
 143 *Default: 0*
 144
 145
 146 #### CONFIGURATION SECTION 5: 'device NAME'
 147 Usage example:
 148 ``` Bash
 149 config device device1
 150     option scan_time '10'
 151     option disabled '0'
 152 ```
 153
 154 * **scan_time***: *Integer*
 155 This option sets the time between checks to the selected kernel table.
 156
 157 * **disable**: *Boolean*
 158 This option sets if the protocol will be used or dismissed.
 159 *Default: 0*
 160
 161
 162 #### CONFIGURATION SECTION 6: 'static NAME'
 163 Usage example:
 164 ``` Bash
 165 config static static1
 166     option table 'aux'
 167     option disabled '0'
 168 ```
 169
 170 * **table**: *String*
 171 Set an auxiliary table for the current static instance. This table **MUST** exist as a [table](#table) instance.
 172 **\[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).
 173
 174 * **disable**: *Boolean*
 175 This option sets if the protocol will be used or dismissed.
 176 *Default: 0*
 177
 178
 179 #### CONFIGURATION SECTION 7 & 8: 'bgp NAME' & 'bgp_template NAME'
 180 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 for each unique instance. Both configuration sections have the same options but, when Bird finds duplicities, the instance will overwrite the template options.
 181
 182 Usage examples:
 183 ``` Bash
 184 # instance
 185 config bgp bgp1
 186     option template 'bgp_common'
 187     option description 'Description of the BGP instance'
 188     option neighbor_address '172.16.1.5'
 189     option neighbor_as '65530'
 190     option source_address '172.16.1.6'
 191     option next_hop_self '0'
 192     option next_hop_keep '0'
 193     option rr_client '1'
 194     option rr_cluster_id '172.16.1.6'
 195 ```
 196
 197 ``` Bash
 198 # template
 199 config bgp_template bgp_common
 200     option table 'aux'
 201     option import 'all'
 202     option export 'all'
 203     option local_address '172.16.1.6'
 204     option local_as '65001'
 205     option import_limit '100'
 206     option import_limit_action 'warn'
 207     option export_limit '100'
 208     option export_limit_action 'warn'
 209     option receive_limit '100'
 210     option receive_limit_action 'warn'
 211     option disabled '0'
 212 ```
 213
 214 * **template**: *String*
 215 This option states the template used for current BGP instance. This template MUST exist.
 216
 217 * **description**: *String*
 218 This option allows to add a description of the bgp instance and its function.
 219
 220 * **local_addr**: IP address
 221 This option allows to set the IP source of our Autonomous System (AS).
 222
 223 * **local_as**: *Integer*
 224 This option allows to set the identification number of our AS number. This option is mandatory for each BGP instance.
 225
 226 * **neighbor_addr**: IP address
 227 Each BGP instance has a neighbor connected to. This option allows to set its IP address.
 228
 229 * **neighbor_as**: *Integer*
 230 Each BGP instance has a neighbor connected to. This option allows to set its AS ID.
 231
 232 * **next_hop_self**: *Boolean*
 233 If this option is true, BGP protocol will avoid to calculate the next hop and always advertise own "Router id" IP.
 234 *Default: 0*
 235
 236 * **next_hop_keep**: *Boolean*
 237 If this option is true, BGP will always use the received next_hop information to redirect the route.
 238 *Default: 0*
 239
 240 * **rr_client**: *Boolean*
 241 IF this option is true, the router will be set as Route Reflector and will treat the rest of the routers as RR clients.
 242 *Default: 0*
 243
 244 * **rr_cluster_id**: *Integer*
 245 This option sets the identification number of the RR cluster. All the nodes in a cluster needs this option and share the same number.
 246 *Default: Router id*
 247
 248 * **import_limit**: *Integer*
 249 This option sets the limit of routes that a protocol can import until take the action indicated in the import_limit_action.
 250 import_limit also counts filtered routes (even dropped ones).
 251 *Default: 0 (no limit)*
 252
 253 * **import_limit_action**: *String*
 254 This option allows to decide the action to take when reached the limit of imported routes.
 255 Actions are: warn, block, restart, disable
 256
 257 * **export_limit**: *Integer*
 258 This option sets the limit of routes that a protocol can export until take the action indicated in the export_limit_action.
 259 *Default: 0 (no limit)*
 260
 261 * **export_limit_action**: *String*
 262 This option allows to decide the action to take when reached the limit of exported routes.
 263 Actions are: warn, block, restart, disable
 264
 265 * **receive_limit**: *Integer*
 266 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.
 267 *Default: 0 (no limit)*
 268
 269 * **receive_limit_action**: *String*
 270 This option allows to decide the action to take when reached the limit of received routes.
 271 Actions are: warn, block, restart, disable
 272
 273 * **disable**: *Boolean*
 274 This option sets if the protocol will be used or dismissed.
 275 *Default: 0*
 276
 277
 278 #### CONFIGURATION SECTION 9: 'route'
 279 Usage example:
 280 ``` Bash
 281 config route
 282     option instance 'static1'
 283     option type 'router'
 284     option prefix '192.168.9.0/24'
 285     option via '10.99.105.159'
 286
 287 config route
 288     option instance 'static1'
 289     option type 'special'
 290     option prefix '192.168.2.0/24'
 291     option attribute 'unreachable'
 292
 293 config route
 294     option instance 'static1'
 295     option type 'iface'
 296     option prefix '192.168.3.0/24'
 297     option iface 'mgmt0'
 298
 299 config route
 300     option instance 'static1'
 301     option type 'recursive'
 302     option prefix '192.168.4.0/24'
 303     option ip '192.168.1.1'
 304
 305 config route
 306     option instance 'static1'
 307     option type 'multipath'
 308     option prefix '192.168.30.0/24'
 309     list l_via '172.16.1.5'
 310     list l_via '172.16.1.6'
 311 ```
 312
 313 * **instance**: *String*
 314 This option indicates the route that the static protocol instance will apply.
 315
 316 * **type**: *String*
 317 This option states the type of route that will be applied. Also defines the options available for it.
 318 Types are: 'router', 'special', 'iface', 'recursive' or 'multipath'.
 319
 320 * **prefix**: IP address/network
 321 This option allows to define the network that you want to define.
 322 **\[router only\]**
 323 **via**: IP Address
 324 This option indicates the IP address of the neighbor router where the routes will pass through.
 325 **\[special only\]**
 326 **attribute**: *String*
 327 This option will mark the behaviour of the route.
 328 Attribures are: 'blackhole', 'unreachable' or 'prohibit'.
 329 **\[iface only\]**
 330 **iface**: *String*
 331 This option indicates the interface used to redirect the BGP routes. Careful, the interface MUST exist, or Bird will fail to start.
 332 **\[recursive only\]**
 333 **ip**: IP address
 334 This option states the IP address which the next hop will depend on.
 335 **\[multipath only\]**
 336 This is a list, not an option. Use it as in the example, or check the UCI configuration documentation.
 337 **l_via**: IP address
 338 This list of IPs specifies the list (following the sequence) of routers that the route will follow as next hops.
 339
 340
 341 #### CONFIGURATION SECTION 10 & 11: 'filter NAME' & 'function Name'
 342 Filters are written in separated files under **/etc/bird{4|6}/filters/** and **/etc/bird{4|6}/functions/**. Their syntax can be found [here.](http://bird.network.cz/?get_doc&f=bird-5.html)
 343 The content of each filter and file file will be included in the resulting bird{4|6}.conf file without checking its syntax, so you could find errors during start time.
 344
 345 * Clarification for any existing **v0.2** user: an automated upgrade path has been added to switch your old "filter" or "function" sections. It is safe to upgrade, but doing regular backups of your key files is always a good practise to avoid frustration.