1Net::BGP::Peer(3)     User Contributed Perl Documentation    Net::BGP::Peer(3)
2
3
4

NAME

6       "Net::BGP::Peer" - Class encapsulating BGP-4 peering session state and
7       functionality
8

SYNOPSIS

10           use Net::BGP::Peer;
11
12           $peer = Net::BGP::Peer->new(
13               Start                => 1,
14               ThisID               => '10.0.0.1',
15               ThisAS               => 64512,
16               PeerID               => '10.0.0.2',
17               PeerAS               => 64513,
18               PeerPort             => 1179,
19               ConnectRetryTime     => 300,
20               HoldTime             => 60,
21               KeepAliveTime        => 20,
22               Listen               => 0,
23               Passive              => 0,
24               AnnounceRefresh      => 1,
25               SupportCapabilities  => 1,
26               SupportMBGP          => 1,
27               SupportAS4           => 1,
28               OpaqueData           => $my_ref,
29               OpenCallback         => \&my_open_callback,
30               KeepaliveCallback    => \&my_keepalive_callback,
31               UpdateCallback       => \&my_update_callback,
32               NotificationCallback => \&my_notification_callback,
33               ErrorCallback        => \&my_error_callback
34           );
35
36           $peer = renew Net::BGP::Peer("$peer");
37
38           $peer->start();
39           $peer->stop();
40
41           $peer->update($update);
42           $peer->refresh($refresh);
43
44           $version = $peer->version();
45
46           $this_id = $peer->this_id();
47           $this_as = $peer->this_as();
48           $peer_id = $peer->peer_id();
49           $peer_as = $peer->peer_as();
50           $my_ref  = $peer->opaque_data();
51           $my_ref  = $peer->opaque_data($new_ref);
52
53           $i_will  = $peer->support_capabilities();
54
55           $i_mbgp  = $peer->support_mbgp();
56
57           $i_can   = $peer->this_can_refresh();
58           $peer_can= $peer->peer_can_refresh();
59
60           $peer_as4= $peer->peer_can_as4();
61
62           $listen  = $peer->is_listener();
63           $passive = $peer->is_passive();
64           $estab   = $peer->is_established();
65
66           $trans   = $peer->transport($trans);
67           @trans   = $peer->transports;
68
69           $string  = $peer->asstring();
70
71           $peer->set_open_callback(\&my_open_callback);
72           $peer->set_established_callback(\&my_established_callback);
73           $peer->set_keepalive_callback(\&my_keepalive_callback);
74           $peer->set_update_callback(\&my_update_callback);
75           $peer->set_notification_callback(\&my_notification_callback);
76           $peer->set_error_callback(\&my_error_callback);
77
78           $peer->add_timer(\&my_minute_timer, 60);
79           $peer->remove_timer(\&my_minute_timer);
80

DESCRIPTION

82       This module encapsulates the state and functionality associated with a
83       BGP peering session. Each instance of a "Net::BGP::Peer" object
84       corresponds to a peering session with a distinct peer and presents a
85       programming interface to manipulate the peering session state and
86       exchange of routing information. Through the methods provided by the
87       "Net::BGP::Peer" module, a program can start or stop peering sessions,
88       send BGP routing UPDATE messages, and register callback functions which
89       are invoked whenever the peer receives BGP messages from its peer.
90

CONSTRUCTOR

