Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::BGP::Peer(3)     User Contributed Perl Documentation    Net::BGP::Peer(3)

NAME
       Net::BGP::Peer -	Class encapsulating BGP-4 peering session state	and
       functionality

SYNOPSIS
	   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,
	       OpaqueData	    => $my_ref,
	       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();
	   $my_ref  = $peer->opaque_data();
	   $my_ref  = $peer->opaque_data($new_ref);

	   $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);

DESCRIPTION
       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.

CONSTRUCTOR
       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.

   Start
       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.

   ThisID
       This parameter sets the BGP ID (IP address) of the Net::BGP::Peer
       object. It takes	a string in IP dotted decimal notation.

   ThisAS
       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.

   PeerID
       This parameter sets the BGP ID (IP address) of the object's peer. It
       takes a string in IP dotted decimal notation.

   PeerAS
       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.

   PeerPort
       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.

   ConnectRetryTime
       This parameter sets the BGP ConnectRetry	timer duration,	the value of
       which is	given in seconds.

   HoldTime
       This parameter sets the BGP Hold	Time duration, the value of which is
       given in	seconds.

   KeepAliveTime
       This parameter sets the BGP KeepAlive timer duration, the value of
       which is	given in seconds.

   Listen
       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.

   Passive
       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.

   Refresh
       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.

   SupportCapabilities
       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.

   SupportMBGP
       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.

   SupportAS4
       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.

   OpaqueData
       This parameter is an optional scalar that will be kept as part of the
       Net::BGP::Peer and can be queried by the	callback routines when they
       receive a peer hashref -	see opaque_data. This allows extra data	to be
       stored with the peer. The contents of this are completely ignored by
       Net::BGP::Peer. This defaults to	undef.

   OpenCallback
       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.

   KeepaliveCallback
       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.

   UpdateCallback
       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.

   RefreshCallback
       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.

   NotificationCallback
       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.

   ErrorCallback
       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).

ACCESSOR METHODS
       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.

       opaque_data()

	   $peer->opaque_data();
	   $peer->opaque_data($new_ref);

       This method can be used to both query (no argument) or set (with	an
       argument) the opaque data held with the peer object. The	method returns
       the old opaque data scalar (which is the	current	value if not
       provided).

       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.

CALLBACK FUNCTIONS
       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.

ERROR HANDLING
       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.

SEE ALSO
       Net::BGP, Net::BGP::Process, Net::BGP::Update, Net::BGP::Transport,
       Net::BGP::Refresh, Net::BGP::Notification

AUTHOR
       Stephen J. Scheck <sscheck@cpan.org>

perl v5.32.1			  2019-08-03		     Net::BGP::Peer(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | ACCESSOR METHODS | CALLBACK FUNCTIONS | ERROR HANDLING | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::BGP::Peer&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help