1Net::BGP::Peer(3) User Contributed Perl Documentation Net::BGP::Peer(3)
2
6 Net::BGP::Peer - Class encapsulating BGP-4 peering session state and
7 functionality
8
10 use Net::BGP::Peer;
11 $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 $peer = renew Net::BGP::Peer("$peer");
37 $peer->start();
39 $peer->stop();
40 $peer->update($update);
42 $peer->refresh($refresh);
43 $version = $peer->version();
45 $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 $i_will = $peer->support_capabilities();
54 $i_mbgp = $peer->support_mbgp();
56 $i_can = $peer->this_can_refresh();
58 $peer_can= $peer->peer_can_refresh();
59 $peer_as4= $peer->peer_can_as4();
61 $listen = $peer->is_listener();
63 $passive = $peer->is_passive();
64 $estab = $peer->is_established();
65 $trans = $peer->transport($trans);
67 @trans = $peer->transports;
68 $string = $peer->asstring();
70 $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 $peer->add_timer(\&my_minute_timer, 60);
79 $peer->remove_timer(\&my_minute_timer);
80
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
92 new() - create a new Net::BGP::Peer object
93 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 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 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 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 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 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 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 ConnectRetryTime
130 This parameter sets the BGP ConnectRetry timer duration, the value of
131 which is given in seconds.
132 HoldTime
134 This parameter sets the BGP Hold Time duration, the value of which is
135 given in seconds.
136 KeepAliveTime
138 This parameter sets the BGP KeepAlive timer duration, the value of
139 which is given in seconds.
140 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 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 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 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 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 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 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 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 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 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 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 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 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 renew - fetch the existing Net::BGP::Peer object from the "object
237 string".
238 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
244 start() - start the BGP peering session with the peer
245 $peer->start();
247 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 stop() - cease the BGP peering session with the peer
256 $peer->stop();
258 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 update() - send a BGP UPDATE message to the peer
264 $peer->update($update);
266 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 refresh() - send a BGP REFRESH message to the peer
272 $peer->refresh($refresh);
274 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 transport()
281 Returns the active transport object to the peer - See
283 Net::BGP::Transport.
284 transports()
286 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 this_id()
293 this_as()
295 peer_id()
297 peer_as()
299 this_can_refresh()
301 support_capabilities()
303 support_mbgp()
305 is_listener()
307 is_passive()
309 version()
311 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 opaque_data()
318 $peer->opaque_data();
320 $peer->opaque_data($new_ref);
321 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 is_established()
328 This accessor method returns true if the peer has a established
330 transport connection - e.g. the peering is up.
331 peer_can_refresh()
333 This accessor method returns a true value if connected to a peer that
335 supports refresh messages - otherwise a false value.
336 asstring()
338 This accessor method returns a print friendly string with the local and
340 remote IP and AS numbers.
341 set_open_callback()
343 set_established_callback()
345 set_keepalive_callback()
347 set_update_callback()
349 set_refresh_callback()
351 set_reset_callback()
353 set_notification_callback()
355 set_error_callback()
357 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 add_timer() - add a program defined timer callback function
369 $peer->add_timer(\&my_minute_timer, 60);
371 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 remove_timer() - remove a program defined timer callback function
385 $peer->remove_timer(\&my_minute_timer);
387 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
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 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 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 open_callback()
432 established_callback()
434 keepalive_callback()
436 update_callback()
438 refresh_callback()
440 reset_callback()
442 notification_callback()
444 error_callback()
446 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
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
486 Net::BGP, Net::BGP::Process, Net::BGP::Update, Net::BGP::Transport,
487 Net::BGP::Refresh, Net::BGP::Notification
488
490 Stephen J. Scheck <sscheck@cpan.org>
491perl v5.32.1 2021-01-27 Net::BGP::Peer(3)