92       new() - create a new "Net::BGP::Peer" object
93
94       This is the constructor for "Net::BGP::Peer" objects. It returns a
95       reference to the newly created object. The following named parameters
96       may be passed to the constructor. Once the object is created, only the
97       callback function references can later be changed.
98
99   Start
100       Setting this parameter to a true value causes the peer to initiate a
101       session with its peer immediately after it is registered with the
102       Net::BGP::Process object's add_peer() method. If omitted or set to a
103       false value, the peer will remain in the Idle state until the start()
104       method is called explicitly by the program. When in the Idle state the
105       peer will refuse connections and will not initiate connection attempts.
106
107   ThisID
108       This parameter sets the BGP ID (IP address) of the "Net::BGP::Peer"
109       object. It takes a string in IP dotted decimal notation.
110
111   ThisAS
112       This parameter sets the BGP Autonomous System number of the
113       "Net::BGP::Peer" object. It takes an integer value in the range of a
114       16-bit unsigned integer.
115
116   PeerID
117       This parameter sets the BGP ID (IP address) of the object's peer. It
118       takes a string in IP dotted decimal notation.
119
120   PeerAS
121       This parameter sets the BGP Autonomous System number of the object's
122       peer.  It takes an integer value in the range of a 16-bit unsigned
123       integer.
124
125   PeerPort
126       This parameter sets the TCP port number on the peer to which to
127       connect. It must be in the range of a valid TCP port number.
128
129   ConnectRetryTime
130       This parameter sets the BGP ConnectRetry timer duration, the value of
131       which is given in seconds.
132
133   HoldTime
134       This parameter sets the BGP Hold Time duration, the value of which is
135       given in seconds.
136
137   KeepAliveTime
138       This parameter sets the BGP KeepAlive timer duration, the value of
139       which is given in seconds.
140
141   Listen
142       This parameter specifies whether the "Net::BGP::Peer" will listen for
143       and accept connections from its peer. If set to a false value, the peer
144       will only initiate connections and will not accept connection attempts
145       from the peer (unless the Passive parameter is set to a true value).
146       Note that this behavior is not specified by RFC 1771 and should be
147       considered non-standard. However, it is useful under certain
148       circumstances and should not present problems as long as one side of
149       the connection is configured to listen.
150
151   Passive
152       This parameter specifies whether the "Net::BGP::Peer" will attempt to
153       initiate connections to its peer. If set to a true value, the peer will
154       only listen for connections and will not initate connections to its
155       peer (unless the Listen parameter is set to false value). Note that
156       this behavior is not specified by RFC 1771 and should be considered
157       non-standard.  However, it is useful under certain circumstances and
158       should not present problems as long as one side of the connection is
159       configured to initiate connections.
160
161   AnnounceRefresh
162       This parameter specifies whether the "Net::BGP::Peer" will announce
163       support for route refresh ('soft re-configure' as specified by RFC
164       2918). No support for route refresh is implemented - only the
165       RefreshCallback function. This has no effect if SupportCapabilities is
166       FALSE.
167
168   SupportCapabilities
169       This parameter specifies whether the "Net::BGP::Peer" will attempt to
170       negotiate capabilities. You can set this to FALSE if talking to an old
171       BGP speaker that doesn't support it (you'll get a notification message
172       for an unsupported capability if this is the case). This defaults to
173       TRUE.
174
175   SupportMBGP
176       This parameter specifies whether the "Net::BGP::Peer" will attempt to
177       negotiate MBGP. Quagga (and probably others) need this if you want to
178       send the REFRESH capability. Today this just indicates support for IPv4
179       unicast.  This defaults to TRUE. This has no effect if
180       SupportCapabilities is FALSE.
181
182   SupportAS4
183       This parameter specifies whether outgoing connections from the
184       "Net::BGP::Peer" will attempt to negotiate AS4 (32 bit ASNs). For
185       received connections, this parameter has no effect - it only determines
186       whether or not AS4 is negotiated during outgoing connection. For
187       received connections, this will be changed to TRUE (on the listening
188       connection) whenever the appropriate OPEN capability is received. Note
189       that the SupportCapabilities must be true for this to be sent. This
190       defaults to FALSE.
191
192   OpaqueData
193       This parameter is an optional scalar that will be kept as part of the
194       "Net::BGP::Peer" and can be queried by the callback routines when they
195       receive a peer hashref - see opaque_data. This allows extra data to be
196       stored with the peer. The contents of this are completely ignored by
197       "Net::BGP::Peer". This defaults to undef.
198
199   OpenCallback
200       This parameter sets the callback function which is invoked when the
201       peer receives an OPEN message. It takes a subroutine reference. See
202       "CALLBACK FUNCTIONS" later in this manual for further details of the
203       conventions of callback invocation.
204
205   KeepaliveCallback
206       This parameter sets the callback function which is invoked when the
207       peer receives a KEEPALIVE message. It takes a subroutine reference.
208       See "CALLBACK FUNCTIONS" later in this manual for further details of
209       the conventions of callback invocation.
210
211   UpdateCallback
212       This parameter sets the callback function which is invoked when the
213       peer receives an UPDATE message. It takes a subroutine reference. See
214       "CALLBACK FUNCTIONS" later in this manual for further details of the
215       conventions of callback invocation.
216
217   RefreshCallback
218       This parameter sets the callback function which is invoked when the
219       peer receives a REFRESH message. It takes a subroutine reference. See
220       "CALLBACK FUNCTIONS" later in this manual for further details of the
221       conventions of callback invocation.
222
223   NotificationCallback
224       This parameter sets the callback function which is invoked when the
225       peer receives a NOTIFICATION message. It takes a subroutine reference.
226       See "CALLBACK FUNCTIONS" later in this manual for further details of
227       the conventions of callback invocation.
228
229   ErrorCallback
230       This parameter sets the callback function which is invoked when the
231       peer encounters an error and must send a NOTIFICATION message to its
232       peer. It takes a subroutine reference. See "CALLBACK FUNCTIONS" later
233       in this manual for further details of the conventions of callback
234       invocation.
235
236       renew - fetch the existing "Net::BGP::Peer" object from the "object
237       string".
238
239       This "reconstructor" returns a previously constructed object from the
240       perl generated string-context scalar of the object, e.g.
241       Net::BGP::Peer=HASH(0x820952c).
242

