Doc: Redesign default config file

The old one does not work with 2.0.x.

1 files changed, 168 insertions, 186 deletions

diff --git a/doc/bird.conf.example b/doc/bird.conf.example
index 62c65ce9..384270e3 100644
--- a/doc/bird.conf.example
+++ b/doc/bird.conf.example
@@ -1,222 +1,204 @@
-/*
- *	This is an example configuration file
- *	(for version 1.x.x, obsolete)
- */
-
-# Yes, even shell-like comments work...
+# This is a basic configuration file, which contains boilerplate options and
+# some basic examples. It allows the BIRD daemon to start but will not cause
+# anything else to happen.
+#
+# Please refer to the BIRD User's Guide documentation, which is also available
+# online at http://bird.network.cz/ in HTML format, for more information on
+# configuring BIRD and adding routing protocols.
 
 # Configure logging
-#log syslog { debug, trace, info, remote, warning, error, auth, fatal, bug };
-#log stderr all;
-#log "tmp" all;
+log syslog all;
+# log "/var/log/bird.log" { debug, trace, info, remote, warning, error, auth, fatal, bug };
 
-# Override router ID
-#router id 198.51.100.1;
+# Set router ID. It is a unique identification of your router, usually one of
+# IPv4 addresses of the router. It is recommended to configure it explicitly.
+# router id 198.51.100.1;
 
-# You can define your own symbols...
-#define xyzzy = (120+10);
-#define '1a-a1' = (30+40);
+# Turn on global debugging of all protocols (all messages or just selected classes)
+# debug protocols all;
+# debug protocols { events, states };
 
-# Define a route filter...
-#filter test_filter {
-#	if net ~ 10.0.0.0/16 then accept;
-#	else reject;
-#}
+# Turn on internal watchdog
+# watchdog warning 5 s;
+# watchdog timeout 30 s;
 
-#filter sink { reject; }
-#filter okay { accept; }
+# You can define your own constants
+# define my_asn = 65000;
+# define my_addr = 198.51.100.1;
 
-#include "filters.conf";
+# Tables master4 and master6 are defined by default
+# ipv4 table master4;
+# ipv6 table master6;
 
-# Define another routing table
-#table testable;
+# Define more tables, e.g. for policy routing or as MRIB
+# ipv4 table mrib4;
+# ipv6 table mrib6;
 
-# Turn on global debugging of all protocols
-#debug protocols all;
+# The Device protocol is not a real routing protocol. It does not generate any
+# routes and it only serves as a module for getting information about network
+# interfaces from the kernel. It is necessary in almost any configuration.
+protocol device {
+}
 
-# Turn on internal watchdog
-#watchdog warning 5 s;
-#watchdog timeout 30 s;
-
-# The direct protocol automatically generates device routes to
-# all network interfaces. Can exist in as many instances as you wish
-# if you want to populate multiple routing tables with device routes.
-#protocol direct {
-#	interface "-eth*", "*";	# Restrict network interfaces it works with
-#}
+# The direct protocol is not a real routing protocol. It automatically generates
+# direct routes to all network interfaces. Can exist in as many instances as you
+# wish if you want to populate multiple routing tables with direct routes.
+protocol direct {
+	disabled;		# Disable by default
+	ipv4;			# Connect to default IPv4 table
+	ipv6;			# ... and to default IPv6 table
+}
 
-# This pseudo-protocol performs synchronization between BIRD's routing
-# tables and the kernel. If your kernel supports multiple routing tables
-# (as Linux 2.2.x does), you can run multiple instances of the kernel
-# protocol and synchronize different kernel tables with different BIRD tables.
+# The Kernel protocol is not a real routing protocol. Instead of communicating
+# with other routers in the network, it performs synchronization of BIRD
+# routing tables with the OS kernel. One instance per table.
 protocol kernel {
-#	learn;			# Learn all alien routes from the kernel
-	persist;		# Don't remove routes on bird shutdown
-	scan time 20;		# Scan kernel routing table every 20 seconds
-#	import none;		# Default is import all
-	export all;		# Default is export none
-#	kernel table 5;		# Kernel table to synchronize with (default: main)
+	ipv4 {			# Connect protocol to IPv4 table by channel
+#	      table master4;	# Default IPv4 table is master4
+#	      import all;	# Import to table, default is import all
+	      export all;	# Export to protocol. default is export none
+	};
+#	learn;			# Learn alien routes from the kernel
+#	kernel table 10;	# Kernel table to synchronize with (default: main)
 }
 
