Merge pull request #332 from ecsv/batadv-2017.4
[feed/routing.git] / 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