path: root/net/openbgpd/files/patch-bgpd_bgpd.8

Index: bgpd/bgpd.8
===================================================================
RCS file: /home/cvs/private/hrs/openbgpd/bgpd/bgpd.8,v
retrieving revision 1.1.1.8
retrieving revision 1.10
diff -u -p -r1.1.1.8 -r1.10
--- bgpd/bgpd.8	14 Feb 2010 20:19:57 -0000	1.1.1.8
+++ bgpd/bgpd.8	13 Oct 2012 18:36:00 -0000	1.10
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bgpd.8,v 1.28 2009/01/13 23:01:36 sthen Exp $
+.\" $OpenBSD: bgpd.8,v 1.45 2012/08/24 20:13:03 jmc Exp $
 .\"
 .\" Copyright (c) 2003, 2004 Henning Brauer <henning@openbsd.org>
 .\"
@@ -14,7 +14,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: January 13 2009 $
+.Dd $Mdocdate: August 24 2012 $
 .Dt BGPD 8
 .Os
 .Sh NAME
@@ -24,12 +24,8 @@
 .Nm bgpd
 .Bk -words
 .Op Fl cdnv
-.Oo Xo
-.Fl D Ar macro Ns = Ns Ar value Oc
-.Xc
+.Op Fl D Ar macro Ns = Ns Ar value
 .Op Fl f Ar file
-.Op Fl r Ar path
-.Op Fl s Ar path
 .Ek
 .Sh DESCRIPTION
 .Nm
@@ -42,15 +38,106 @@ concerning
 with other BGP systems.
 .Nm
 uses the Border Gateway Protocol, Version 4,
-as described in RFC 1771.
-Please refer to that document for more information about BGP.
+as described in RFC 4271.
+.Pp
+BGP is an exterior gateway protocol using a multiple step decision process
+to find the best path.
+Advanced filtering can be used to influence the route
+decision for traffic engineering.
+The session engine of
+.Nm
+is responsible for maintaining the TCP session with each neighbor.
+Updates are passed to the Route Decision Engine (RDE) where the paths
+are filtered and used to compute a Routing Information Base (RIB).
+The parent process is responsible for keeping the RIB in sync with
+the kernel routing table.
+.Pp
+The route decision process selects the best path by evaluating all paths to
+the same destination.
+The decision process continues to the next step if paths have equal attributes.
+Paths that are less preferred are taken out of consideration until there is
+only one path left.
+.Bl -enum -width 42 -offset bula
+.It
+All paths with errors or loops are not eligible.
+.It
+Paths with an unreachable nexthop are not eligible.
+After this step all remaining paths are valid.
+.It
+The path with the highest
+.Em LOCAL_PREF
+is selected.
+.It
+The path with the shortest
+.Em AS path
+attribute is selected.
+.It
+The
+.Em ORIGIN
+attribute is compared.
+The order is IGP before EGP before incomplete origins.
+.It
+The path with the lowest
+.Em MULTI_EXIT_DISC
+metric is selected.
+Normally, this value is only considered when choosing between multiple
+routes sent by the same neighbouring AS.
+However, if
+.Dq Li rde med compare always
+is set in the configuration, the metric is compared for routes sent by any AS.
+.It
+Comparison of the BGP session type.
+Paths learned over an external (EBGP) session are preferred over those
+learned via an internal (IBGP) session.
+.It
+The path with the lowest local
+.Em weight
+is selected.
+.It
+If
+.Dq Li rde route-age evaluate
+is set then the oldest path is selected.
+.It
+The path coming from the neighbor with the lowest
+.Em BGP ID
+wins.
+If the
+.Em ORIGINATOR_ID
+attribute is present that value will be used in the comparison instead.
+.It
+The path with the shortest
+.Em CLUSTER_LIST
+attribute is selected.
+If it is not present then a length of 0 is used in the comparison.
+.It
+The path coming from the peer with the lowest IP address is selected.
+IPv4 sessions will be preferred over IPv6 ones.
+.It
+In case of locally announced prefixes
+.Nm
+will prefer statically set prefixes over dynamically inserted ones.
+.El
+.Pp
+Attributes set by filters can be used to tip the decision process to prefer
+particular paths over others.
+This can be achieved by changing the
+.Em localpref ,
+.Em med ,
+or
+.Em weight
+attributes.
+AS path prepending or changing the
+.Em med
+or
+.Em origin
+attribute can be used to influencing the routing behaviour on remote systems.
 .Pp
 .Nm
 is usually started at boot time, and can be enabled by
 setting the following in
-.Pa /etc/rc.conf.local :
+.Pa /etc/rc.conf :
 .Pp
-.Dl bgpd_flags=\&"\&"
+.Dl openbgpd_enable=\&"YES\&"
 .Pp
 See
 .Xr rc 8
@@ -117,25 +204,16 @@ Use
 .Ar file
 as the configuration file,
 instead of the default
-.Pa /etc/bgpd.conf .
+.Pa %%PREFIX%%/etc/bgpd.conf .
 .It Fl n
 Configtest mode.
 Only check the configuration file for validity.
