diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/LinuxDocTools.pm | 2 | ||||
| -rw-r--r-- | doc/Makefile | 73 | ||||
| -rw-r--r-- | doc/bird.conf.example | 3 | ||||
| -rw-r--r-- | doc/bird.conf.example2 | 341 | ||||
| -rw-r--r-- | doc/bird.sgml | 515 | ||||
| -rwxr-xr-x | doc/sgml2html | 8 | ||||
| -rwxr-xr-x | doc/sgml2latex | 8 | ||||
| -rwxr-xr-x | doc/sgml2txt | 8 |
8 files changed, 835 insertions, 123 deletions
diff --git a/doc/LinuxDocTools.pm b/doc/LinuxDocTools.pm index 51d4a04c..39bb401d 100644 --- a/doc/LinuxDocTools.pm +++ b/doc/LinuxDocTools.pm @@ -372,6 +372,8 @@ sub process_file } } # + + local $ENV{PATH} = "$ENV{PATH}:/usr/lib/linuxdoc-tools"; my($precmd) = "|sgmlpre output=$global->{format} $global->{define}"; # diff --git a/doc/Makefile b/doc/Makefile index 70b73943..f36642be 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,50 +1,49 @@ -root-rel=../ -dir-name=doc - -ifneq ($(wildcard ../Rules),) -include ../Rules -else -srcdir=$(shell cd $(root-rel) ; pwd) -srcdir_abs=$(srcdir) -endif - # Force rebuilds -.PHONY: prog.sgml bird.sgml +.PHONY: progspell docs progdocs userdocs + +doc-srcdir := $(shell cd $(s) && pwd) +sgml2 := $(doc-srcdir)/sgml2 docs: progdocs userdocs -progdocs: prog.html prog.ps -userdocs: bird.html bird.pdf -prog.sgml: - $(srcdir)/tools/progdoc $(srcdir_abs) +doc-fmt = $(1): $(o)prog.$(1) $(o)bird.$(1) +$(call doc-fmt,html) +$(call doc-fmt,dvi) +$(call doc-fmt,ps) +$(call doc-fmt,pdf) -%.html: %.sgml - ./sgml2html $< +progdocs: $(o)prog.html $(o)prog.pdf +userdocs: $(o)bird.html $(o)bird.pdf +progspell: $(o)prog.spell -%.dvi: %.tex - latex $< - latex $< +$(o)prog.sgml: $(srcdir)/tools/progdoc $(objdir)/.dir-stamp + $(srcdir)/tools/progdoc $(srcdir) $@ -%.ps: %.dvi - dvips -D600 -ta4 -o $@ $< +$(o)%.sgml: $(s)%.sgml $(objdir)/.dir-stamp + cp $< $@ -%.pdf: %.tex - pdflatex $< - pdflatex $< +$(o)%.html: $(o)%.sgml + cd $(dir $@) && $(sgml2)html $(notdir $<) -%.tex: %.sgml - ./sgml2latex --output=tex $< +$(o)%.tex: $(o)%.sgml + cd $(dir $@) && $(sgml2)latex --output=tex $(notdir $<) + +$(o)%.dvi: $(o)%.tex + cd $(dir $@) && TEXINPUTS=$(TEXINPUTS):$(doc-srcdir)/tex latex $(notdir $<) + cd $(dir $@) && TEXINPUTS=$(TEXINPUTS):$(doc-srcdir)/tex latex $(notdir $<) + +$(o)%.ps: $(o)%.dvi + dvips -D600 -ta4 -o $@ $< -%.txt: %.sgml - ./sgml2txt $< +$(o)%.pdf: $(o)%.tex + TEXINPUTS=$(TEXINPUTS):$(doc-srcdir)/tex pdflatex -output-directory=$(dir $@) $< + TEXINPUTS=$(TEXINPUTS):$(doc-srcdir)/tex pdflatex -output-directory=$(dir $@) $< -progspell: prog.sgml - sed -f prog-spell.sed <prog.sgml >prog.spell - ispell prog.spell +$(o)%.txt: $(o)%.sgml + cd $(dir $@) && $(sgml2)txt $(notdir $<) -clean: - rm -f *.tex *.dvi *.log *.txt *.aux *.toc *.spell - rm -f prog.sgml +$(o)prog.spell: $(o)prog.sgml $(s)prog-spell.sed + sed -f $(lastword $^) <$< >$@ + ispell $@ -distclean: clean - rm -f *.html *.ps +$(call clean,prog.spell $(addprefix *.,html dvi ps pdf sgml tex txt aux log toc)) diff --git a/doc/bird.conf.example b/doc/bird.conf.example index bbfe0020..62c65ce9 100644 --- a/doc/bird.conf.example +++ b/doc/bird.conf.example @@ -1,5 +1,6 @@ /* - * This is an example configuration file. + * This is an example configuration file + * (for version 1.x.x, obsolete) */ # Yes, even shell-like comments work... diff --git a/doc/bird.conf.example2 b/doc/bird.conf.example2 new file mode 100644 index 00000000..51fcfb64 --- /dev/null +++ b/doc/bird.conf.example2 @@ -0,0 +1,341 @@ +/* + * This is an example configuration file for MB-BGP setting + */ + + +log "bird.log" all; +# debug protocols all; + +router id 192.168.1.1; + +ipv4 table master4; +ipv6 table master6; + +ipv4 table mcast4; +ipv6 table mcast6; + +ipv4 table mtab4; +ipv6 table mtab6; + +vpn4 table vpntab4; +vpn6 table vpntab6; + +vpn4 table vpn4mc; +vpn6 table vpn6mc; + +flow4 table flowtab4; +flow6 table flowtab6; + + +protocol device { + scan time 10; +} + +protocol kernel kernel4 { + scan time 20; + + ipv4 { + export all; + }; +} + +protocol kernel kernel6 { + scan time 20; + + ipv6 { + export all; + }; +} + + +protocol static static4 { + ipv4; + + route 10.10.0.0/24 via 192.168.1.2; + route 10.10.1.0/24 via 192.168.1.2 { bgp_large_community.add((10,20,30)); bgp_large_community.add((10,(20*3),10)); }; +} + +protocol static static6 { + ipv6; + + route 2001:db8:10:10::/64 via 2001:db8:1:1::10; + route 2001:db8:10:11::/64 via 2001:db8:1:1::10; + + route 2001:db8:1:1::/64 via fe80::ec9b:67ff:fe60:fd5d % ve1; +} + +# VPNv4 routes with MPLS labels +protocol static statvpn4 { + vpn4; + + route 10:10 10.20.0.0/24 via 192.168.1.2 mpls 210; + route 10:10 10.20.1.0/24 via 192.168.1.2 mpls 210; + route 10:20 10.20.0.0/24 via 192.168.1.2 mpls 220; + route 10:20 10.20.1.0/24 via 192.168.1.2 mpls 220; +} + +protocol static statvpn6 { + vpn6; + + route 10:10 2001:db8:20:10::/64 via 2001:db8:1:1::10 mpls 200/210; + route 10:10 2001:db8:20:11::/64 via 2001:db8:1:1::10 mpls 200/210; + route 10:20 2001:db8:20:10::/64 via 2001:db8:1:1::10 mpls 200/220; + route 10:20 2001:db8:20:11::/64 via 2001:db8:1:1::10 mpls 200/220; +} + +# RFC 5575 flow specification +protocol static flowstat4 { + flow4; + + route flow4 { + dst 10.0.0.0/8; + proto = 23; + dport > 24 && < 30 || 40..50,60..70,80; + sport > 24 && < 30 || = 40 || 50,60..70,80; + icmp type 80; + icmp code 90; + tcp flags 0x03/0x0f; + length 2048..65535; + dscp = 63; + fragment dont_fragment, is_fragment || !first_fragment; + }; + + route flow4 { + dst 11.0.0.0/8; + proto = 0x12; + sport > 0x5678 && < 0x9abc || 0xdef0 || 0x1234,0x5678,0x9abc..0xdef0; + dport = 50; + tcp flags 0x000/0xf00; + }; + + route flow4 { + dst 12.0.0.0/32; + tcp flags ! 0/0x999; + }; + + route flow4 { + dst 220.0.254.0/24; + tcp flags 0x99/0x999; + }; + + route flow4 { + dst 220.0.254.192/28; + tcp flags ! 0xfff/0xfff; + }; + + route flow4 { + dst 15.0.0.0/8; + tcp flags ! 0x999/0x999; + }; +} + +protocol static flowstat6 { + flow6; + + route flow6 { + dst fec0:1122:3344:5566::1/128; + src 0000:0000:0000:0001:1234:5678:9800:0000/101 offset 63; + next header = 23; + sport 24..30, 42 || 50,60,70..80; + dport = 50; + tcp flags 0x03/0x0f, !0/0xff || 0x33/0x33; + fragment !is_fragment || !first_fragment; + label 0xaaaa/0xaaaa && 0x33/0x33; + }; + + route flow6 { + dst fec0:1122:3344:5566::1/128; + src ::1:1234:5678:9800:0/101 offset 63; + next header = 23; + dport = 50; + sport > 24 && < 30 || = 40 || = 50 || = 60 || >= 70 && <= 80; + tcp flags 0x3/0x3 && 0x0/0xc; + }; +} + + +protocol pipe { + table master4; + peer table mcast4; + import none; + export where source = RTS_OSPF; +} + +protocol pipe { + table master6; + peer table mcast6; + import none; + export where source = RTS_OSPF; +} + +protocol ospf2 ospf4 { +# ecmp; + + ipv4 { + import all; +# export where source = RTS_STATIC; + }; + + area 0 { + interface "ve0" { stub; }; + interface "ve1" { hello 5; type ptp; }; + interface "ve2" { hello 5; type bcast; ttl security; }; + interface "ve3" { hello 5; type bcast; ttl security; }; + }; +} + + +protocol ospf3 ospf6 { +# ecmp; + + ipv6 { + import all; +# export where source = RTS_STATIC; + }; + + area 0 { + interface "ve0" { stub; }; + interface "ve1" { hello 5; type ptp; }; + interface "ve2" { hello 5; type bcast; }; + }; +} + +protocol bgp { + local 192.168.11.1 as 1000; + neighbor 192.168.11.2 as 2000; +# local 192.168.1.1 as 1000; +# neighbor 192.168.2.1 as 2000; +# multihop; +# rr client; +# strict bind; +# debug all; + + # regular IPv4 unicast (1/1) + ipv4 { + # connects to master4 table by default + import all; + export where source ~ [ RTS_STATIC, RTS_BGP ]; + }; + + # regular IPv6 unicast (2/1) + ipv6 { + # connects to master6 table by default + import all; + export where source ~ [ RTS_STATIC, RTS_BGP ]; +# next hop address 2001:db8:1:1::1; + }; + + # IPv4 multicast topology (1/2) + ipv4 multicast { + # explicit IPv4 table + table mcast4; + import all; + export all; + }; + + # IPv6 multicast topology (2/2) + ipv6 multicast { + # explicit IPv6 table + table mcast6; + import all; + export all; +# next hop address 2001:db8:1:1::1; + }; + + # IPv4 with MPLS labels (1/4) + ipv4 mpls { + # explicit IPv4 table + table mtab4; + import all; + export all; + }; + + # IPv6 with MPLS labels (2/4) + ipv6 multicast { + # explicit IPv6 table + table mtab6; + import all; + export all; + # allows IPv4 next hops (6PE) + # extended next hop; + }; + + # VPNv4 with MPLS labels (1/128) + vpn4 mpls { + # connects to vpntab4 table by default + import all; + export all; + }; + + # VPNv6 with MPLS labels (2/128) + vpn6 mpls { + # connects to vpntab6 table by default + import all; + export all; + }; + + # VPNv4 multicast topology (1/129) + vpn4 multicast { + table vpn4mc; + import all; + export all; + }; + + # VPNv6 multicast topology (2/129) + vpn6 multicast { + table vpn6mc; + import all; + export all; + }; + + # IPv4 Flowspec (1/133) + flow4 { + # connects to flowtab4 table by default + import all; + export all; + }; + + # IPv6 Flowspec (2/133) + flow6 { + # connects to flowtab6 table by default + import all; + export all; + }; +} + +protocol bgp { + local 192.168.1.1 as 1000; + neighbor 192.168.3.1 as 1000; + multihop; + rr client; + + ipv4 { + import all; + export where source ~ [ RTS_STATIC, RTS_BGP ]; + }; + + ipv6 { + import all; + export where source ~ [ RTS_STATIC, RTS_BGP ]; + next hop address 2001:db8:1:1::1; + }; +} + +protocol bgp { + local 2001:db8:1:1::1 as 1000; + neighbor 2001:db8:4:1::1 as 1000; + multihop; + rr client; + + ipv4 { + import all; + export where source ~ [ RTS_STATIC, RTS_BGP ]; + next hop address 192.168.4.1; + }; + + ipv6 { + import all; + export where source ~ [ RTS_STATIC, RTS_BGP ]; + }; +} + diff --git a/doc/bird.sgml b/doc/bird.sgml index ffd28964..01b59c6a 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -715,6 +715,138 @@ agreement"). </descrip> + +<sect>Flowspec network type +<label id="flowspec-network-type"> + +<p>The flow specification are rules for routers and firewalls for filtering +purpose. It is described by <rfc id="5575">. There are 3 types of arguments: +<m/inet4/ or <m/inet6/ prefixes, bitmasks matching expressions and numbers +matching expressions. + +Bitmasks matching is written using <m/value/<cf>/</cf><m/mask/ or +<cf/!/<m/value/<cf>/</cf><m/mask/ pairs. It means that <cf/(/<m/data/ <cf/&/ +<m/mask/<cf/)/ is or is not equal to <m/value/. + +Numbers matching is a matching sequence of numbers and ranges separeted by a +commas (<cf/,/) (e.g. <cf/10,20,30/). Ranges can be written using double dots +<cf/../ notation (e.g. <cf/80..90,120..124/). An alternative notation are +sequence of one or more pairs of relational operators and values separated by +logical operators <cf/&&/ or <cf/||/. Allowed relational operators are <cf/=/, +<cf/!=/, <cf/</, <cf/<=/, <cf/>/, <cf/>=/, <cf/true/ and <cf/false/. + +<sect1>IPv4 Flowspec + +<p><descrip> + <tag><label id="flow-dst">dst <m/inet4/</tag> + Set a matching destination prefix (e.g. <cf>dst 192.168.0.0/16</cf>). + Only this option is mandatory in IPv4 Flowspec. + + <tag><label id="flow-src">src <m/inet4/</tag> + Set a matching source prefix (e.g. <cf>src 10.0.0.0/8</cf>). + + <tag><label id="flow-proto">proto <m/numbers-match/</tag> + Set a matching IP protocol numbers (e.g. <cf/proto 6/). + + <tag><label id="flow-port">port <m/numbers-match/</tag> + Set a matching source or destination TCP/UDP port numbers (e.g. + <cf>port 1..1023,1194,3306</cf>). + + <tag><label id="flow-dport">dport <m/numbers-match/</tag> + Set a mating destination port numbers (e.g. <cf>dport 49151</cf>). + + <tag><label id="flow-sport">sport <m/numbers-match/</tag> + Set a matching source port numbers (e.g. <cf>sport = 0</cf>). + + <tag><label id="flow-icmp-type">icmp type <m/numbers-match/</tag> + Set a matching type field number of an ICMP packet (e.g. <cf>icmp type + 3</cf>) + + <tag><label id="flow-icmp-code">icmp code <m/numbers-match/</tag> + Set a matching code field number of an ICMP packet (e.g. <cf>icmp code + 1</cf>) + + <tag><label id="flow-tcp-flags">tcp flags <m/bitmask-match/</tag> + Set a matching bitmask for TCP header flags (aka control bits) (e.g. + <cf>tcp flags 0x03/0x0f;</cf>). The maximum length of mask is 12 bits + (0xfff). + + <tag><label id="flow-length">length <m/numbers-match/</tag> + Set a matching packet length (e.g. <cf>length > 1500;</cf>) + + <tag><label id="flow-dscp">dscp <m/numbers-match/</tag> + Set a matching DiffServ Code Point number (e.g. <cf>length > 1500;</cf>). + + <tag><label id="flow-fragment">fragment <m/fragmentation-type/</tag> + Set a matching type of packet fragmentation. Allowed fragmentation + types are <cf/dont_fragment/, <cf/is_fragment/, <cf/first_fragment/, + <cf/last_fragment/ (e.g. <cf>fragment is_fragment && + !dont_fragment</cf>). +</descrip> + +<p><code> +protocol static { + flow4; + + route flow4 { + dst 10.0.0.0/8; + port > 24 && < 30 || 40..50,60..70,80 && >= 90; + tcp flags 0x03/0x0f; + length > 1024; + dscp = 63; + fragment dont_fragment, is_fragment || !first_fragment; + } drop; +} +</code> + +<sect1>Differences for IPv6 Flowspec + +<p>Flowspec IPv6 are same as Flowspec IPv4 with a few exceptions. +<itemize> + <item>Prefixes <m/inet6/ can be specified not only with prefix length, + but with prefix <cf/offset/ <m/num/ too (e.g. + <cf>::1234:5678:9800:0000/101 offset 64</cf>). Offset means to don't + care of <m/num/ first bits. + <item>IPv6 Flowspec hasn't mandatory any flowspec component. + <item>In IPv6 packets, there is a matching the last next header value + for a matching IP protocol number (e.g. <cf>next header 6</cf>). + <item>It is not possible to set <cf>dont_fragment</cf> as a type of + packet fragmentation. +</itemize> + +<p><descrip> + <tag><label id="flow6-dst">dst <m/inet6/ [offset <m/num/]</tag> + Set a matching destination IPv6 prefix (e.g. <cf>dst + ::1c77:3769:27ad:a11a/128 offset 64</cf>). + + <tag><label id="flow6-src">src <m/inet6/ [offset <m/num/]</tag> + Set a matching source IPv6 prefix (e.g. <cf>src fe80::/64</cf>). + + <tag><label id="flow6-next-header">next header <m/numbers-match/</tag> + Set a matching IP protocol numbers (e.g. <cf>next header != 6</cf>). + + <tag><label id="flow6-label">label <m/bitmask-match/</tag> + Set a 20-bit bitmask for matching Flow Label field in IPv6 packets + (e.g. <cf>label 0x8e5/0x8e5</cf>). +</descrip> + +<p><code> +protocol static { + flow6; + + route flow6 { + dst fec0:1122:3344:5566:7788:99aa:bbcc:ddee/128; + src 0000:0000:0000:0001:1234:5678:9800:0000/101 offset 63; + next header = 23; + sport > 24 && < 30 || = 40 || 50,60,70..80; + dport = 50; + tcp flags 0x03/0x0f, !0/0xff || 0x33/0x33; + fragment !is_fragment || !first_fragment; + label 0xaaaa/0xaaaa && 0x33/0x33; + } drop; +} +</code> + <chapt>Remote control <label id="remote-control"> @@ -793,9 +925,8 @@ This argument can be omitted if there exists only a single instance. Show the list of symbols defined in the configuration (names of protocols, routing tables etc.). - <tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table <m/t/] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [<m/options/]</tag> - Show contents of a routing table (by default of the main one or the - table attached to a respective protocol), that is routes, their metrics + <tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table (<m/t/ | all)] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [(stats|count)] [<m/options/]</tag> + Show contents of specified routing tables, that is routes, their metrics and (in case the <cf/all/ switch is given) all their attributes. <p>You can specify a <m/prefix/ if you want to print routes for a @@ -805,20 +936,31 @@ This argument can be omitted if there exists only a single instance. the selected one at the top, unless <cf/primary/ is given in which case only the selected route is shown. + <p>The <cf/show route/ command can process one or multiple routing + tables. The set of selected tables is determined on three levels: First, + tables can be explicitly selected by <cf/table/ switch, which could be + used multiple times, all tables are specified by <cf/table all/. Second, + tables can be implicitly selected by channels or protocols that are + arguments of several other switches (e.g., <cf/export/, <cf/protocol/). + Last, the set of default tables is used: <cf/master4/, <cf/master6/ and + each first table of any other network type. + <p>You can also ask for printing only routes processed and accepted by a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ } </cf> or matching a given condition (<cf>where <m/condition/</cf>). The <cf/export/, <cf/preexport/ and <cf/noexport/ switches ask for - printing of routes that are exported to the specified protocol. - With <cf/preexport/, the export filter of the protocol is skipped. - With <cf/noexport/, routes rejected by the export filter are printed - instead. Note that routes not exported to the protocol for other reasons + printing of routes that are exported to the specified protocol or + channel. With <cf/preexport/, the export filter of the channel is + skipped. With <cf/noexport/, routes rejected by the export filter are + printed instead. Note that routes not exported for other reasons (e.g. secondary routes or routes imported from that protocol) are not - printed even with <cf/noexport/. + printed even with <cf/noexport/. These switches also imply that + associated routing tables are selected instead of default ones. <p>You can also select just routes added by a specific protocol. - <cf>protocol <m/p/</cf>. + <cf>protocol <m/p/</cf>. This switch also implies that associated + routing tables are selected instead of default ones. <p>If BIRD is configured to keep filtered routes (see <cf/import keep filtered/ option), you can show them instead of routes by using @@ -828,27 +970,6 @@ This argument can be omitted if there exists only a single instance. number of networks, number of routes before and after filtering). If you use <cf/count/ instead, only the statistics will be printed. - <tag><label id="cli-show-roa">show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/]</tag> - Show contents of a ROA table (by default of the first one). You can - specify a <m/prefix/ to print ROA entries for a specific network. If you - use <cf>for <m/prefix/</cf>, you'll get all entries relevant for route - validation of the network prefix; i.e., ROA entries whose prefixes cover - the network prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA - entries covered by the network prefix. You could also use <cf/as/ option - to show just entries for given AS. - - <tag><label id="cli-add-roa">add roa <m/prefix/ max <m/num/ as <m/num/ [table <m/t/]</tag> - Add a new ROA entry to a ROA table. Such entry is called <it/dynamic/ - compared to <it/static/ entries specified in the config file. These - dynamic entries survive reconfiguration. - - <tag><label id="cli-delete-roa">delete roa <m/prefix/ max <m/num/ as <m/num/ [table <m/t/]</tag> - Delete the specified ROA entry from a ROA table. Only dynamic ROA - entries (i.e., the ones added by <cf/add roa/ command) can be deleted. - - <tag><label id="cli-flush-roa">flush roa [table <m/t/]</tag> - Remove all dynamic ROA entries from a ROA table. - <tag><label id="cli-configure">configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag> Reload configuration from a given file. BIRD will smoothly switch itself to the new configuration, protocols are reconfigured if possible, @@ -1055,20 +1176,41 @@ foot). <tag><label id="type-ip">ip</tag> This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it is either an IPv4 or IPv6 - address. IP addresses are written in the standard notation + address; this may be checked by <cf>.is_ip4</cf> which returns <cf/bool/. + IP addresses are written in the standard notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from the IP address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true. <tag><label id="type-prefix">prefix</tag> - This type can hold a network prefix consisting of IP address and prefix - length. Prefix literals are written as <cf><m/ipaddress//<m/pxlen/</cf>, + This type can hold a network prefix consisting of IP address, prefix + length and several other values. This is the key in route tables. + + Prefixes may be of several types, which can be determined by the special + operator <cf/.type/. The type may be: + + <cf/NET_IP4/ and <cf/NET_IP6/ prefixes hold an IP prefix. The literals + are written as <cf><m/ipaddress//<m/pxlen/</cf>, or <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special - operators on prefixes: <cf/.ip/ which extracts the IP address from the - pair, and <cf/.len/, which separates prefix length from the pair. + operators on IP prefixes: <cf/.ip/ which extracts the IP address from + the pair, and <cf/.len/, which separates prefix length from the pair. So <cf>1.2.0.0/16.len = 16</cf> is true. + <cf/NET_VPN4/ and <cf/NET_VPN6/ prefixes hold an IP prefix with VPN + Route Distinguisher (<rfc id="4364">). They support the same special + operators as IP prefixes, and also <cf/.rd/ which extracts the Route + Distinguisher. Their literals are written + as <cf><m/vpnrd/ <m/ipprefix/</cf> + + <cf/NET_ROA4/ and <cf/NET_ROA6/ prefixes hold an IP prefix range + together with an ASN. They support the same special operators as IP + prefixes, and also <cf/.maxlen/ which extracts maximal prefix length, + and <cf/.asn/ which extracts the ASN. + + <cf/NET_FLOW4/ and <cf/NET_FLOW6/ hold an IP prefix together with a + flowspec rule. Filters currently don't support flowspec parsing. + <tag><label id="type-ec">ec</tag> This is a specialized type used to represent BGP extended community values. It is essentially a 64bit value, literals of this type are @@ -1253,7 +1395,7 @@ foot). <cf/!˜/ membership operators) can be used to modify or test eclists, with ECs instead of pairs as arguments. - <tag/lclist/ + <tag><label id="type-lclist">lclist/</tag> Lclist is a data type used for BGP large community lists. Like eclists, lclists are very similar to clists, but they are sets of LCs instead of pairs. The same operations (like <cf/add/, <cf/delete/ or <cf/˜/ @@ -1812,17 +1954,39 @@ table it wishes to export along with complete path information (a list of AS'es the packet will travel through if it uses the particular route) in order to avoid routing loops. -<p>BIRD supports all requirements of the BGP4 standard as defined in -<rfc id="4271"> It also supports the community attributes (<rfc id="1997">), -capability negotiation (<rfc id="5492">), MD5 password authentication (<rfc -id="2385">), extended communities (<rfc id="4360">), route reflectors (<rfc -id="4456">), graceful restart (<rfc id="4724">), multiprotocol extensions -(<rfc id="4760">), 4B AS numbers (<rfc id="4893">), and 4B AS numbers in -extended communities (<rfc id="5668">). - +<sect1>Supported standards: +<label id="bgp-standards"> -For IPv6, it uses the standard multiprotocol extensions defined in -<rfc id="4760"> and applied to IPv6 according to <rfc id="2545">. +<itemize> +<item> <rfc id="4271"> - Border Gateway Protocol 4 (BGP) +<item> <rfc id="1997"> - BGP Communities Attribute +<item> <rfc id="2385"> - Protection of BGP Sessions via TCP MD5 Signature +<item> <rfc id="2545"> - Use of BGP Multiprotocol Extensions for IPv6 +<item> <rfc id="2918"> - Route Refresh Capability +<item> <rfc id="3107"> - Carrying Label Information in BGP +<item> <rfc id="4360"> - BGP Extended Communities Attribute +<item> <rfc id="4364"> - BGP/MPLS IPv4 Virtual Private Networks +<item> <rfc id="4456"> - BGP Route Reflection +<item> <rfc id="4486"> - Subcodes for BGP Cease Notification Message +<item> <rfc id="4659"> - BGP/MPLS IPv6 Virtual Private Networks +<item> <rfc id="4724"> - Graceful Restart Mechanism for BGP +<item> <rfc id="4760"> - Multiprotocol extensions for BGP +<item> <rfc id="4798"> - Connecting IPv6 Islands over IPv4 MPLS +<item> <rfc id="5065"> - AS confederations for BGP +<item> <rfc id="5082"> - Generalized TTL Security Mechanism +<item> <rfc id="5492"> - Capabilities Advertisement with BGP +<item> <rfc id="5549"> - Advertising IPv4 NLRI with an IPv6 Next Hop +<item> <rfc id="5575"> - Dissemination of Flow Specification Rules +<item> <rfc id="5668"> - 4-Octet AS Specific BGP Extended Community +<item> <rfc id="6286"> - AS-Wide Unique BGP Identifier +<item> <rfc id="6608"> - Subcodes for BGP Finite State Machine Error +<item> <rfc id="6793"> - BGP Support for 4-Octet AS Numbers +<item> <rfc id="7313"> - Enhanced Route Refresh Capability for BGP +<item> <rfc id="7606"> - Revised Error Handling for BGP UPDATE Messages +<item> <rfc id="7911"> - Advertisement of Multiple Paths in BGP +<item> <rfc id="7947"> - Internet Exchange BGP Route Server +<item> <rfc id="8092"> - BGP Large Communities Attribute +</itemize> <sect1>Route selection rules <label id="bgp-route-select-rules"> @@ -1911,6 +2075,16 @@ using the following configuration parameters: source address for the BGP session. Default: the address of the local end of the interface our neighbor is connected to. + <tag><label id="bgp-strict-bind">strict bind <m/switch/</tag> + Specify whether BGP listening socket should be bound to a specific local + address (the same as the <cf/source address/) and associated interface, + or to all addresses. Binding to a specific address could be useful in + cases like running multiple BIRD instances on a machine, each using its + IP address. Note that listening sockets bound to a specific address and + to all addresses collide, therefore either all BGP protocols (of the + same address family and using the same local port) should have set + <cf/strict bind/, or none of them. Default: disabled. + <tag><label id="bgp-next-hop-self">next hop self</tag> Avoid calculation of the Next Hop attribute and always advertise our own source address as a next hop. This needs to be used only occasionally to @@ -1983,7 +2157,7 @@ using the following configuration parameters: Note that full (ICMP protection, for example) <rfc id="5082"> support is provided by Linux only. Default: disabled. - <tag><label id="bgp-pass">password <m/string/</tag> + <tag><label id="bgp-password">password <m/string/</tag> Use this password for MD5 authentication of BGP sessions (<rfc id="2385">). When used on BSD systems, see also <cf/setkey/ option below. Default: no authentication. @@ -2004,6 +2178,21 @@ using the following configuration parameters: accepting incoming connections. In passive mode, outgoing connections are not initiated. Default: off. + <tag><label id="bgp-confederation">confederation <m/number/</tag> + BGP confederations (<rfc id="5065">) are collections of autonomous + systems that act as one entity to external systems, represented by one + confederation identifier (instead of AS numbers). This option allows to + enable BGP confederation behavior and to specify the local confederation + identifier. When BGP confederations are used, all BGP speakers that are + members of the BGP confederation should have the same confederation + identifier configured. Default: 0 (no confederation). + + <tag><label id="bgp-confederation-member">confederation member <m/switch/</tag> + When BGP confederations are used, this option allows to specify whether + the BGP neighbor is a member of the same confederation as the local BGP + speaker. The option is unnecessary (and ignored) for IBGP sessions, as + the same AS number implies the same confederation. Default: no. + <tag><label id="bgp-rr-client">rr client</tag> Be a route reflector and treat the neighbor as a route reflection client. Default: disabled. @@ -2134,13 +2323,6 @@ using the following configuration parameters: This option is relevant to IPv4 mode with enabled capability advertisement only. Default: on. - <tag><label id="bgp-route-limit">route limit <m/number/</tag> - The maximal number of routes that may be imported from the protocol. If - the route limit is exceeded, the connection is closed with an error. - Limit is currently implemented as <cf>import limit <m/number/ action - restart</cf>. This option is obsolete and it is replaced by - <ref id="proto-import-limit" name="import limit option">. Default: no limit. - <tag><label id="bgp-disable-after-error">disable after error <m/switch/</tag> When an error is encountered (either locally or by the other side), disable the instance automatically and wait for an administrator to fix @@ -2515,7 +2697,7 @@ limitations can be overcome using another routing table and the pipe protocol. routes from other sources (e.g. kernel device routes). Metric 0 has a special meaning of undefined metric, in which either OS default is used, or per-route metric can be set using <cf/krt_metric/ attribute. Default: - 0 (undefined). + 32. <tag><label id="krt-graceful-restart">graceful restart <m/switch/</tag> Participate in graceful restart recovery. If this option is enabled and @@ -2656,14 +2838,15 @@ each router detects all changes. <sect1>Configuration <label id="ospf-config"> -<p>In the main part of configuration, there can be multiple definitions of OSPF -areas, each with a different id. These definitions includes many other switches -and multiple definitions of interfaces. Definition of interface may contain many -switches and constant definitions and list of neighbors on nonbroadcast -networks. +<p>First, the desired OSPF version can be specified by using <cf/ospf v2/ or +<cf/ospf v3/ as a protocol type. By default, OSPFv2 is used. In the main part of +configuration, there can be multiple definitions of OSPF areas, each with a +different id. These definitions includes many other switches and multiple +definitions of interfaces. Definition of interface may contain many switches and +constant definitions and list of neighbors on nonbroadcast networks. <code> -protocol ospf <name> { +protocol ospf [v2|v3] <name> { rfc1583compat <switch>; instance id <num>; stub router <switch>; @@ -3589,10 +3772,12 @@ pretty much obsolete. It is still usable on very small networks. <label id="rip-config"> <p>RIP configuration consists mainly of common protocol options and interface -definitions, most RIP options are interface specific. +definitions, most RIP options are interface specific. RIPng (RIP for IPv6) +protocol instance can be configured by using <cf/rip ng/ instead of just +<cf/rip/ as a protocol type. <code> -protocol rip [<name>] { +protocol rip [ng] [<name>] { infinity <number>; ecmp <switch> [limit <number>]; interface <interface pattern> { @@ -3797,8 +3982,8 @@ protocol rip [<name>] { <p>RIP defines two route attributes: <descrip> - <tag><label id="rta-rip-metric">int rip_metric/</tag> - RIP metric of the route (ranging from 0 to <cf/infinity/). When routes + <tag>int <cf/rip_metric/</tag> + RIP metric of the route (ranging from 0 to <cf/infinity/). When routes from different RIP instances are available and all of them have the same preference, BIRD prefers the route with lowest <cf/rip_metric/. When a non-RIP route is exported to RIP, the default metric is 1. @@ -3829,6 +4014,184 @@ protocol rip { } </code> +<sect>RPKI + +<sect1>Introduction + +<p>The Resource Public Key Infrastructure (RPKI) is mechanism for origin +validation of BGP routes (RFC 6480). BIRD supports only so-called RPKI-based +origin validation. There is implemented RPKI to Router (RPKI-RTR) protocol (RFC +6810). It uses some of the RPKI data to allow a router to verify that the +autonomous system announcing an IP address prefix is in fact authorized to do +so. This is not crypto checked so can be violated. But it should prevent the +vast majority of accidental hijackings on the Internet today, e.g. the famous +Pakastani accidental announcement of YouTube's address space. + +<p>The RPKI-RTR protocol receives and maintains a set of ROAs from a cache +server (also called validator). You can validate routes (RFC 6483) using +function <cf/roa_check()/ in filter and set it as import filter at the BGP +protocol. BIRD should re-validate all of affected routes after RPKI update by +RFC 6811, but we don't support it yet! You can use a BIRD's client command +<cf>reload in <m/bgp_protocol_name/</cf> for manual call of revalidation of all +routes. + +<sect1>Supported transports +<itemize> + <item>Unprotected transport over TCP uses a port 323. The cache server + and BIRD router should be on the same trusted and controlled network + for security reasons. + <item>SSHv2 encrypted transport connection uses the normal SSH port + 22. +</itemize> + +<sect1>Configuration + +<p>We currently support just one cache server per protocol. However you can +define more RPKI protocols generally. + +<code> +protocol rpki [<name>] { + roa4 { table <tab>; }; + roa6 { table <tab>; }; + remote <ip> | "<domain>" [port <num>]; + port <num>; + refresh [keep] <num>; + retry [keep] <num>; + expire [keep] <num>; + transport tcp; + transport ssh { + bird private key "</path/to/id_rsa>"; + remote public key "</path/to/known_host>"; + user "<name>"; + }; +} +</code> + +<p>Alse note that you have to specify ROA table into which will be imported +routes from a cache server. If you want to import only IPv4 prefixes you have +to specify only roa4 table. Similarly with IPv6 prefixes only. If you want to +fetch both IPv4 and even IPv6 ROAs you have to specify both types of ROA +tables. + +<sect2>RPKI protocol options + +<descrip> + <tag>remote <m/ip/ | "<m/hostname/" [port <m/num/]</tag> Specifies + a destination address of the cache server. Can be specified by an IP + address or by full domain name string. Only one cache can be specified + per protocol. This option is required. + + <tag>port <m/num/</tag> Specifies the port number. The default port + number is 323 for transport without any encryption and 22 for transport + with SSH encryption. + + <tag>refresh [keep] <m/num/</tag> Time period in seconds. Tells how + long to wait before next attempting to poll the cache using a Serial + Query or a Reset Query packet. Must be lower than 86400 seconds (one + day). Too low value can caused a false positive detection of + network connection problems. A keyword <cf/keep/ suppresses updating + this value by a cache server. + Default: 3600 seconds + + <tag>retry [keep] <m/num/</tag> Time period in seconds between a failed + Serial/Reset Query and a next attempt. Maximum allowed value is 7200 + seconds (two hours). Too low value can caused a false positive + detection of network connection problems. A keyword <cf/keep/ + suppresses updating this value by a cache server. + Default: 600 seconds + + <tag>expire [keep] <m/num/</tag> Time period in seconds. Received + records are deleted if the client was unable to successfully refresh + data for this time period. Must be in range from 600 seconds (ten + minutes) to 172800 seconds (two days). A keyword <cf/keep/ + suppresses updating this value by a cache server. + Default: 7200 seconds + + <tag>transport tcp</tag> Unprotected transport over TCP. It's a default + transport. Should be used only on secure private networks. + Default: tcp + + <tag>transport ssh { <m/SSH transport options.../ }</tag> It enables a + SSHv2 transport encryption. Cannot be combined with a TCP transport. + Default: off +</descrip> + +<sect3>SSH transport options +<descrip> + <tag>bird private key "<m>/path/to/id_rsa</m>"</tag> + A path to the BIRD's private SSH key for authentication. + It can be a <cf><m>id_rsa</m></cf> file. + + <tag>remote public key "<m>/path/to/known_host</m>"</tag> + A path to the cache's public SSH key for verification identity + of the cache server. It could be a path to <cf><m>known_host</m></cf> file. + + <tag>user "<m/name/"</tag> + A SSH user name for authentication. This option is a required. +</descrip> + +<sect1>Examples +<sect2>BGP origin validation +<p>Policy: Don't import <cf/ROA_INVALID/ routes. +<code> +roa4 table r4; +roa6 table r6; + +protocol rpki { + debug all; + + roa4 { table r4; }; + roa6 { table r6; }; + + # Please, do not use rpki-validator.realmv6.org in production + remote "rpki-validator.realmv6.org" port 8282; + + retry keep 5; + refresh keep 30; + expire 600; +} + +filter peer_in { + if (roa_check(r4, net, bgp_path.last) = ROA_INVALID || + roa_check(r6, net, bgp_path.last) = ROA_INVALID) then + { + print "Ignore invalid ROA ", net, " for ASN ", bgp_path.last; + reject; + } + accept; +} + +protocol bgp { + debug all; + local as 65000; + neighbor 192.168.2.1 as 65001; + import filter peer_in; +} +</code> + +<sect2>SSHv2 transport encryption +<code> +roa4 table r4; +roa6 table r6; + +protocol rpki { + debug all; + + roa4 { table r4; }; + roa6 { table r6; }; + + remote 127.0.0.1 port 2345; + transport ssh { + bird private key "/home/birdgeek/.ssh/id_rsa"; + remote public key "/home/birdgeek/.ssh/known_hosts"; + user "birdgeek"; + }; + + # Default interval values +} +</code> + + <sect>Static <label id="static"> @@ -3841,12 +4204,12 @@ return packets as undeliverable if they are in your IP block, you don't have any specific destination for them and you don't want to send them out through the default route to prevent routing loops). -<p>There are five types of static routes: `classical' routes telling to forward -packets to a neighboring router, multipath routes specifying several (possibly -weighted) neighboring routers, device routes specifying forwarding to hosts on a -directly connected network, recursive routes computing their nexthops by doing -route table lookups for a given IP, and special routes (sink, blackhole etc.) -which specify a special action to be done instead of forwarding the packet. +<p>There are four types of static routes: `classical' routes telling to forward +packets to a neighboring router (single path or multipath, possibly weighted), +device routes specifying forwarding to hosts on a directly connected network, +recursive routes computing their nexthops by doing route table lookups for a +given IP, and special routes (sink, blackhole etc.) which specify a special +action to be done instead of forwarding the packet. <p>When the particular destination is not available (the interface is down or the next hop of the route is not a neighbor at the moment), Static just @@ -3875,14 +4238,14 @@ definition of the protocol contains mainly a list of static routes. <p>Route definitions (each may also contain a block of per-route options): <descrip> - <tag><label id="static-route-via-ip">route <m/prefix/ via <m/ip/</tag> - Static route through a neighboring router. For link-local next hops, + <tag><label id="static-route-via-ip">route <m/prefix/ via <m/ip/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]]</tag> + Static single path route through a neighboring router. For link-local next hops, interface can be specified as a part of the address (e.g., - <cf/via fe80::1234%eth0/). + <cf/via fe80::1234%eth0/). MPLS labels should be specified in outer-first order. - <tag><label id="static-route-via-mpath">route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [bfd <m/switch/] [via <m/.../]</tag> + <tag><label id="static-route-via-mpath">route <m/prefix/ via <m/ip/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]] [weight <m/num/] [bfd <m/switch/] [via ...]</tag> Static multipath route. Contains several nexthops (gateways), possibly - with their weights. + with their weights and MPLS labels. <tag><label id="static-route-via-iface">route <m/prefix/ via <m/"interface"/</tag> Static device route through an interface to hosts on a directly diff --git a/doc/sgml2html b/doc/sgml2html index 774a03d5..a5bbee9e 100755 --- a/doc/sgml2html +++ b/doc/sgml2html @@ -17,8 +17,10 @@ use strict; use vars qw($prefix $DataDir $BinDir $progs); +use FindBin; + $prefix = "/usr"; -$DataDir = "sbase"; +$DataDir = "$FindBin::Bin/sbase"; $BinDir = "/usr/bin"; use lib "/usr/share/linuxdoc-tools"; @@ -32,9 +34,9 @@ $progs = { "GROFFMACRO" => "-ms", "AWK" => "/usr/share/linuxdoc-tools/awkwhich" }; -$ENV{"SGML_CATALOG_FILES"} = "sbase/dtd/catalog"; +$ENV{"SGML_CATALOG_FILES"} = "$DataDir/dtd/catalog"; -require "./LinuxDocTools.pm"; +require "$FindBin::Bin/LinuxDocTools.pm"; &LinuxDocTools::init; my @FileList = LinuxDocTools::process_options ("html", @ARGV); diff --git a/doc/sgml2latex b/doc/sgml2latex index 27aae4c8..02b60d94 100755 --- a/doc/sgml2latex +++ b/doc/sgml2latex @@ -17,8 +17,10 @@ use strict; use vars qw($prefix $DataDir $BinDir $progs); +use FindBin; + $prefix = "/usr"; -$DataDir = "sbase"; +$DataDir = "$FindBin::Bin/sbase"; $BinDir = "/usr/bin"; use lib "/usr/share/linuxdoc-tools"; @@ -32,9 +34,9 @@ $progs = { "GROFFMACRO" => "-ms", "AWK" => "/usr/share/linuxdoc-tools/awkwhich" }; -$ENV{"SGML_CATALOG_FILES"} = "sbase/dtd/catalog"; +$ENV{"SGML_CATALOG_FILES"} = "$DataDir/dtd/catalog"; -require "./LinuxDocTools.pm"; +require "$FindBin::Bin/LinuxDocTools.pm"; &LinuxDocTools::init; my @FileList = LinuxDocTools::process_options ("latex", @ARGV); diff --git a/doc/sgml2txt b/doc/sgml2txt index 90dc4855..dfc017de 100755 --- a/doc/sgml2txt +++ b/doc/sgml2txt @@ -17,8 +17,10 @@ use strict; use vars qw($prefix $DataDir $BinDir $progs); +use FindBin; + $prefix = "/usr"; -$DataDir = "sbase"; +$DataDir = "$FindBin::Bin/sbase"; $BinDir = "/usr/bin"; use lib "/usr/share/linuxdoc-tools"; @@ -32,9 +34,9 @@ $progs = { "GROFFMACRO" => "-ms", "AWK" => "/usr/share/linuxdoc-tools/awkwhich" }; -$ENV{"SGML_CATALOG_FILES"} = "sbase/dtd/catalog"; +$ENV{"SGML_CATALOG_FILES"} = "$DataDir/dtd/catalog"; -require "./LinuxDocTools.pm"; +require "$FindBin::Bin/LinuxDocTools.pm"; &LinuxDocTools::init; my @FileList = LinuxDocTools::process_options ("txt", @ARGV); |