Buff; also, specify router-id per rfc6286.

MPLS VPN cluesticks supplied by Dylan Hall
ok claudio@ jmc@

1 files changed, 128 insertions, 139 deletions

diff --git a/usr.sbin/bgpd/bgpd.conf.5 b/usr.sbin/bgpd/bgpd.conf.5
index 7bd49fca739..5c0d11ef548 100644
--- a/usr.sbin/bgpd/bgpd.conf.5
+++ b/usr.sbin/bgpd/bgpd.conf.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bgpd.conf.5,v 1.195 2019/08/28 20:12:02 procter Exp $
+.\" $OpenBSD: bgpd.conf.5,v 1.196 2019/10/04 19:51:27 procter Exp $
 .\"
 .\" Copyright (c) 2004 Claudio Jeker <claudio@openbsd.org>
 .\" Copyright (c) 2003, 2004 Henning Brauer <henning@openbsd.org>
@@ -16,7 +16,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 28 2019 $
+.Dd $Mdocdate: October 4 2019 $
 .Dt BGPD.CONF 5
 .Os
 .Sh NAME
@@ -32,27 +32,27 @@ The
 .Nm
 config file is divided into the following main sections:
 .Bl -tag -width xxxx
-.It Sy Macros
+.It Sx MACROS
 User-defined variables may be defined and used later, simplifying the
 configuration file.
-.It Sy Global Configuration
+.It Sx GLOBAL CONFIGURATION
 Global settings for
 .Xr bgpd 8 .
-.It Sy Set Configuration
+.It Sx SET CONFIGURATION
 Various lookup tables are defined in this section.
-.It Sy Network Announcements
+.It Sx NETWORK ANNOUNCEMENTS
 Networks which should be announced by
 .Xr bgpd 8
 are set in this section.
-.It Sy MPLS VPN Configuration
+.It Sx MPLS VPN CONFIGURATION
 The definition and properties for BGP MPLS VPNs are set in this section.
-.It Sy Neighbors and Groups
+.It Sx NEIGHBORS AND GROUPS
 .Xr bgpd 8
 establishes sessions with
 .Em neighbors .
 The neighbor definition and properties are set in this section, as well as
 grouping neighbors for the ease of configuration.
-.It Sy Filter
+.It Sx FILTER
 Filter rules for incoming and outgoing
 .Em UPDATES .
 .El
@@ -110,7 +110,7 @@ number to
 .Ar as-number .
 A fallback 2-byte AS number may follow a 4-byte AS number for neighbors that
 do not support 4-byte AS numbers.
-The standard and default fallback AS is 23456.
+The standard and default fallback AS number is 23456.
 .Pp
 The AS numbers are assigned by local RIRs, such as:
 .Pp
@@ -133,6 +133,7 @@ The AS number 23456 is reserved and should not be used.
 .Bd -literal -offset indent
 AS 196618
 .Ed
+.Pp
 or in the older ASDOT format:
 .Bd -literal -offset indent
 AS 3.10
@@ -158,15 +159,19 @@ The default is 120 seconds.
 .Xc
 Dump the RIB, a.k.a. the
 .Em routing information base ,
-or dump BGP activity, in Multi-threaded Routing Toolkit (MRT) format.
+or dump ongoing BGP activity, in Multi-threaded Routing Toolkit (MRT) format.
+The
+.Ar file
+is subject to
+.Xr strftime 3 Ns -expansion.
 .Pp
 The
 .Ic table-v2
 and
 .Ic table-mp
-formats store multi-protocol RIBs correctly, but the
+RIB formats store multi-protocol RIBs correctly, but the
 .Ic table
-RIB format does not.
+format does not.
 The latter two are provided only to support third-party tools lacking
 support for the recommended
 .Ic table-v2
@@ -177,33 +182,24 @@ Specify an
 .Ar interval
 in seconds for periodic RIB dumps.
 .Pp
-The following will dump the entire RIB table to the
-.Xr strftime 3 Ns -expanded
-filename at startup and every 5 minutes thereafter:
+The following will dump the entire RIB table, at startup and every
+5 minutes thereafter, to a new file:
 .Bd -literal -offset indent
 dump table-v2 "/tmp/rib-dump-%H%M" 300
 .Ed
 .Pp
