[bird-openwrt] Add documentation file. Remove OSPF and filters configuration examples...
authorPau Escrich <p4u@dabax.net>
Thu, 20 Nov 2014 17:13:43 +0000 (18:13 +0100)
committerPau Escrich <p4u@dabax.net>
Thu, 20 Nov 2014 17:13:43 +0000 (18:13 +0100)
Signed-off-by: Pau Escrich <p4u@dabax.net>
bird-openwrt/DOCUMENTATION [new file with mode: 0644]
bird-openwrt/bird4-openwrt/src/config/bird4
bird-openwrt/bird6-openwrt/src/config/bird6

diff --git a/bird-openwrt/DOCUMENTATION b/bird-openwrt/DOCUMENTATION
new file mode 100644 (file)
index 0000000..a55e271
--- /dev/null
@@ -0,0 +1,531 @@
+---------------------------------------------------------------------
+
+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'
+
+
index 05eaffa..5bfc372 100644 (file)
@@ -58,72 +58,10 @@ config bgp_template bgp_common
     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'
-
 
index 1807df7..134b44f 100644 (file)
@@ -78,9 +78,3 @@ config route
     option type 'iface'
     option prefix '2001:db8:0:f101::1111/128'
     option iface 'eth0'
-
-config filter 'firstFilter'
-    option type 'bgp'
-    option instance 'bgp1'
-    option file_path '/var/filters/f1'
-