ACCESSOR METHODS

244       start() - start the BGP peering session with the peer
245
246           $peer->start();
247
248       This method initiates the BGP peering session with the peer by
249       internally emitting the BGP Start event, which causes the peer to
250       initiate a transport-layer connection to its peer (unless the Passive
251       parameter was set to a true value in the constructor) and listen for a
252       connection from the peer (unless the Listen parameter is set to a false
253       value).
254
255       stop() - cease the BGP peering session with the peer
256
257           $peer->stop();
258
259       This method immediately ceases the peering session with the peer by
260       sending it a NOTIFICATION message with Error Code Cease, closing the
261       transport-layer connection, and entering the Idle state.
262
263       update() - send a BGP UPDATE message to the peer
264
265           $peer->update($update);
266
267       This method sends the peer an UPDATE message. It takes a reference to a
268       Net::BGP::Update object. See the Net::BGP::Update manual page for
269       details on setting UPDATE attributes.
270
271       refresh() - send a BGP REFRESH message to the peer
272
273           $peer->refresh($refresh);
274
275       This method sends the peer a REFRESH message. It takes a reference to a
276       Net::BGP::Refresh object. If no argument is provided, a default
277       Net::BGP::Refresh object is constructed. See the Net::BGP::Refresh
278       manual page for details on setting REFRESH attributes.
279
280       this_id()
281
282       this_as()
283
284       peer_id()
285
286       peer_as()
287
288       this_can_refresh()
289
290       support_capabilities()
291
292       support_mbgp()
293
294       is_listener()
295
296       is_passive()
297
298       version()
299
300       These are accessor methods for the corresponding constructor named
301       parameters.  They retrieve the values set when the object was created,
302       but the values cannot be changed after object construction. Hence, they
303       take no arguments.
304
305       opaque_data()
306
307           $peer->opaque_data();
308           $peer->opaque_data($new_ref);
309
310       This method can be used to both query (no argument) or set (with an
311       argument) the opaque data held with the peer object. The method returns
312       the old opaque data scalar (which is the current value if not
313       provided).
314
315       is_established()
316
317       This accessor method returns true if the peer has a established
318       transport connection - e.g. the peering is up.
319
320       peer_can_refresh()
321
322       This accessor method returns a true value if connected to a peer that
323       supports refresh messages - otherwise a false value.
324
325       asstring()
326
327       This accessor method returns a print friendly string with the local and
328       remote IP and AS numbers.
329
330       set_open_callback()
331
332       set_established_callback()
333
334       set_keepalive_callback()
335
336       set_update_callback()
337
338       set_refresh_callback()
339
340       set_reset_callback()
341
342       set_notification_callback()
343
344       set_error_callback()
345
346       These methods set the callback functions which are invoked whenever the
347       peer receives the corresponding BGP message type from its peer, or, in
348       the case of set_established_callback, transitions to the relevant
349       state. They can be set in the constructor as well as with these
350       methods. These methods each take one argument, which is the subroutine
351       reference to be invoked.  A callback function can be removed by calling
352       the corresponding one of these methods and passing it the perl undef
353       value. For callback definition and invocation conventions see "CALLBACK
354       FUNCTIONS" later in this manual.
355
356       add_timer() - add a program defined timer callback function
357
358           $peer->add_timer(\&my_minute_timer, 60);
359
360       This method sets a program defined timer which invokes the specified
361       callback function when the timer expires. It takes two arguments: the
362       first is a code reference to the subroutine to be invoked when the
363       timer expires, and the second is the timer interval, in seconds. The
364       program may set as many timers as needed, and multiple timer callbacks
365       may share the same interval. Program timers add an asynchronous means
366       for user code to gain control of the program control flow - without
367       them user code would only be invoked whenever BGP events exposed by the
368       module occur. They may be used to perform any necessary action - for
369       example, sending UPDATEs, starting or stopping the peering session,
370       house-keeping, etc.
371
372       remove_timer() - remove a program defined timer callback function
373
374           $peer->remove_timer(\&my_minute_timer);
375
376       This method removes a program defined timer callback which has been
377       previously set with the add_timer() method. It takes a single argument:
378       a reference to the subroutine previously added.
379

CALLBACK FUNCTIONS