-The following will instead dump all BGP
-.Em state transitions
-and received BGP messages to the specified filename for 5 minutes before
-restarting with a new file:
-.Bd -literal -offset indent
-dump all in "/tmp/all-in-%H%M" 300
-.Ed
-.Pp
-Dumps can be limited to the BGP
+Dumps of ongoing BGP activity include all BGP state transitions, and
+all BGP messages in the specified direction.
+Use
+.Ic updates
+to dump only BGP
 .Em UPDATE
-messages alone:
-.Bd -literal -offset indent
-dump updates in "/tmp/updates-in-%H%M" 300
-.Ed
-.Pp
-Specify
-.Ic out
-to dump all outgoing BGP messages:
+messages, without state transitions.
+Specify an
+.Ar interval
+in seconds to restart periodically with a new file:
 .Bd -literal -offset indent
-dump all out "/tmp/all-out-%H%M" 300
+dump all in "/tmp/all-in-%H%M" 300
 .Ed
 .Pp
 .It Ic fib-priority Ar prio
@@ -224,16 +220,17 @@ The default is
 .Pp
 .It Ic holdtime Ar seconds
 Set the announced holdtime in seconds.
-This is exchanged with neighboring systems upon connection
+This is exchanged with a neighbor upon connection
 establishment, in the
 .Em OPEN
 message, and the shortest holdtime governs the session.
 .Pp
-The neighbor session is dropped whenever a
+The neighbor session is dropped if the session holdtime passes
+without receipt of a
 .Em KEEPALIVE
 or an
 .Em UPDATE
-message has not been received from the neighbor within the session holdtime.
+message from the neighbor.
 The default is 90 seconds.
 .Pp
 .It Ic holdtime min Ar seconds
@@ -301,8 +298,8 @@ The degree to which its routes may be utilized is configurable.
 They may be excluded from the decision process that selects usable routes
 with the
 .Ic no Ic evaluate
-flag, and never be exported to any kernel routing table.
-By default, its routes will be evaluated but never exported to the kernel.
+flag, and this precludes their export to any kernel routing table.
+By default its routes will be evaluated, but not exported to the kernel.
 They may be both evaluated and exported if associated with a given
 .Ic rtable
 .Ar number ,
@@ -333,10 +330,10 @@ This renders the decision process nondeterministic.
 The default is
 .Ic ignore .
 .Pp
-.It Ic router-id Ar address
-Set the BGP router ID to the given IP address, which should be local to the
-machine.
-By default, the router ID is the highest IP address assigned
+.It Ic router-id Ar dotted-quad
+Set the BGP router ID, which must be non-zero and should be unique
+within the AS.
+By default, the router ID is the highest IPv4 address assigned
 to the local machine.
 .Bd -literal -offset indent
 router-id 10.0.0.1