-.It Fl r Ar path
-Open a second, restricted, control socket that
-.Xr bgpctl 8
-can use.
-Only
-.Em show
-requests are allowed on this socket.
-.It Fl s Ar path
-Use an alternate location for the default control socket.
 .It Fl v
 Produce more verbose output.
 .El
 .Sh FILES
 .Bl -tag -width "/var/run/bgpd.sockXXX" -compact
-.It Pa /etc/bgpd.conf
+.It Pa %%PREFIX%%/etc/bgpd.conf
 default
 .Nm
 configuration file
@@ -149,55 +227,144 @@ control socket
 .Xr bgpctl 8 ,
 .Xr bgplg 8 ,
 .Xr bgplgsh 8
+.Sh STANDARDS
 .Rs
-.%R RFC 1771
-.%T "A Border Gateway Protocol 4 (BGP-4)"
-.%D March 1995
-.Re
-.Rs
-.%R RFC 1997
-.%T "BGP Communities Attribute"
+.%A R. Chandra
+.%A P. Traina
+.%A "T. Li"
 .%D August 1996
+.%R RFC 1997
+.%T BGP Communities Attribute
 .Re
+.Pp
 .Rs
-.%R RFC 2385
-.%T "Protection of BGP Sessions via the TCP MD5 Signature Option"
+.%A A. Heffernan
 .%D August 1998
+.%R RFC 2385
+.%T Protection of BGP Sessions via the TCP MD5 Signature Option
 .Re
+.Pp
 .Rs
-.%R RFC 2796
-.%T "BGP Route Reflection - An Alternative to Full Mesh IBGP"
-.%D April 2000
+.%A P. Marques
+.%A F. Dupont
+.%D March 1999
+.%R RFC 2545
+.%T Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
 .Re
+.Pp
 .Rs
-.%R RFC 2918
-.%T "Route Refresh Capability for BGP-4"
+.%A E. Chen
 .%D September 2000
+.%R RFC 2918
+.%T Route Refresh Capability for BGP-4
 .Re
+.Pp
 .Rs
-.%R RFC 3392
-.%T "Capabilities Advertisement with BGP-4"
-.%D January 1999
+.%A G. Huston
+.%D April 2004
+.%R RFC 3765
+.%T NOPEER Community for Border Gateway Protocol (BGP) Route Scope Control
 .Re
+.Pp
 .Rs
-.%R RFC 3682
-.%T "The Generalized TTL Security Mechanism (GTSM)"
-.%D February 2004
+.%A Y. Rekhter
+.%A "T. Li"
+.%A S. Hares
+.%D January 2006
+.%R RFC 4271
+.%T A Border Gateway Protocol 4 (BGP-4)
 .Re
+.Pp
 .Rs
-.%R RFC 3765
-.%T "NOPEER Community for Border Gateway Protocol"
-.%D April 2004
+.%A S. Sangli
+.%A D. Tappan
+.%A Y. Rekhter
+.%D February 2006
+.%R RFC 4360
+.%T BGP Extended Communities Attribute
 .Re
+.Pp
 .Rs
-.%R RFC 4760
-.%T "Multiprotocol Extensions for BGP-4"
+.%A E. Rosen
+.%A Y. Rekhter
+.%D February 2006
+.%R RFC 4364
+.%T BGP/MPLS IP Virtual Private Networks (VPNs)
+.Re
+.Pp
+.Rs
+.%A T. Bates
+.%A E. Chen
+.%A R. Chandra
+.%D April 2006
+.%R RFC 4456
+.%T "BGP Route Reflection: An Alternative to Full Mesh Internal BGP (IBGP)"
+.Re
+.Pp
+.Rs
+.%A E. Chen
+.%A V. Gillet
+.%D April 2006
+.%R RFC 4486
+.%T Subcodes for BGP Cease Notification Message
+.Re
+.Pp
+.Rs
+.%A T. Bates
+.%A R. Chandra
+.%A D. Katz
+.%A Y. Rekhter
 .%D January 2007
+.%R RFC 4760
+.%T Multiprotocol Extensions for BGP-4
 .Re
+.Pp
 .Rs
-.%R RFC 4893
-.%T "BGP Support for Four-octet AS Number Space"
+.%A Q. Vohra
+.%A E. Chen
 .%D May 2007
+.%R RFC 4893
+.%T BGP Support for Four-octet AS Number Space
+.Re
+.Pp
+.Rs
+.%A V. Gill
+.%A J. Heasley
+.%A D. Meyer
+.%A P. Savola
+.%A C. Pignatoro
+.%D October 2007
+.%R RFC 5082
+.%T The Generalized TTL Security Mechanism (GTSM)
+.Re
+.Pp
+.Rs
+.%A J. Scudder
+.%A R. Chandra
+.%D February 2009
+.%R RFC 5492
+.%T Capabilities Advertisement with BGP-4
+.Re
+.Pp
+.Rs
+.%D April 2009
+.%R draft-ietf-idr-optional-transitive-00
+.%T Error Handling for Optional Transitive BGP Attributes
+.Re
+.Pp
+.Rs
+.%D August 2011
+.%R draft-ietf-grow-mrt-17
+.%T MRT routing information export format
+.Re
+.Pp
+.Rs
+.%A J. Dong
+.%A M. Chen
+.%A A. Suryanarayana
+.%D May 2012
+.%R RFC 6608
+.%T Subcodes for BGP Finite State Machine Error
 .Re
 .Sh HISTORY
 The