-# This pseudo-protocol watches all interface up/down events.
-protocol device {
-	scan time 10;		# Scan interfaces every 10 seconds
+# Another instance for IPv6, skipping default options
+protocol kernel {
+	ipv6 { export all; };
 }
 
-# Static routes (again, there can be multiple instances, so that you
-# can disable/enable various groups of static routes on the fly).
+# Static routes (Again, there can be multiple instances, for different address
+# families and to disable/enable various groups of static routes on the fly).
 protocol static {
-#	disabled;		# Disable by default
-#	table testable;		# Connect to a non-default table
-#	preference 1000;	# Default preference of routes
-#	debug { states, routes, filters, interfaces, events, packets };
-#	debug all;
-#	route 0.0.0.0/0 via 198.51.100.13;
-#	route 198.51.100.0/25 unreachable;
+	ipv4;			# Again, IPv4 channel with default options
+
+#	route 0.0.0.0/0 via 198.51.100.10;
+#	route 192.0.2.0/24 blackhole;
 #	route 10.0.0.0/8 unreachable;
-#	route 10.1.1.0:255.255.255.0 via 198.51.100.3;
-#	route 10.1.2.0:255.255.255.0 via 198.51.100.3;
-#	route 10.1.3.0:255.255.255.0 via 198.51.100.4;
-#	route 10.2.0.0/24 via "arc0";
+#	route 10.2.0.0/24 via "eth0";
+#	# Static routes can be defined with optional attributes
+#	route 10.1.1.0/24 via 198.51.100.3 { rip_metric = 3; };
+#	route 10.1.2.0/24 via 198.51.100.3 { ospf_metric1 = 100; };
+#	route 10.1.3.0/24 via 198.51.100.4 { ospf_metric2 = 100; };
 }
 
-# Pipe protocol connects two routing tables... Beware of loops.
-#protocol pipe {
-#	peer table testable;
-# Define what routes do we export to this protocol / import from it.
-#	import all;		# default is all
-#	export all;		# default is none
-#	import none;		# If you wish to disable imports
-#	import filter test_filter;		# Use named filter
-#	import where source = RTS_DEVICE;	# Use explicit filter
-#}
-
-# RIP aka Rest In Pieces...
-#protocol rip MyRIP {	# You can also use an explicit name
-#	preference xyzzy;
-#	debug all;
-#	port 1520;
-#	period 7;
-#	infinity 16;
-#	garbage time 60;
-#	interface "*" { mode broadcast; };
-#	honor neighbor;		# To whom do we agree to send the routing table
-#	honor always;
-#	honor never;
-#	passwords {
-#		password "nazdar";
+# Pipe protocol connects two routing tables. Beware of loops.
+# protocol pipe {
+#	table master4;		# No ipv4/ipv6 channel definition like in other protocols
+#	peer table mrib4;
+#	import all;		# Direction peer table -> table
+#	export all;		# Direction table -> peer table
+# }
+
+# RIP example, both RIP and RIPng are supported
+# protocol rip {
+#	ipv4 {
+#		# Export direct, static routes and ones from RIP itself
+#		import all;
+#		export where source ~ [ RTS_DEVICE, RTS_STATIC, RTS_RIP ];
 #	};
-#	authentication none;
-#	import filter { print "importing"; accept; };
-#	export filter { print "exporting"; accept; };
-#}
+#	interface "eth*" {
+#	  	update time 10;			# Default period is 30
+#		timeout time 60;		# Default timeout is 180
+#		authentication cryptographic;	# No authentication by default
+#		password "hello" { algorithm hmac sha256; }; # Default is MD5
+#	};
+# }
 
-#protocol ospf MyOSPF {
-#       tick 2;
-#	rfc1583compat yes;
-#	area 0.0.0.0 {
-#		stub no;
+# OSPF example, both OSPFv2 and OSPFv3 are supported
+# protocol ospf v3 {
+#  	ipv6 {
+#		import all;
+#		export where source = RTS_STATIC;
+#	};
+#	area 0 {
 #		interface "eth*" {
-#			hello 9;
-#			retransmit 6;
-#			cost 10;
-#			transmit delay 5;
-#			dead count 5;
-#			wait 50;
-#			type broadcast;
-#			authentication simple;
-#			password "pass";
+#			type broadcast;		# Detected by default
+#			cost 10;		# Interface metric
+#			hello 5;		# Default hello perid 10 is too long
 #		};
-#		interface "arc0" {
-#			rx buffer large;
-#			type nonbroadcast;
-#			poll 14;
-#			dead 75;
-#			neighbors {
-#				10.1.1.2 eligible;
-#				10.1.1.4;
-#			};
-#			strict nonbroadcast yes;
+#		interface "tun*" {
+#			type ptp;		# PtP mode, avoids DR selection
+#			cost 100;		# Interface metric
+#			hello 5;		# Default hello perid 10 is too long
 #		};
-#		interface "xxx0" {
-#                       passwords {
-#				password "abc" {
-#					id 1;
-#					generate to "22-04-2003 11:00:06";
-#					accept to "17-01-2004 12:01:05";
-#				};
-#				password "def" {
-#					id 2;
-#					generate from "22-04-2003 11:00:07";
-#					accept from "17-01-2003 12:01:05";
-#				};
-#			};
-#                       authentication cryptographic;
-#		};
-#	};
-#	area 20 {
-#		stub 1;
-#		interface "ppp1" {
-#			hello 8;
-#			authentication none;
+#		interface "dummy0" {
+#			stub;			# Stub interface, just propagate it
 #		};
-#               interface "fr*";
-#               virtual link 192.168.0.1 {
-#                       password "sdsdffsdfg";
-#                       authentication cryptographic;
-#               };
 #	};
 #}
 
-
-#protocol bgp {
-#	disabled;
+# Define simple filter as an example for BGP import filter
+# See https://gitlab.labs.nic.cz/labs/bird/wikis/BGP_filtering for more examples
+# filter rt_import
+# {
+#	if bgp_path.first != 64496 then accept;
+#	if bgp_path.len > 64 then accept;
+#	if bgp_next_hop != from then accept;
+#	reject;
+# }
+
+# BGP example, explicit name 'uplink1' is used instead of default 'bgp1'
+# protocol bgp uplink1 {
 #	description "My BGP uplink";
-#	local as 65000;
-#	neighbor 198.51.100.130 as 64496;
-#	multihop;
-#	hold time 240;
-#	startup hold time 240;
-#	connect retry time 120;
-#	keepalive time 80;	# defaults to hold time / 3
-#	start delay time 5;	# How long do we wait before initial connect
-#	error wait time 60, 300;# Minimum and maximum time we wait after an error (when consecutive
-#				# errors occur, we increase the delay exponentially ...
-#	error forget time 300;	# ... until this timeout expires)
-#	disable after error;	# Disable the protocol automatically when an error occurs
-#	next hop self;		# Disable next hop processing and always advertise our local address as nexthop
-#	path metric 1;		# Prefer routes with shorter paths (like Cisco does)
-#	default bgp_med 0;	# MED value we use for comparison when none is defined
-#	default bgp_local_pref 0;	# The same for local preference
-#	source address 198.51.100.14;	# What local address we use for the TCP connection
+#	local 198.51.100.1 as 65000;
+#	neighbor 198.51.100.10 as 64496;
+#	hold time 90;		# Default is 240
 #	password "secret";	# Password used for MD5 authentication
-#	rr client;		# I am a route reflector and the neighor is my client
-#	rr cluster id 1.0.0.1;	# Use this value for cluster id instead of my router id
-#	export where source=RTS_STATIC;
-#	export filter {
-#		if source = RTS_STATIC then {
-#			bgp_community = -empty-; bgp_community = add(bgp_community,(65000,5678));
-#			bgp_origin = 0;
-#			bgp_community = -empty-; bgp_community.add((65000,5678));
-#			if (65000,64501) ~ bgp_community then
-#				bgp_community.add((0, 1));
-#			if bgp_path ~ [= 65000 =] then
-#				bgp_path.prepend(65000);
-#			accept;
-#		}
-#		reject;
+#
+#	ipv4 {			# regular IPv4 unicast (1/1)
+#		import filter rt_import;
+#		export where source ~ [ RTS_STATIC, RTS_BGP ];
+#	};
+#
+#	ipv6 {			# regular IPv6 unicast (2/1)
+#		import filter rt_import;
+#		export filter {	# The same as 'where' expression above
+#			if source ~ [ RTS_STATIC, RTS_BGP ]
+#			then accept;
+#			else reject;
+#		};
+#	};
+#
+#	ipv4 multicast {	# IPv4 multicast topology (1/2)
+#		table mrib4;	# explicit IPv4 table
+#		import filter rt_import;
+#		export all;
 #	};
-#}
 #
-# Template usage example
-#template bgp rr_client {
-#	disabled;
-#	local as 65000;
-#	multihop;
+#	ipv6 multicast {	# IPv6 multicast topology (2/2)
+#		table mrib6;	# explicit IPv6 table
+#		import filter rt_import;
+#		export all;
+#	};
+#}
+
+# Template example. Using templates to define IBGP route reflector clients.
+# template bgp rr_clients {
+#	local 10.0.0.1 as 65000;
+#	neighbor as 65000;
 #	rr client;
 #	rr cluster id 1.0.0.1;
-#}
 #
-#protocol bgp rr_abcd from rr_client {
-#	neighbor 10.1.4.7 as 65000;
-#}
+#	ipv4 {
+#		import all;
+#		export where source = RTS_BGP;
+#	};
+#
+#	ipv6 {
+#		import all;
+#		export where source = RTS_BGP;
+#	};
+# }
+#
+# protocol bgp client1 from rr_clients {
+#	neighbor 10.0.1.1;
+# }
+#
+# protocol bgp client2 from rr_clients {
+#	neighbor 10.0.2.1;
+# }
+#
+# protocol bgp client3 from rr_clients {
+#	neighbor 10.0.3.1;
+# }