Net::BGP::Peer(3)

✨ Net::BGP::Peer(3) ✨

okay bestie, welcome to the Net::BGP::Peer(3) page from User Contributed Perl Documentation — yes, it's a Perl module manual, and it's lowkey a whole vibe. 💅

💖 NAME 💖

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

🌈 SYNOPSIS 🌈

Here's the whole cast of calls, fr fr — copy/paste energy, but keep it exact:

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 is the whole package for a BGP peering session: it encapsulates the state and functionality associated with it. Every instance of a Net::BGP::Peer object = one peering session with a distinct peer, and it hands you a programming interface to manipulate the peering session state and exchange of routing information. Through the methods provided by Net::BGP::Peer, a program can start or stop peering sessions, send BGP routing UPDATE messages, and register callback functions that get invoked whenever the peer receives BGP messages from its peer. Iconic. 👑

🛠️ 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 — set this to a true value and the peer will 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 program explicitly calls the start() method. When in the Idle state, the peer will refuse connections and will not initiate connection attempts. 🌱
• ThisID — sets the BGP ID (IP address) of the Net::BGP::Peer object. It takes a string in IP dotted decimal notation. 📍
• ThisAS — 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 — sets the BGP ID (IP address) of the object's peer. It takes a string in IP dotted decimal notation. 🎯
• PeerAS — 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 — 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 — sets the BGP ConnectRetry timer duration, and the value is given in seconds. ⏱️
• HoldTime — sets the BGP Hold Time duration, and the value is given in seconds. ⏳
• KeepAliveTime — sets the BGP KeepAlive timer duration, and the value is given in seconds. 💓
• Listen — 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 — 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 initiate connections to its peer (unless the Listen parameter is set to a 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. 🛋️
• AnnounceRefresh — specifies whether the Net::BGP::Peer will announce 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 — 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 — 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 — specifies whether outgoing connections from the 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 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 — 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 — 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 — 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 — 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 — 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 — 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 previously constructed object from the perl generated string-context scalar of the object, e.g. Net::BGP::Peer=HASH(0x820952c). 🪄

💖 ACCESSOR METHODS 💖

okay bestie, this is the part where you actually poke at the peer object and make it do stuff. no cap, these are the handles. 🎀

start() — start the BGP peering session with the peer

$peer->start();

This method kicks off the BGP peering session with the peer by internally emitting the BGP Start event. That event makes the peer 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. slay. ✨

stop() — cease the BGP peering session with the peer

$peer->stop();

This one immediately ceases the peering session with the peer: it sends a NOTIFICATION message with Error Code Cease, closes the transport-layer connection, and enters the Idle state. boom, done. 💅

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. For the deets on setting UPDATE attributes, see the Net::BGP::Update manual page. 🦋

refresh() — send a BGP REFRESH message to the peer

$peer->refresh($refresh);

This sends the peer a REFRESH message. It takes a reference to a Net::BGP::Refresh object. If no argument is provided, a default Net::BGP::Refresh object is constructed. Again, the Net::BGP::Refresh manual page has the details on setting REFRESH attributes. ✨

constructor-parameter accessors, aka the read-only squad

• 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. periodt. 🔥

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 one wasn’t provided. 🫶

is_established()

This accessor method returns true if the peer has an established transport connection — e.g. the peering is up. iykyk. ✅

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. cute and useful. 🎀

callback setter crew

• 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. Each one takes one argument: 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. bye timer 👋

---

🦋 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 respectively 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 received 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 occurring internally is the invocation of one of the following methods, corresponding to the event which has occurred:

• 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 overriding the definitions 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 specific 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 message 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. your call, bestie. 💅

---

👑 SEE ALSO 👑

• Net::BGP
• Net::BGP::Process
• Net::BGP::Update
• Net::BGP::Refresh
• Net::BGP::ASPath
• Net::BGP::NLRI
• Net::BGP::Notification

---

🌸 AUTHOR 🌸

Stephen J. Scheck <sscheck@cpan.org>

💖 that’s the whole vibe. footer deets: this Net::BGP::Peer(3) page is from perl v5.32.1, dated 2021-12-02. mwah 💋✨