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
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 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 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 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 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 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 previously constructed object from the
240 perl generated string-context scalar of the object, e.g.
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::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 this_id()
281 this_as()
283 peer_id()
285 peer_as()
287 this_can_refresh()
289 support_capabilities()
291 support_mbgp()
293 is_listener()
295 is_passive()
297 version()
299 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 opaque_data()
306 $peer->opaque_data();
308 $peer->opaque_data($new_ref);
309 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 is_established()
316 This accessor method returns true if the peer has a established
318 transport connection - e.g. the peering is up.
319 peer_can_refresh()
321 This accessor method returns a true value if connected to a peer that
323 supports refresh messages - otherwise a false value.
324 asstring()
326 This accessor method returns a print friendly string with the local and
328 remote IP and AS numbers.
329 set_open_callback()
331 set_established_callback()
333 set_keepalive_callback()
335 set_update_callback()
337 set_refresh_callback()
339 set_reset_callback()
341 set_notification_callback()
343 set_error_callback()
345 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 add_timer() - add a program defined timer callback function
357 $peer->add_timer(\&my_minute_timer, 60);
359 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 remove_timer() - remove a program defined timer callback function
373 $peer->remove_timer(\&my_minute_timer);
375 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
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 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 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 open_callback()
420 established_callback()
422 keepalive_callback()
424 update_callback()
426 refresh_callback()
428 reset_callback()
430 notification_callback()
432 error_callback()
434 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
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
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
483 Stephen J. Scheck <sscheck@cpan.org>
484perl v5.36.0 2022-07-22 Net::BGP::Peer(3)