@@ -485,14 +482,16 @@ roa-set { 192.0.2.0/24 maxlen 24 source-as 64511
 .Ed
 .El
 .Sh NETWORK ANNOUNCEMENTS
-To announce a specific network as belonging to our AS, a
 .Ic network
-statement is used.
+statements specify the networks that
+.Xr bgpd 8
+will announce as its own.
+An announcement must also be permitted by the
+.Sx FILTER
+rules.
 By default
 .Xr bgpd 8
-will not announce anything.
-Filter rules need to be in place to allow announcement of the right prefixes
-to each neighbor.
+announces no networks.
 .Pp
 .Bl -tag -width Ds -compact
 .It Xo
@@ -514,16 +513,15 @@ Announce routes to directly attached networks.
 .Ar name
 .Op Ic set ...\&
 .Xc
-All networks in the prefix-set
-.Ar name
-will be announced.
+Announce all networks in the prefix-set
+.Ar name .
 .Pp
 .It Xo
 .Ic network
 .Pq Ic inet Ns | Ns Ic inet6
 .Ic priority Ar number Op Ic set ...\&
 .Xc
-Announce routes with the specified
+Announce routes having the specified
 .Ar priority .
 .Pp
 .It Xo
@@ -531,7 +529,7 @@ Announce routes with the specified
 .Pq Ic inet Ns | Ns Ic inet6
 .Ic rtlabel Ar label Op Ic set ...\&
 .Xc
-Announce routes with the specified
+Announce routes having the specified
 .Ar label .
 .Pp
 .It Xo
@@ -542,11 +540,10 @@ Announce routes with the specified
 Announce all static routes.
 .El
 .Pp
-It is possible to set default
-.Em AS path attributes
-per
+Each
 .Ic network
-statement:
+statement may set default
+.Em AS path attributes :
 .Bd -literal -offset indent
 network 192.168.7.0/24 set localpref 220
 .Ed
@@ -555,16 +552,12 @@ See also the
 .Sx ATTRIBUTE SET
 section.
 .Sh MPLS VPN CONFIGURATION
-.Xr bgpd 8
-supports the setup and distribution of MPLS Virtual Private Networks.
-A router can be configured to participate in a VPN by specifying a
+A
 .Ic vpn
-section with a description for the VPN and an
+section configures a router to participate in an MPLS Virtual Private Network.
+It specifies an
 .Xr mpe 4
-interface.
-.Pp
-The vpn configuration section allows properties to be set specifically
-for that VPN:
+interface to use, a description, and various properties of the VPN:
 .Bd -literal -offset indent
 vpn "description" on mpe1 {
 	rd 65002:1
@@ -574,6 +567,10 @@ vpn "description" on mpe1 {
 }
 .Ed
 .Pp
+.Xr bgpd 8
+will not exchange VPN routes with a neighbor by default, see the
+.Sx NEIGHBORS AND GROUPS
+section.
 The description is used when logging but has no further meaning to
 .Xr bgpd 8 .
 .Pp
@@ -603,23 +600,26 @@ inet 192.198.0.1 255.255.255.255
 up
 .Ed
 .Pp
-There are several VPN properties:
+The VPN properties are as follows:
 .Pp
 .Bl -tag -width Ds -compact
 .It Ic export-target Ar subtype Ar as-number : Ns Ar local
 .It Ic export-target Ar subtype Ar IP : Ns Ar local
-Specify an extended community which will be attached to announced networks.
+Classify announced networks by tagging them with an
+.Em extended community
+of the given arguments.
+The community
+.Ar subtype
+should be a
+.Em route target ,
+.Ic rt ,
+to ensure interoperability.
+The arguments are further detailed in the
+.Sx ATTRIBUTE SET
+section.
 More than one
 .Ic export-target
 can be specified.
-See also the
-.Sx ATTRIBUTE SET
-section for further information about the encoding.
-The
-.Ar subtype
-should be set to
-.Ar rt
-for best compatibility with other implementations.
 .Pp
 .It Xo
 .Ic fib-update
@@ -634,46 +634,47 @@ The default is
 .Pp
 .It Ic import-target Ar subtype Ar as-number : Ns Ar local
 .It Ic import-target Ar subtype Ar IP : Ns Ar local
-Only prefixes matching one of the specified
-.Ic import-targets
-will be imported into the rdomain.
+The rdomain imports only those prefixes tagged with an
+.Em extended community
+matching an
+.Ic import-target .
+The community
+.Ar subtype
+should be a
+.Em route target ,
+.Ic rt ,
+to ensure interoperability.
+The arguments are further detailed in the
+.Sx ATTRIBUTE SET
+section.
 More than one
 .Ic import-target
 can be specified.
-See also the
-.Sx ATTRIBUTE SET
-section for further information about the encoding of extended communities.
-The
-.Ar subtype
-should be set to
-.Ar rt
-for best compatibility with other implementations.
 .Pp
 .It Ic network Ar arguments ...
-Define which networks should be exported into this VPN.
-See also the
-.Ic nexthop
-section in
-.Sx GLOBAL CONFIGURATION
-for further information about the arguments.
+Announce the given networks within this VPN;
+see the
+.Sx NETWORK ANNOUNCEMENTS
+section.
 .Pp
 .It Ic rd Ar as-number : Ns Ar local
 .It Ic rd Ar IP : Ns Ar local
-The sole purpose of the Route Distinguisher
+The Route Distinguisher
 .Ic rd
-is to ensure that possible common prefixes are distinct between VPNs.
-The
+supplies BGP with namespaces to disambiguate VPN prefixes, as these needn't be
+globally unique.
+Unlike route targets, the
 .Ic rd
-is neither used to identify the origin of the prefix nor to control into
-which VPNs the prefix is distributed to.
+neither identifies the origin of the prefix nor controls into
+which VPNs the prefix is distributed.
 The
 .Ar as-number
 or
 .Ar IP
 of a
 .Ic rd
-should be set to a number or IP that was assigned by an appropriate authority.
-Whereas
+should be set to a number or IP that was assigned by an appropriate authority,
+whereas
 .Ar local
 can be chosen by the local operator.
 .El
@@ -681,9 +682,9 @@ can be chosen by the local operator.
 .Xr bgpd 8
 establishes TCP connections to other BGP speakers called
 .Em neighbors .
-Each neighbor is specified by a
+A neighbor and its properties are specified by a
 .Ic neighbor
-section, which allows properties to be set specifically for that neighbor:
+section:
 .Bd -literal -offset indent
 neighbor 10.0.0.2 {
 	remote-as 65002
@@ -691,14 +692,9 @@ neighbor 10.0.0.2 {
 }
 .Ed
 .Pp
-Multiple neighbors can be grouped together by a
-.Ic group
-section.
-Each
-.Ic neighbor
-section within the
+Neighbors placed within a
 .Ic group
-section inherits all properties from its group:
+section inherit the properties common to that group:
 .Bd -literal -offset indent
 group "peering AS65002" {
 	remote-as 65002
@@ -711,26 +707,24 @@ group "peering AS65002" {
 }
 .Ed
 .Pp
-Instead of the neighbor's IP address, an address/netmask pair may be given:
+An entire network of neighbors may be accommodated by specifying an
+address/netmask pair:
 .Bd -literal -offset indent
 neighbor 10.0.0.0/8
 .Ed
 .Pp
-In this case, the neighbor specification becomes a
-.Em template ,
-and if a neighbor connects from an IP address within the given network,
-the template is
-.Em cloned ,
-inheriting everything from the template but the remote address, which is
-replaced by the connecting neighbor's address.
-With a template specification it is valid to omit
+This is a
+.Em template
+that recognises as a neighbor any connection from within the given network.
+Such neighbors inherit their template's properties, except for their IP address.
+A template may omit
 .Ic remote-as ;
 .Xr bgpd 8
-will then accept any AS the neighbor presents in the
+then accepts any AS presented by the neighbor in the
 .Em OPEN
 message.
 .Pp
-There are several neighbor properties:
+The neighbor properties are as follows:
 .Pp
 .Bl -tag -width Ds -compact
 .It Xo
@@ -738,17 +732,18 @@ There are several neighbor properties:
 .Pq Ic IPv4 Ns | Ns Ic IPv6
 .Pq Ic none Ns | Ns Ic unicast Ns | Ns Ic vpn
 .Xc
-For the given address family, control which subsequent address families
+For the given address family, control which
+.Em subsequent address families
 are announced during the capabilities negotiation.
 Only routes for that address family and subsequent address families will be
 announced and processed.
 .Pp
 At the moment, only
-.Em none ,
+.Ic none ,
 which disables the announcement of that address family,
-.Em unicast ,
+.Ic unicast ,
 and
-.Em vpn ,
+.Ic vpn ,
 which allows the distribution of BGP MPLS VPNs, are supported.
 .Pp
 The default is
@@ -881,16 +876,12 @@ cannot exceed 128 octets.
 .Ic dump
 .Pq Ic all Ns | Ns Ic updates
 .Pq Ic in Ns | Ns Ic out
-.Ar file Op Ar timeout
+.Ar file Op Ar interval
 .Xc
-Do a peer specific MRT dump.
-Peer specific dumps are limited to
-.Ic all
-and
-.Ic updates .
+Dump ongoing BGP activity for a particular neighbor.
 See also the
 .Ic dump
-section in
+setting in
 .Sx GLOBAL CONFIGURATION .
 .Pp
 .It Xo
@@ -1153,18 +1144,15 @@ The default is
 .El
 .Sh FILTER
 .Xr bgpd 8
-has the ability to
-.Ic allow
-and
-.Ic deny
-.Em UPDATES
-based on
+filters all BGP
+.Em UPDATE
+messages, including its own announcements, and blocks them by default.
+Filter rules may match on neighbor, direction,
 .Em prefix
 or
 .Em AS path attributes .
-In addition,
-.Em UPDATES
-may also be modified by filter rules.
+Filter rules may also modify
+.Em AS path attributes .
 .Pp
 For each
 .Em UPDATE
@@ -1890,6 +1878,7 @@ configuration file
 .Xr strftime 3 ,
 .Xr ipsec 4 ,
 .Xr pf 4 ,
+.Xr rdomain 4 ,
 .Xr tcp 4 ,
 .Xr bgpctl 8 ,
 .Xr bgpd 8 ,