#
# Public Release 3
# 
# $Id: README.bgp,v 1.2 1997/07/17 22:39:23 chopps Exp $
#
# ------------------------------------------------------------------------
# 
# Copyright (c) 1996, 1997 The Regents of the University of Michigan
# All Rights Reserved
#  
# Royalty-free licenses to redistribute GateD Release
# 3 in whole or in part may be obtained by writing to:
# 
# 	Merit GateDaemon Project
# 	4251 Plymouth Road, Suite C
# 	Ann Arbor, MI 48105
#  
# THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
# EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF 
# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE REGENTS OF THE
# UNIVERSITY OF MICHIGAN AND MERIT DO NOT WARRANT THAT THE
# FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET LICENSEE'S REQUIREMENTS OR
# THAT OPERATION WILL BE UNINTERRUPTED OR ERROR FREE. The Regents of the
# University of Michigan and Merit shall not be liable for
# any special, indirect, incidental or consequential damages with respect
# to any claim by Licensee or any third party arising from use of the
# software. GateDaemon was originated and developed through release 3.0
# by Cornell University and its collaborators.
# 
# Please forward bug fixes, enhancements and questions to the
# gated mailing list: gated-people@gated.merit.edu.
# 
# ------------------------------------------------------------------------
# 
# Copyright (c) 1990,1991,1992,1993,1994,1995 by Cornell University.
#     All rights reserved.
# 
# THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY
# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
# LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY
# AND FITNESS FOR A PARTICULAR PURPOSE.
# 
# GateD is based on Kirton's EGP, UC Berkeley's routing
# daemon	 (routed), and DCN's HELLO routing Protocol.
# Development of GateD has been supported in part by the
# National Science Foundation.
# 
# ------------------------------------------------------------------------
# 
# Portions of this software may fall under the following
# copyrights:
# 
# Copyright (c) 1988 Regents of the University of California.
# All rights reserved.
# 
# Redistribution and use in source and binary forms are
# permitted provided that the above copyright notice and
# this paragraph are duplicated in all such forms and that
# any documentation, advertising materials, and other
# materials related to such distribution and use
# acknowledge that the software was developed by the
# University of California, Berkeley.  The name of the
# University may not be used to endorse or promote
# products derived from this software without specific
# prior written permission.  THIS SOFTWARE IS PROVIDED
# ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
# INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
#
#
This is an attempt to document how the BGP is supposed to work
so you'll be able to tell when it doesn't work this way.

The BGP protocol supports two basic flavours, external and internal.
From the protocol's point of view the difference between these
is for external advertisements the local AS is prepended to the
AS path while for internal advertisements it isn't, and there
is in principle a builtin policy constraint against readvertising
internal routes to another member of the same group.

A note about "groups".  Currently the implementation demands that each
group differ by at least one of the group type, peer AS and local AS.
This isn't quite the right thing to do, but will require some thinking
about to fix.  "internal", "test" and "igp" implement identical policy
for all peers, this constraining certain options (for example,
importdefault and exportdefault) to be the same for all neighbours in
the group.

The configuration language allows options to be applied to either the
group or to individual peers within the group.  The group options are
used as a default for peers in the group (and, of course, are applied
to unconfigured peers which connect), peer options vary the configuration
from this.

This implementation defines four different "group types":

external - the classic external BGP.  Full policy checking is applied
	   to all incoming and outgoing advertisements.  The implementation
	   demands that external neighbours be directly reachable through
	   one of the machine's local interfaces.  By default no metric
	   is included in external advertisements, and the next hop is
	   computed with respect to the shared interface.

test     - a special case of external BGP which implements a fixed
	   policy.  The implementation discards all routing information
	   advertised to it by a test peer, and sends all BGP-advertiseable
	   routes back to it.  The constraint that external peers be on a
	   directly attached network is removed for test peers.  If the
	   local and remote addresses for the peer association are on
	   the same (directly attached) subnet the advertised next hop
	   is computed with respect to that network, otherwise the next
	   hop is the local machine's current next hop.  Metrics from
	   BGP- and EGP-derived routes are forwarded in the advertisement,
	   otherwise no metric is included.  The reason "test" peers
	   are special-cased (you could do most of this with appropriate
	   policy configuration for an external peer) is that the fixed
	   policy and special case code which implements it makes test
	   peers comparatively quite cheap to maintain.

internal - this type of internal group is meant to operate where there
	   is no IP-level IGP, for example perhaps an SMDS network or
	   the MILNET.  All neighbours in the group are constrained to
	   be directly reachable via a single interface, all next hop
	   information is computed with respect to this interface.  Import
	   and export policy may be applied to group advertisements.
	   Routes received from external BGP or EGP neighbours are by
	   default readvertised with the received metric (import and export
	   policy statements should be modified to allow configuration of
	   this instead).  Advertisements received from internal peers in
	   the same group are never readvertised.

igp	 - this type of internal group runs in association with an instance
	   of an IGP (currently only OSPF is supported).  This type of
	   group operates by examining routes which OSPF is exporting
	   and sending an advertisement only if the path attributes
	   could not be entirely represented in the OSPF tag.  Only
	   the AS path, path origin and transitive optional attributes
	   are sent with routes.  No metric is sent, and the next hop
	   is set to the local address used by the connection.  Received
	   internal-igp routes are never used or readvertised, instead
	   the AS path information is attached to the corresponding IGP
	   route and the latter is used for readvertisement.  Since
	   internal-igp peers are sent a subset of the routes which the
	   IGP is exporting, the export policy used is essentially
	   that of the IGP.  There is no need to actually implement the
	   don't-readvertise-routes-from-peers-in-the-same-group
	   constraint since one is actually advertising routes which the IGP
	   exports and the IGP shouldn't export routes from itself.