381       Whenever a "Net::BGP::Peer" object receives one of the BGP protocol
382       messages - OPEN, KEEPALIVE, UPDATE, REFRESH, or NOTIFICATION - from its
383       peer, or whenever it encounters an error condition and must send a
384       NOTIFICATION message to its peer, the peer object will invoke a program
385       defined callback function corresponding to the event type, if one has
386       been provided, to inform the application about the event. These
387       callback functions are installed as described in the preceding section
388       of the manual. Whenever any callback function is invoked, it is passed
389       one or more arguments, depending on the BGP message type associated
390       with the callback. The first argument passed to all of the callbacks is
391       a reference to the "Net::BGP::Peer" object which the application may
392       use to identify which peer has signalled the event and to take
393       appropriate action. For OPEN and KEEPALIVE callbacks, this is the only
394       argument passed. It is very unlikely that applications will be
395       interested in OPEN and KEEPALIVE events, since the "Net::BGP" module
396       handles all details of OPEN and KEEPALIVE message processing in order
397       to establish and maintain BGP sessions. Callback handling for these
398       messages is mainly included for the sake of completeness. For UPDATE
399       and NOTIFICATION messages, however, most applications will install
400       callback handlers.  Whenever an UPDATE, REFRESH, NOTIFICATION, or error
401       handler is called, the object will pass a second argument. In the first
402       two cases, this is a Net::BGP::Update or Net::BGP::Refresh object
403       respectivly encapsulating the information contained in the UPDATE or
404       REFRESH message, while in the latter two cases it is a
405       Net::BGP::Notification object encapsulating the information in the
406       NOTIFICATION message sent or received.
407
408       The RESET and ESTABLISHED callbacks are special, since they are used
409       whenever an established BGP session is reset, even though no message
410       has been recieved or sent.  The REFRESH callback is also special, since
411       it is also called without a REFRESH object whenever a BGP session is
412       established. The two callbacks can be used to clear and retransmit a
413       RIB from/to the peer in question.
414
415       Whenever a callback function is to be invoked, the action occuring
416       internally is the invocation of one of the following methods,
417       corresponding to the event which has occured:
418
419       open_callback()
420
421       established_callback()
422
423       keepalive_callback()
424
425       update_callback()
426
427       refresh_callback()
428
429       reset_callback()
430
431       notification_callback()
432
433       error_callback()
434
435       Internally, each of these methods just checks to see whether a program
436       defined callback function has been set and calls it if so, passing it
437       arguments as described above. As an alternative to providing subroutine
438       references to the constructor or through the set_open_callback(),
439       set_established_callback(), set_keepalive_callback(),
440       set_update_callback(), set_refresh_callback(), set_reset_callback(),
441       set_notification_callback(), and set_error_callback() methods, an
442       application may effect a similar result by sub-classing the
443       "Net::BGP::Peer" module and overridding the defintions of the above
444       methods to perform whatever actions would have been executed by
445       ordinary callback functions.  The overridden methods are passed the
446       same arguments as the callback functions.  This method might offer an
447       advantage in organizing code according to different derived classes
448       which apply specifc routing policies.
449

ERROR HANDLING

451       There are two possibilities for error handling callbacks to be invoked.
452       The first case occurs when the peer receives a NOTIFICATION messages
453       from its peer. The second case occurs when the peer detects an error
454       condition while processing an incoming BGP message or when some other
455       protocol covenant is violated - for example if a KEEPALIVE or UPDATE
456       message is not received before the peer's Keepalive timer expires. In
457       this case, the peer responds by sending a NOTIFICATION message to its
458       peer. In the former case the notification_callback() method is invoked
459       as described above to handle the error, while in the latter the
460       error_callback() method is invoked to inform the application that it
461       has encountered an error. Both methods are passed a
462       Net::BGP::Notification object encapsulating the details of the error.
463       In both cases, the transport-layer connection and BGP session are
464       closed and the peer transitions to the Idle state.  The error handler
465       callbacks can examine the cause of the error and take appropriate
466       action. This could be to attempt to re-establish the session (perhaps
467       after sleeping for some amount of time), or to unregister the peer
468       object from the Net::BGP::Process object and permanently end the
469       session (for the duration of the application's running time), or to log
470       the event to a file on the host system, or some combination of these or
471       none.
472

SEE ALSO

474       Net::BGP
475       Net::BGP::Process
476       Net::BGP::Update
477       Net::BGP::Refresh
478       Net::BGP::ASPath
479       Net::BGP::NLRI
480       Net::BGP::Notification
481

AUTHOR

483       Stephen J. Scheck <sscheck@cpan.org>
484
485
486
487perl v5.36.0                      2022-07-22                 Net::BGP::Peer(3)
Impressum