2005-11-04 Paul Jakma <paul.jakma@sun.com>
* quagga.info: Update auto-built file
* ospf6d.texi: Add example config
* bgpd.texi: Add example configs. Couple of cleanups of format
and macros.
* routemap.texi: Add an explanation of how route-maps work.
Document the call and exit-policy commands.
diff --git a/doc/bgpd.texi b/doc/bgpd.texi
index 43d9702..a9c4810 100644
--- a/doc/bgpd.texi
+++ b/doc/bgpd.texi
@@ -5,15 +5,15 @@
@node BGP
@chapter BGP
- BGP stands for a Border Gateway Protocol. The lastest BGP version
+@acronym{BGP} stands for a Border Gateway Protocol. The lastest BGP version
is 4. It is referred as BGP-4. BGP-4 is one of the Exterior Gateway
Protocols and de-fact standard of Inter Domain routing protocol.
-BGP-4 is described in @code{RFC1771} - @cite{A Border Gateway Protocol
+BGP-4 is described in @cite{RFC1771, A Border Gateway Protocol
4 (BGP-4)}.
- Many extentions are added to @code{RFC1771}. @code{RFC2858} -
-@cite{Multiprotocol Extensions for BGP-4} provide multiprotocol
-support to BGP-4.
+Many extensions have been added to @cite{RFC1771}. @cite{RFC2858,
+Multiprotocol Extensions for BGP-4} provides multiprotocol support to
+BGP-4.
@menu
* Starting BGP::
@@ -31,6 +31,7 @@
* Route Server::
* How to set up a 6-Bone connection::
* Dump BGP packets and table::
+* BGP Configuration Examples::
@end menu
@node Starting BGP
@@ -338,16 +339,16 @@
@node Autonomous System
@section Autonomous System
- AS (Autonomous System) is one of the essential element of BGP. BGP
-is a distance vector routing protocol. AS framework provides distance
-vector metric and loop detection to BGP. @code{RFC1930} -
-@cite{Guidelines for creation, selection, and registration of an
-Autonomous System (AS)} describes how to use AS.
+The @acronym{AS,Autonomous System} number is one of the essential
+element of BGP. BGP is a distance vector routing protocol, and the
+AS-Path framework provides distance vector metric and loop detection to
+BGP. @cite{RFC1930, Guidelines for creation, selection, and
+registration of an Autonomous System (AS)} provides some background on
+the concepts of an AS.
- AS number is tow octet digita value. So the value range is from 1
-to 65535. AS numbers 64512 through 65535 are defined as private AS
-numbers. Private AS numbers must not to be advertised in the global
-Internet.
+The AS number is a two octet value, ranging in value from 1 to 65535.
+The AS numbers 64512 through 65535 are defined as private AS numbers.
+Private AS numbers must not to be advertised in the global Internet.
@menu
* AS Path Regular Expression::
@@ -360,7 +361,7 @@
@node AS Path Regular Expression
@subsection AS Path Regular Expression
- AS path regular expression can be used for displaying BGP routes and
+AS path regular expression can be used for displaying BGP routes and
AS path access list. AS path regular expression is based on
@code{POSIX 1003.2} regular expressions. Following description is
just a subset of @code{POSIX} regular expression. User can use full
@@ -392,7 +393,7 @@
@node Display BGP Routes by AS Path
@subsection Display BGP Routes by AS Path
- To show BGP routes which has specific AS path information @code{show
+To show BGP routes which has specific AS path information @code{show
ip bgp} command can be used.
@deffn Command {show ip bgp regexp @var{line}} {}
@@ -403,7 +404,7 @@
@node AS Path Access List
@subsection AS Path Access List
- AS path access list is user defined AS path.
+AS path access list is user defined AS path.
@deffn {Command} {ip as-path access-list @var{word} @{permit|deny@} @var{line}} {}
This command defines a new AS path access list.
@@ -429,15 +430,15 @@
@node BGP Communities Attribute
@section BGP Communities Attribute
- BGP communities attribute is widely used for implementing policy
+BGP communities attribute is widely used for implementing policy
routing. Network operators can manipulate BGP communities attribute
based on their network policy. BGP communities attribute is defined
-in @code{RFC1997} - @cite{BGP Communities Attribute} and
-@code{RFC1998} - @cite{An Application of the BGP Community Attribute
+in @cite{RFC1997, BGP Communities Attribute} and
+@cite{RFC1998, An Application of the BGP Community Attribute
in Multi-home Routing}. It is an optional transitive attribute,
therefore local policy can travel through different autonomous system.
- Communities attribute is a set of communities values. Each
+Communities attribute is a set of communities values. Each
communities value is 4 octet long. The following format is used to
define communities value.
@@ -487,7 +488,7 @@
BGP community list can be used for matching or manipulating BGP
communities attribute in updates.
- There are two types of community list. One is standard community
+There are two types of community list. One is standard community
list and another is expanded community list. Standard community list
defines communities attribute. Expanded community list defines
communities attribute string with regular expression. Standard
@@ -545,7 +546,7 @@
@node Numbered BGP Community Lists
@subsection Numbered BGP Community Lists
- When number is used for BGP community list name, the number has
+When number is used for BGP community list name, the number has
special meanings. Community list number in the range from 1 and 99 is
standard community list. Community list number in the range from 100
to 199 is expanded community list. These community lists are called
@@ -577,11 +578,11 @@
@node BGP Community in Route Map
@subsection BGP Community in Route Map
- In Route Map (@pxref{Route Map}), we can match or set BGP
+In Route Map (@pxref{Route Map}), we can match or set BGP
communities attribute. Using this feature network operator can
implement their network policy based on BGP communities attribute.
- Following commands can be used in Route Map.
+Following commands can be used in Route Map.
@deffn {Route Map} {match community @var{word}} {}
@deffnx {Route Map} {match community @var{word} exact-match} {}
@@ -617,7 +618,7 @@
@node Display BGP Routes by Community
@subsection Display BGP Routes by Community
- To show BGP routes which has specific BGP communities attribute,
+To show BGP routes which has specific BGP communities attribute,
@code{show ip bgp} command can be used. The @var{community} value and
community list can be used for @code{show ip bgp} command.
@@ -642,7 +643,7 @@
@node Using BGP Communities Attribute
@subsection Using BGP Communities Attribute
- Following configuration is the most typical usage of BGP communities
+Following configuration is the most typical usage of BGP communities
attribute. AS 7675 provides upstream Internet connection to AS 100.
When following configuration exists in AS 7675, AS 100 networks
operator can set local preference in AS 7675 network by setting BGP
@@ -673,7 +674,7 @@
set local-preference 90
@end example
- Following configuration announce 10.0.0.0/8 from AS 100 to AS 7675.
+Following configuration announce 10.0.0.0/8 from AS 100 to AS 7675.
The route has communities value 7675:80 so when above configuration
exists in AS 7675, announced route's local preference will be set to
value 80.
@@ -691,7 +692,7 @@
set community 7675:80
@end example
- Following configuration is an example of BGP route filtering using
+Following configuration is an example of BGP route filtering using
communities attribute. This configuration only permit BGP routes
which has BGP communities value 0:80 or 0:90. Network operator can
put special internal communities value at BGP border router, then
@@ -708,7 +709,7 @@
match community 1
@end example
- Following exmaple filter BGP routes which has communities value 1:1.
+Following exmaple filter BGP routes which has communities value 1:1.
When there is no match community-list returns deny. To avoid
filtering all of routes, we need to define permit any at last.
@@ -724,7 +725,7 @@
match community FILTER
@end example
- Communities value keyword @code{internet} has special meanings in
+Communities value keyword @code{internet} has special meanings in
standard community lists. In below example @code{internet} act as
match any. It matches all of BGP routes even if the route does not
have communities attribute at all. So community list @code{INTERNET}
@@ -735,7 +736,7 @@
ip community-list standard INTERNET permit internet
@end example
- Following configuration is an example of communities value deletion.
+Following configuration is an example of communities value deletion.
With this configuration communities value 100:1 and 100:2 is removed
from BGP updates. For communities value deletion, only @code{permit}
community-list is used. @code{deny} community-list is ignored.
@@ -755,23 +756,23 @@
@node BGP Extended Communities Attribute
@section BGP Extended Communities Attribute
- BGP extended communities attribute is introduced with MPLS VPN/BGP
+BGP extended communities attribute is introduced with MPLS VPN/BGP
technology. MPLS VPN/BGP expands capability of network infrastructure
to provide VPN functionality. At the same time it requires a new
framework for policy routing. With BGP Extended Communities Attribute
we can use Route Target or Site of Origin for implementing network
policy for MPLS VPN/BGP.
- BGP Extended Communities Attribute is similar to BGP Communities
+BGP Extended Communities Attribute is similar to BGP Communities
Attribute. It is an optional transitive attribute. BGP Extended
Communities Attribute can carry multiple Extended Community value.
Each Extended Community value is eight octet length.
- BGP Extended Communities Attribute provides an extended range
+BGP Extended Communities Attribute provides an extended range
compared with BGP Communities Attribute. Adding to that there is a
type field in each value to provides community space structure.
- There are two format to define Extended Community value. One is AS
+There are two format to define Extended Community value. One is AS
based format the other is IP address based format.
@table @code
@@ -795,7 +796,7 @@
@node BGP Extended Community Lists
@subsection BGP Extended Community Lists
- Expanded Community Lists is a user defined BGP Expanded Community
+Expanded Community Lists is a user defined BGP Expanded Community
Lists.
@deffn Command {ip extcommunity-list standard @var{name} @{permit|deny@} @var{extcommunity}} {}
@@ -937,35 +938,38 @@
@node Capability Negotiation
@section Capability Negotiation
- When adding IPv6 routing information exchange feature to BGP. There
-were some proposals. @acronym{IETF} @acronym{IDR} working group finally
-take a proposal called Multiprotocol Extension for BGP. The
-specification is described in RFC2283. The protocol does not define new
-protocols. It defines new attributes to existing BGP. When it is used
-exchanging IPv6 routing information it is called BGP-4+. When it is
-used for exchanging multicast routing information it is called MBGP.
+When adding IPv6 routing information exchange feature to BGP. There
+were some proposals. @acronym{IETF,Internet Engineering Task Force}
+@acronym{IDR, Inter Domain Routing} @acronym{WG, Working group} adopted
+a proposal called Multiprotocol Extension for BGP. The specification
+is described in @cite{RFC2283}. The protocol does not define new protocols.
+It defines new attributes to existing BGP. When it is used exchanging
+IPv6 routing information it is called BGP-4+. When it is used for
+exchanging multicast routing information it is called MBGP.
- @command{bgpd} supports Multiprotocol Extension for BGP. So if remote peer
-supports the protocol, @command{bgpd} can exchange IPv6 and/or multicast routing
-information.
+@command{bgpd} supports Multiprotocol Extension for BGP. So if remote
+peer supports the protocol, @command{bgpd} can exchange IPv6 and/or
+multicast routing information.
- Traditional BGP does not have the feature to detect remote peer's
-capability whether it can handle other than IPv4 unicast routes. This
-is a big problem using Multiprotocol Extension for BGP to operational
-network. @cite{draft-ietf-idr-bgp4-cap-neg-04.txt} is proposing a
-feature called Capability Negotiation. @command{bgpd} use this Capability
-Negotiation to detect remote peer's capabilities. If the peer is only
-configured as IPv4 unicast neighbor, @command{bgpd} does not send these Capability
-Negotiation packets.
+Traditional BGP did not have the feature to detect remote peer's
+capabilities, e.g. whether it can handle prefix types other than IPv4
+unicast routes. This was a big problem using Multiprotocol Extension
+for BGP to operational network. @cite{RFC2842, Capabilities
+Advertisement with BGP-4} adopted a feature called Capability
+Negotiation. @command{bgpd} use this Capability Negotiation to detect
+the remote peer's capabilities. If the peer is only configured as IPv4
+unicast neighbor, @command{bgpd} does not send these Capability
+Negotiation packets (at least not unless other optional BGP features
+require capability negotation).
- By default, Quagga will bring up peering with minimal common capability
-for the both sides. For example, local router has unicast and multicast
-capabilitie and remote router has unicast capability. In this case,
-the local router will establish the connection with unicast only capability.
-When there are no common capabilities, Quagga sends Unsupported Capability
-error and then resets the connection.
+By default, Quagga will bring up peering with minimal common capability
+for the both sides. For example, local router has unicast and
+multicast capabilitie and remote router has unicast capability. In
+this case, the local router will establish the connection with unicast
+only capability. When there are no common capabilities, Quagga sends
+Unsupported Capability error and then resets the connection.
- If you want to completely match capabilities with remote peer. Please
+If you want to completely match capabilities with remote peer. Please
use @command{strict-capability-match} command.
@deffn {BGP} {neighbor @var{peer} strict-capability-match} {}
@@ -974,7 +978,7 @@
are different, send Unsupported Capability error then reset connection.
@end deffn
- You may want to disable sending Capability Negotiation OPEN message
+You may want to disable sending Capability Negotiation OPEN message
optional parameter to the peer when remote peer does not implement
Capability Negotiation. Please use @command{dont-capability-negotiate}
command to disable the feature.
@@ -986,14 +990,15 @@
other than IPv4 unicast configuration.
@end deffn
- When remote peer does not have capability negotiation feature, remote
-peer will not send any capabilities at all. In that case, bgp configures
-the peer with configured capabilities.
+When remote peer does not have capability negotiation feature, remote
+peer will not send any capabilities at all. In that case, bgp
+configures the peer with configured capabilities.
- You may prefer locally configured capabilities more than the negotiated
-capabilities even though remote peer sends capabilities. If the peer is
-configured by @command{override-capability}, @command{bgpd} ignores received
-capabilities then override negotiated capabilities with configured values.
+You may prefer locally configured capabilities more than the negotiated
+capabilities even though remote peer sends capabilities. If the peer
+is configured by @command{override-capability}, @command{bgpd} ignores
+received capabilities then override negotiated capabilities with
+configured values.
@deffn {BGP} {neighbor @var{peer} override-capability} {}
@deffnx {BGP} {no neighbor @var{peer} override-capability} {}
@@ -1016,7 +1021,7 @@
At an Internet Exchange point, many ISPs are connected to each other by
external BGP peering. Normally these external BGP connection are done by
-@code{full mesh} method. As with internal BGP full mesh formation,
+@samp{full mesh} method. As with internal BGP full mesh formation,
this method has a scaling problem.
This scaling problem is well known. Route Server is a method to resolve
@@ -1077,21 +1082,21 @@
configuration is specified community attribute and extended community
attribute are sent to neighbor. When user manually disable the
feature community attribute is not sent to the neighbor. In case of
-``bgp config-type cisco'' is specified, community attribute is not
+@command{bgp config-type cisco} is specified, community attribute is not
sent to the neighbor by default. To send community attribute user has
-to specify ``neighbor A.B.C.D send-community'' command.
+to specify @command{neighbor A.B.C.D send-community} command.
+@example
!
router bgp 1
neighbor 10.0.0.1 remote-as 1
no neighbor 10.0.0.1 send-community
!
-
-!
router bgp 1
neighbor 10.0.0.1 remote-as 1
neighbor 10.0.0.1 send-community
!
+@end example
@deffn {Command} {bgp config-type zebra} {}
Quagga style BGP configuration. This is default.
@@ -1247,3 +1252,233 @@
@deffnx Command {dump bgp routes @var{path}} {}
Dump whole BGP routing table to @var{path}. This is heavy process.
@end deffn
+
+@node BGP Configuration Examples
+@section BGP Configuration Examples
+
+Example of a session to an upstream, advertising only one prefix to it.
+
+@example
+router bgp 64512
+ bgp router-id 10.236.87.1
+ network 10.236.87.0/24
+ neighbor upstream peer-group
+ neighbor upstream remote-as 64515
+ neighbor upstream capability dynamic
+ neighbor upstream prefix-list pl-allowed-adv out
+ neighbor 10.1.1.1 peer-group upstream
+ neighbor 10.1.1.1 description ACME ISP
+!
+ip prefix-list pl-allowed-adv seq 5 permit 82.195.133.0/25
+ip prefix-list pl-allowed-adv seq 10 deny any
+
+@end example
+
+A more complex example. With upstream, peer and customer sessions.
+Advertising global prefixes and NO_EXPORT prefixes and providing
+actions for customer routes based on community values. Extensive use of
+route-maps and the 'call' feature to support selective advertising of
+prefixes. This example is intended as guidance only, it has NOT been
+tested and almost certainly containts silly mistakes, if not serious
+flaws.
+
+@example
+router bgp 64512
+ bgp router-id 10.236.87.1
+ network 10.123.456.0/24
+ network 10.123.456.128/25 route-map rm-no-export
+ neighbor upstream capability dynamic
+ neighbor upstream route-map rm-upstream-out out
+ neighbor cust capability dynamic
+ neighbor cust route-map rm-cust-in in
+ neighbor cust route-map rm-cust-out out
+ neighbor cust send-community both
+ neighbor peer capability dynamic
+ neighbor peer route-map rm-peer-in in
+ neighbor peer route-map rm-peer-out out
+ neighbor peer send-community both
+ neighbor 10.1.1.1 remote-as 64515
+ neighbor 10.1.1.1 peer-group upstream
+ neighbor 10.2.1.1 remote-as 64516
+ neighbor 10.2.1.1 peer-group upstream
+ neighbor 10.3.1.1 remote-as 64517
+ neighbor 10.3.1.1 peer-group cust-default
+ neighbor 10.3.1.1 description customer1
+ neighbor 10.3.1.1 prefix-list pl-cust1-network in
+ neighbor 10.4.1.1 remote-as 64518
+ neighbor 10.4.1.1 peer-group cust
+ neighbor 10.4.1.1 prefix-list pl-cust2-network in
+ neighbor 10.4.1.1 description customer2
+ neighbor 10.5.1.1 remote-as 64519
+ neighbor 10.5.1.1 peer-group peer
+ neighbor 10.5.1.1 prefix-list pl-peer1-network in
+ neighbor 10.5.1.1 description peer AS 1
+ neighbor 10.6.1.1 remote-as 64520
+ neighbor 10.6.1.1 peer-group peer
+ neighbor 10.6.1.1 prefix-list pl-peer2-network in
+ neighbor 10.6.1.1 description peer AS 2
+!
+ip prefix-list pl-default permit 0.0.0.0/0
+!
+ip prefix-list pl-upstream-peers permit 10.1.1.1/32
+ip prefix-list pl-upstream-peers permit 10.2.1.1/32
+!
+ip prefix-list pl-cust1-network permit 10.3.1.0/24
+ip prefix-list pl-cust1-network permit 10.3.2.0/24
+!
+ip prefix-list pl-cust2-network permit 10.4.1.0/24
+!
+ip prefix-list pl-peer1-network permit 10.5.1.0/24
+ip prefix-list pl-peer1-network permit 10.5.2.0/24
+ip prefix-list pl-peer1-network permit 192.168.0.0/24
+!
+ip prefix-list pl-peer2-network permit 10.6.1.0/24
+ip prefix-list pl-peer2-network permit 10.6.2.0/24
+ip prefix-list pl-peer2-network permit 192.168.1.0/24
+ip prefix-list pl-peer2-network permit 192.168.2.0/24
+ip prefix-list pl-peer2-network permit 172.16.1/24
+!
+ip as-path access-list asp-own-as permit ^$
+ip as-path access-list asp-own-as permit _64512_
+!
+! #################################################################
+! Match communities we provide actions for, on routes receives from
+! customers. Communities values of <our-ASN>:X, with X, have actions:
+!
+! 100 - blackhole the prefix
+! 200 - set no_export
+! 300 - advertise only to other customers
+! 400 - advertise only to upstreams
+! 500 - set no_export when advertising to upstreams
+! 2X00 - set local_preference to X00
+!
+! blackhole the prefix of the route
+ip community-list standard cm-blackhole permit 64512:100
+!
+! set no-export community before advertising
+ip community-list standard cm-set-no-export permit 64512:200
+!
+! advertise only to other customers
+ip community-list standard cm-cust-only permit 64512:300
+!
+! advertise only to upstreams
+ip community-list standard cm-upstream-only permit 64512:400
+!
+! advertise to upstreams with no-export
+ip community-list standard cm-upstream-noexport permit 64512:500
+!
+! set local-pref to least significant 3 digits of the community
+ip community-list standard cm-prefmod-100 permit 64512:2100
+ip community-list standard cm-prefmod-200 permit 64512:2200
+ip community-list standard cm-prefmod-300 permit 64512:2300
+ip community-list standard cm-prefmod-400 permit 64512:2400
+ip community-list expanded cme-prefmod-range permit 64512:2...
+!
+! Informational communities
+!
+! 3000 - learned from upstream
+! 3100 - learned from customer
+! 3200 - learned from peer
+!
+ip community-list standard cm-learnt-upstream permit 64512:3000
+ip community-list standard cm-learnt-cust permit 64512:3100
+ip community-list standard cm-learnt-peer permit 64512:3200
+!
+! ###################################################################
+! Utility route-maps
+!
+! These utility route-maps generally should not used to permit/deny
+! routes, i.e. they do not have meaning as filters, and hence probably
+! should be used with 'on-match next'. These all finish with an empty
+! permit entry so as not interfere with processing in the caller.
+!
+route-map rm-no-export permit 10
+ set community additive no-export
+route-map rm-no-export permit 20
+!
+route-map rm-blackhole permit 10
+ description blackhole, up-pref and ensure it cant escape this AS
+ set ip next-hop 127.0.0.1
+ set local-preference 10
+ set community additive no-export
+route-map rm-blackhole permit 20
+!
+! Set local-pref as requested
+route-map rm-prefmod permit 10
+ match community cm-prefmod-100
+ set local-preference 100
+route-map rm-prefmod permit 20
+ match community cm-prefmod-200
+ set local-preference 200
+route-map rm-prefmod permit 30
+ match community cm-prefmod-300
+ set local-preference 300
+route-map rm-prefmod permit 40
+ match community cm-prefmod-400
+ set local-preference 400
+route-map rm-prefmod permit 50
+!
+! Community actions to take on receipt of route.
+route-map rm-community-in permit 10
+ description check for blackholing, no point continuing if it matches.
+ match community cm-blackhole
+ call rm-blackhole
+route-map rm-community-in permit 20
+ match community cm-set-no-export
+ call rm-no-export
+ on-match next
+route-map rm-community-in permit 30
+ match community cme-prefmod-range
+ call rm-prefmod
+route-map rm-community-in permit 40
+!
+! #####################################################################
+! Community actions to take when advertising a route.
+! These are filtering route-maps,
+!
+! Deny customer routes to upstream with cust-only set.
+route-map rm-community-filt-to-upstream deny 10
+ match community cm-learnt-cust
+ match community cm-cust-only
+route-map rm-community-filt-to-upstream permit 20
+!
+! Deny customer routes to other customers with upstream-only set.
+route-map rm-community-filt-to-cust deny 10
+ match community cm-learnt-cust
+ match community cm-upstream-only
+route-map rm-community-filt-to-cust permit 20
+!
+! ###################################################################
+! The top-level route-maps applied to sessions. Further entries could
+! be added obviously..
+!
+! Customers
+route-map rm-cust-in permit 10
+ call rm-community-in
+ on-match next
+route-map rm-cust-in permit 20
+ set community additive 64512:3100
+route-map rm-cust-in permit 30
+!
+route-map rm-cust-out permit 10
+ call rm-community-filt-to-cust
+ on-match next
+route-map rm-cust-out permit 20
+!
+! Upstream transit ASes
+route-map rm-upstream-out permit 10
+ description filter customer prefixes which are marked cust-only
+ call rm-community-filt-to-upstream
+ on-match next
+route-map rm-upstream-out permit 20
+ description only customer routes are provided to upstreams/peers
+ match community cm-learnt-cust
+!
+! Peer ASes
+! outbound policy is same as for upstream
+route-map rm-peer-out permit 10
+ call rm-upstream-out
+!
+route-map rm-peer-in permit 10
+ set community additive 64512:3200
+@end example