The implementation fully compresses routes with similar path attributes
into a single update for advertisement.  While the overall effectiveness
of this is somewhat dependent on gated's flash update strategy, it is
certainly guaranteed that routes which are received in a single update
will be readvertised in a single update, that the churn caused by the
loss of a neighbour will go out all at once, and that the initial
advertisement sent during peer establishment will be maximally compressed.
Currently the implementation limits the size of outgoing messages to
1024 bytes to match a constraint I am told rcp_routed may have possessed.
This may be changed by changing the appropriate constant in bgp.h.
Input messages up to the full 4096 bytes in size are accepted.

The implementation does not read data from the kernel message-by-message,
but rather operates by trying to fill the (currently 4k) input buffer
on every read and process all complete messages in the buffer before
reading again, this to minimize system call overhead.  It also currently
does multiple reads to clear all incoming data queued on the socket
before returning to flash the other protocol instances, to minimize
gated overhead.  As the latter behaviour can cause the other protocol
instances to be blocked for long periods (if not indefinitely) by a
busy peer connection I intend to change this to have the incoming update
processing return when it has read "enough", but I want to get an idea
of how this performs on an RT or similar worst case before deciding how
much is "enough".

The implementation collects all unreachable announcements it needs to
send into a single message (or several maximally sized messages) and
sends this all at once prior to sending reachable routes during a flash
update.  For these announcements the next hop is set to the local address
on the connection, no metric is sent, and the path origin is set to
incomplete.  On external connections the AS path is set to the local
AS, on internal connections the AS path is set to zero length.  The
behaviour on internal connections violates the spec, which says you
must send full path attributes with unreachable announcements on internal
connections, but I don't think I care since I can't figure out why this
constraint exists.  If I should care please tell me.

In accord with the spec, the implementation always sends unreachables
for networks which have actually gone unreachable, even if they are
to be immediately replaced by another route.  Incoming update processing
is done such that the unreachable is propagated to other peers.  The
exception to this is for igp group members, where unreachables aren't
sent if there is a replacement route immediately available.  The reason
is that it isn't clear to me that OSPF will do this right for routes
which don't require an IBGP announcement, and I think that if you are
going to get this wrong some of the time you might as well get it
wrong all of the time.  I may change this if it turns out I am incorrect.

For internal and igp groups, and for test groups where possible, a
single outgoing message is built for all group peers based on the
common policy, and a copy of the message is then sent to every peer in
the group, with possible adjustments to the next hop field as appropriate
for each peer.  This minimizes the computational load of running
large numbers of peers in these types of groups, since essentially
the same update messages are sent to all peers in the group.

The implementation allows unconfigured peers to connect if an
appropriate peer group has been configured, with authentication
being done by address-and-mask checking against the peer IP
address.  The intention was to use this for internal groups to
allow additional IBGP peers to be brought up without having to
configure everyone else, and test groups to let a variety of
testers connect, though the feature may be used with any group.
The implementation also allows multiple connections from a single
machine as long as the local and peer AS numbers differ for each
connection.  Indeed, the implementation fully supports running
in several AS's, handling route exchange between AS's as if there
were several routers running with BGPs between them, though the fact
that gated's policy configuration isn't quite up to this yet makes
this somewhat less useful.

A great deal of effort has been spent making the implementation
reconfigurable on-the-fly, with established connections being taken
down only when the new configuration absolutely demands it.  Policy
may be freely changed across reconfigurations.  Unconfigured peers
may be configured without interruption.  Individual peers and groups
may be removed from the configuration and will be taken down without
affecting others (unless, of course, the deleted peer would still
qualify as an unconfigured peer in the same group).  To do this in
general requires that the implementation retain state about every
network advertised to it even if it is prevented from using the route
by policy.  By default the implementation maintains state about all
routes advertised to it except those whose AS path contains the
local AS in use on the connection (the "keepall" option makes it
remember even the latter routes, a feature which might be useful for
debugging).

The following options may be used with both BGP groups and peers.
The options which probably only make sense with groups are noted.

	metricout     - for internal and test groups, group only.
			Ignored for igp groups.
	asout         - group only
	nogendefault  - ignored for test groups
	gateway       - ignored for test groups
	interface     - for internal groups, group only
	holdtime
	version       - only version 3 permitted for igp groups
	passive
	importdefault - for internal, group only.  Ignored for igp groups
	exportdefault - for internal, group only.  Ignored for igp groups
	preference    - ignored for igp and test groups
	keepall       - ignored for test groups

Changing the following option will cause an entire group to be restarted.

	asout

Changing the following options may result in an established peer
association being terminated.

	holdtime
	version
	interface (if the new interface address isn't being used currently)
	keepall (only if it is turned on, turning it off should be okay)

The implementation has rudimentary support for dynamic interface
configuration.  In particular if an external peer is configured whose
address is not reachable directly through one of the machine's current
interfaces, or if the interface option specified a local interface
different than this, the implementation emits a complaint but continues
on with the peer idled in case an interface to which the peer is attached
should appear during operation.

Dennis Ferguson
March 23, 1992
