Net::BGP::Peer - Class encapsulating BGP-4 peering session state and
functionality
use Net::BGP::Peer;
$peer = Net::BGP::Peer->new(
Start => 1,
ThisID => '10.0.0.1',
ThisAS => 64512,
PeerID => '10.0.0.2',
PeerAS => 64513,
PeerPort => 1179,
ConnectRetryTime => 300,
HoldTime => 60,
KeepAliveTime => 20,
Listen => 0,
Passive => 0,
AnnounceRefresh => 1,
SupportCapabilities => 1,
SupportMBGP => 1,
SupportAS4 => 1,
OpenCallback => \&my_open_callback,
KeepaliveCallback => \&my_keepalive_callback,
UpdateCallback => \&my_update_callback,
NotificationCallback => \&my_notification_callback,
ErrorCallback => \&my_error_callback
);
$peer = renew Net::BGP::Peer("$peer");
$peer->start();
$peer->stop();
$peer->update($update);
$peer->refresh($refresh);
$version = $peer->version();
$this_id = $peer->this_id();
$this_as = $peer->this_as();
$peer_id = $peer->peer_id();
$peer_as = $peer->peer_as();
$i_will = $peer->support_capabilities();
$i_mbgp = $peer->support_mbgp();
$i_can = $peer->this_can_refresh();
$peer_can= $peer->peer_can_refresh();
$peer_as4= $peer->peer_can_as4();
$listen = $peer->is_listener();
$passive = $peer->is_passive();
$estab = $peer->is_established();
$trans = $peer->transport($trans);
@trans = $peer->transports;
$string = $peer->asstring();
$peer->set_open_callback(\&my_open_callback);
$peer->set_established_callback(\&my_established_callback);
$peer->set_keepalive_callback(\&my_keepalive_callback);
$peer->set_update_callback(\&my_update_callback);
$peer->set_notification_callback(\&my_notification_callback);
$peer->set_error_callback(\&my_error_callback);
$peer->add_timer(\&my_minute_timer, 60);
$peer->remove_timer(\&my_minute_timer);
This module encapsulates the state and functionality associated with a BGP
peering session. Each instance of a
Net::BGP::Peer object corresponds
to a peering session with a distinct peer and presents a programming interface
to manipulate the peering session state and exchange of routing information.
Through the methods provided by the
Net::BGP::Peer module, a program
can start or stop peering sessions, send BGP routing UPDATE messages, and
register callback functions which are invoked whenever the peer receives BGP
messages from its peer.
new() - create a new Net::BGP::Peer object
This is the constructor for Net::BGP::Peer objects. It returns a reference to
the newly created object. The following named parameters may be passed to the
constructor. Once the object is created, only the callback function references
can later be changed.
Setting this parameter to a true value causes the peer to initiate a session
with its peer immediately after it is registered with the
Net::BGP::Process object's
add_peer()
method. If omitted or set to a false value, the peer will remain in the Idle
state until the
start() method is called
explicitly by the program. When in the Idle state the peer will refuse
connections and will not initiate connection attempts.
This parameter sets the BGP ID (IP address) of the
Net::BGP::Peer object.
It takes a string in IP dotted decimal notation.
This parameter sets the BGP Autonomous System number of the
Net::BGP::Peer object. It takes an integer value in the range of a
16-bit unsigned integer.
This parameter sets the BGP ID (IP address) of the object's peer. It takes a
string in IP dotted decimal notation.
This parameter sets the BGP Autonomous System number of the object's peer. It
takes an integer value in the range of a 16-bit unsigned integer.
This parameter sets the TCP port number on the peer to which to connect. It must
be in the range of a valid TCP port number.
This parameter sets the BGP ConnectRetry timer duration, the value of which is
given in seconds.
This parameter sets the BGP Hold Time duration, the value of which is given in
seconds.
This parameter sets the BGP KeepAlive timer duration, the value of which is
given in seconds.
This parameter specifies whether the
Net::BGP::Peer will listen for and
accept connections from its peer. If set to a false value, the peer will only
initiate connections and will not accept connection attempts from the peer
(unless the
Passive parameter is set to a true value). Note that this
behavior is not specified by RFC 1771 and should be considered non-standard.
However, it is useful under certain circumstances and should not present
problems as long as one side of the connection is configured to listen.
This parameter specifies whether the
Net::BGP::Peer will attempt to
initiate connections to its peer. If set to a true value, the peer will only
listen for connections and will not initate connections to its peer (unless
the
Listen parameter is set to false value). Note that this behavior is
not specified by RFC 1771 and should be considered non-standard. However, it
is useful under certain circumstances and should not present problems as long
as one side of the connection is configured to initiate connections.
This parameter specifies whether the
Net::BGP::Peer will annonce support
for route refresh ('soft re-configure' as specified by RFC 2918). No support
for route refresh is implemented - only the
RefreshCallback function.
This has no effect if SupportCapabilities is FALSE.
This parameter specifies whether the
Net::BGP::Peer will attempt to
negotiate capabilities. You can set this to FALSE if talking to an old BGP
speaker that doesn't support it (you'll get a notification message for an
unsupported capability if this is the case). This defaults to TRUE.
This parameter specifies whether the
NET::BGP::Peer will attempt to
negotiate MBGP. Quagga (and probably others) need this if you want to send the
REFRESH capability. Today this just indicates support for IPv4 Unicast. This
defaults to TRUE. This has no effect if SupportCapabilities is FALSE.
This paramemter specifies whether outgoing connections from
NET::BGP::Peer will attempt to negotiate AS4 (32 bit ASNs). For
received connections, this parameter has no effect - it only determines
whether or not AS4 is negotiated during outgoing connection. For received
connections, this will be changed to TRUE (on the listening connection)
whenever the appropriate OPEN capability is received. Note that the
SupportCapabilities must be true for this to be sent. This defaults to
FALSE.
This parameter sets the callback function which is invoked when the peer
receives an OPEN message. It takes a subroutine reference. See "CALLBACK
FUNCTIONS" later in this manual for further details of the conventions of
callback invocation.
This parameter sets the callback function which is invoked when the peer
receives a KEEPALIVE message. It takes a subroutine reference. See
"CALLBACK FUNCTIONS" later in this manual for further details of the
conventions of callback invocation.
This parameter sets the callback function which is invoked when the peer
receives an UPDATE message. It takes a subroutine reference. See
"CALLBACK FUNCTIONS" later in this manual for further details of the
conventions of callback invocation.
This parameter sets the callback function which is invoked when the peer
receives a REFRESH message. It takes a subroutine reference. See
"CALLBACK FUNCTIONS" later in this manual for further details of the
conventions of callback invocation.
This parameter sets the callback function which is invoked when the peer
receives a NOTIFICATION message. It takes a subroutine reference. See
"CALLBACK FUNCTIONS" later in this manual for further details of the
conventions of callback invocation.
This parameter sets the callback function which is invoked when the peer
encounters an error and must send a NOTIFICATION message to its peer. It takes
a subroutine reference. See "CALLBACK FUNCTIONS" later in this
manual for further details of the conventions of callback invocation.
renew - fetch the existing Net::BGP::Peer object from the "object
string".
This "reconstructor" returns a previeus constructed object from the
perl genereted string-context scalar of the object, eg.
Net::BGP::Peer=HASH(0x820952c).
start() - start the BGP peering session with the
peer
$peer->start();
This method initiates the BGP peering session with the peer by internally
emitting the BGP Start event, which causes the peer to initiate a
transport-layer connection to its peer (unless the
Passive parameter
was set to a true value in the constructor) and listen for a connection from
the peer (unless the
Listen parameter is set to a false value).
stop() - cease the BGP peering session with the peer
$peer->stop();
This method immediately ceases the peering session with the peer by sending it a
NOTIFICATION message with Error Code Cease, closing the transport-layer
connection, and entering the Idle state.
update() - send a BGP UPDATE message to the peer
$peer->update($update);
This method sends the peer an UPDATE message. It takes a reference to a
Net::BGP::Update object. See the Net::BGP::Update manual page for details on
setting UPDATE attributes.
refresh() - send a BGP REFRESH message to the peer
$peer->refresh($refresh);
This method sends the peer a REFRESH message. It takes a reference to a
Net::BGP::Refesh object. If no argument is provided, a default
Net::BGP::Refresh object is constructed. See the Net::BGP::Refresh manual page
for details on setting REFRESH attributes.
transport()
Returns the active transport object to the peer - See Net::BGP::Transport.
transports()
Return a list of transport objects. The list will contain one or two elements.
The first will always be the primary transport object. If there are two
sessions (e.g. collision detection hasn't removed one of them), the sibling
will be returned as the second element of the list.
this_id()
this_as()
peer_id()
peer_as()
this_can_refresh()
support_capabilities()
support_mbgp()
is_listener()
is_passive()
version()
These are accessor methods for the corresponding constructor named parameters.
They retrieve the values set when the object was created, but the values
cannot be changed after object construction. Hence, they take no arguments.
is_established()
This accessor method returns true if the peer has a established transport
connection - e.g. the peering is up.
peer_can_refresh()
This accessor method returns a true value if connected to a peer that supports
refresh messages - otherwise a false value.
asstring()
This accessor method returns a print friendly string with the local and remote
IP and AS numbers.
set_open_callback()
set_established_callback()
set_keepalive_callback()
set_update_callback()
set_refresh_callback()
set_reset_callback()
set_notification_callback()
set_error_callback()
These methods set the callback functions which are invoked whenever the peer
receives the corresponding BGP message type from its peer, or, in the case of
set_established_callback, transitions to the relevant state. They can
be set in the constructor as well as with these methods. These methods each
take one argument, which is the subroutine reference to be invoked. A callback
function can be removed by calling the corresponding one of these methods and
passing it the perl
undef value. For callback definition and invocation
conventions see "CALLBACK FUNCTIONS" later in this manual.
add_timer() - add a program defined timer callback
function
$peer->add_timer(\&my_minute_timer, 60);
This method sets a program defined timer which invokes the specified callback
function when the timer expires. It takes two arguments: the first is a code
reference to the subroutine to be invoked when the timer expires, and the
second is the timer interval, in seconds. The program may set as many timers
as needed, and multiple timer callbacks may share the same interval. Program
timers add an asynchronous means for user code to gain control of the program
control flow - without them user code would only be invoked whenever BGP
events exposed by the module occur. They may be used to perform any necessary
action - for example, sending UPDATEs, starting or stopping the peering
session, house-keeping, etc.
remove_timer() - remove a program defined timer
callback function
$peer->remove_timer(\&my_minute_timer);
This method removes a program defined timer callback which has been previously
set with the
add_timer() method. It takes a single
argument: a reference to the subroutine previously added.
Whenever a
Net::BGP::Peer object receives one of the BGP protocol
messages - OPEN, KEEPALIVE, UPDATE, REFRESH, or NOTIFICATION - from its peer,
or whenever it encounters an error condition and must send a NOTIFICATION
message to its peer, the peer object will invoke a program defined callback
function corresponding to the event type, if one has been provided, to inform
the application about the event. These callback functions are installed as
described in the preceding section of the manual. Whenever any callback
function is invoked, it is passed one or more arguments, depending on the BGP
message type associated with the callback. The first argument passed to all of
the callbacks is a reference to the
Net::BGP::Peer object which the
application may use to identify which peer has signalled the event and to take
appropriate action. For OPEN and KEEPALIVE callbacks, this is the only
argument passed. It is very unlikely that applications will be interested in
OPEN and KEEPALIVE events, since the
Net::BGP module handles all
details of OPEN and KEEPALIVE message processing in order to establish and
maintain BGP sessions. Callback handling for these messages is mainly included
for the sake of completeness. For UPDATE and NOTIFICATION messages, however,
most applications will install callback handlers. Whenever an UPDATE, REFRESH,
NOTIFICATION, or error handler is called, the object will pass a second
argument. In the first two cases, this is a
Net::BGP::Update or
Net::BGP::Refresh object respectivly encapsulating the information
contained in the UPDATE or REFRESH message, while in the latter two cases it
is a
Net::BGP::Notification object encapsulating the information in the
NOTIFICATION message sent or received.
The RESET and ESTABLISHED callbacks are special, since they are used whenever an
established BGP session is reset, even though no message has been recieved or
sent. The REFRESH callback is also special, since it is also called without a
REFRESH object whenever a BGP session is established. The two callbacks can be
used to clear and retransmit a RIB from/to the peer in question.
Whenever a callback function is to be invoked, the action occuring internally is
the invocation of one of the following methods, corresponding to the event
which has occured:
open_callback()
established_callback()
keepalive_callback()
update_callback()
refresh_callback()
reset_callback()
notification_callback()
error_callback()
Internally, each of these methods just checks to see whether a program defined
callback function has been set and calls it if so, passing it arguments as
described above. As an alternative to providing subroutine references to the
constructor or through the
set_open_callback(),
set_established_callback(),
set_keepalive_callback() ,
set_update_callback() ,
set_refresh_callback() ,
set_reset_callback() ,
set_notification_callback() , and
set_error_callback() methods, an application may
effect a similar result by sub-classing the
Net::BGP::Peer module and
overridding the defintions of the above methods to perform whatever actions
would have been executed by ordinary callback functions. The overridden
methods are passed the same arguments as the callback functions. This method
might offer an advantage in organizing code according to different derived
classes which apply specifc routing policies.
There are two possibilities for error handling callbacks to be invoked. The
first case occurs when the peer receives a NOTIFICATION messages from its
peer. The second case occurs when the peer detects an error condition while
processing an incoming BGP message or when some other protocol covenant is
violated - for example if a KEEPALIVE or UPDATE message is not received before
the peer's Keepalive timer expires. In this case, the peer responds by sending
a NOTIFICATION message to its peer. In the former case the
notification_callback() method is invoked as
described above to handle the error, while in the latter the
error_callback() method is invoked to inform the
application that it has encountered an error. Both methods are passed a
Net::BGP::Notification object encapsulating the details of the error.
In both cases, the transport-layer connection and BGP session are closed and
the peer transitions to the Idle state. The error handler callbacks can
examine the cause of the error and take appropriate action. This could be to
attempt to re-establish the session (perhaps after sleeping for some amount of
time), or to unregister the peer object from the
Net::BGP::Process
object and permanently end the session (for the duration of the application's
running time), or to log the event to a file on the host system, or some
combination of these or none.
Net::BGP, Net::BGP::Process, Net::BGP::Update, Net::BGP::Transport,
Net::BGP::Refresh, Net::BGP::Notification
Stephen J. Scheck <code@neurosphere.com>