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 and
143       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   Refresh
162       This parameter specifies whether the Net::BGP::Peer will annonce
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 paramemter specifies whether outgoing connections from
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 previeus constructed object from the
240       perl genereted string-context scalar of the object, eg.
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::Refesh 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       transport()
281
282       Returns the active transport object to the peer - See
283       Net::BGP::Transport.
284
285       transports()
286
287       Return a list of transport objects. The list will contain one or two
288       elements.  The first will always be the primary transport object. If
289       there are two sessions (e.g. collision detection hasn't removed one of
290       them), the sibling will be returned as the second element of the list.
291
292       this_id()
293
294       this_as()
295
296       peer_id()
297
298       peer_as()
299
300       this_can_refresh()
301
302       support_capabilities()
303
304       support_mbgp()
305
306       is_listener()
307
308       is_passive()
309
310       version()
311
312       These are accessor methods for the corresponding constructor named
313       parameters.  They retrieve the values set when the object was created,
314       but the values cannot be changed after object construction. Hence, they
315       take no arguments.
316
317       opaque_data()
318
319           $peer->opaque_data();
320           $peer->opaque_data($new_ref);
321
322       This method can be used to both query (no argument) or set (with an
323       argument) the opaque data held with the peer object. The method returns
324       the old opaque data scalar (which is the current value if not
325       provided).
326
327       is_established()
328
329       This accessor method returns true if the peer has a established
330       transport connection - e.g. the peering is up.
331
332       peer_can_refresh()
333
334       This accessor method returns a true value if connected to a peer that
335       supports refresh messages - otherwise a false value.
336
337       asstring()
338
339       This accessor method returns a print friendly string with the local and
340       remote IP and AS numbers.
341
342       set_open_callback()
343
344       set_established_callback()
345
346       set_keepalive_callback()
347
348       set_update_callback()
349
350       set_refresh_callback()
351
352       set_reset_callback()
353
354       set_notification_callback()
355
356       set_error_callback()
357
358       These methods set the callback functions which are invoked whenever the
359       peer receives the corresponding BGP message type from its peer, or, in
360       the case of set_established_callback, transitions to the relevant
361       state. They can be set in the constructor as well as with these
362       methods. These methods each take one argument, which is the subroutine
363       reference to be invoked.  A callback function can be removed by calling
364       the corresponding one of these methods and passing it the perl undef
365       value. For callback definition and invocation conventions see "CALLBACK
366       FUNCTIONS" later in this manual.
367
368       add_timer() - add a program defined timer callback function
369
370           $peer->add_timer(\&my_minute_timer, 60);
371
372       This method sets a program defined timer which invokes the specified
373       callback function when the timer expires. It takes two arguments: the
374       first is a code reference to the subroutine to be invoked when the
375       timer expires, and the second is the timer interval, in seconds. The
376       program may set as many timers as needed, and multiple timer callbacks
377       may share the same interval. Program timers add an asynchronous means
378       for user code to gain control of the program control flow - without
379       them user code would only be invoked whenever BGP events exposed by the
380       module occur. They may be used to perform any necessary action - for
381       example, sending UPDATEs, starting or stopping the peering session,
382       house-keeping, etc.
383
384       remove_timer() - remove a program defined timer callback function
385
386           $peer->remove_timer(\&my_minute_timer);
387
388       This method removes a program defined timer callback which has been
389       previously set with the add_timer() method. It takes a single argument:
390       a reference to the subroutine previously added.
391

CALLBACK FUNCTIONS

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

ERROR HANDLING

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

SEE ALSO

486       Net::BGP, Net::BGP::Process, Net::BGP::Update, Net::BGP::Transport,
487       Net::BGP::Refresh, Net::BGP::Notification
488

AUTHOR

490       Stephen J. Scheck <sscheck@cpan.org>
491
492
493
494perl v5.32.1                      2021-01-27                 Net::BGP::Peer(3)
Impressum