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 OpenCallback => \&my_open_callback,
29 KeepaliveCallback => \&my_keepalive_callback,
30 UpdateCallback => \&my_update_callback,
31 NotificationCallback => \&my_notification_callback,
32 ErrorCallback => \&my_error_callback
33 );
34 $peer = renew Net::BGP::Peer("$peer");
36 $peer->start();
38 $peer->stop();
39 $peer->update($update);
41 $peer->refresh($refresh);
42 $version = $peer->version();
44 $this_id = $peer->this_id();
46 $this_as = $peer->this_as();
47 $peer_id = $peer->peer_id();
48 $peer_as = $peer->peer_as();
49 $i_will = $peer->support_capabilities();
51 $i_mbgp = $peer->support_mbgp();
53 $i_can = $peer->this_can_refresh();
55 $peer_can= $peer->peer_can_refresh();
56 $peer_as4= $peer->peer_can_as4();
58 $listen = $peer->is_listener();
60 $passive = $peer->is_passive();
61 $estab = $peer->is_established();
62 $trans = $peer->transport($trans);
64 @trans = $peer->transports;
65 $string = $peer->asstring();
67 $peer->set_open_callback(\&my_open_callback);
69 $peer->set_established_callback(\&my_established_callback);
70 $peer->set_keepalive_callback(\&my_keepalive_callback);
71 $peer->set_update_callback(\&my_update_callback);
72 $peer->set_notification_callback(\&my_notification_callback);
73 $peer->set_error_callback(\&my_error_callback);
74 $peer->add_timer(\&my_minute_timer, 60);
76 $peer->remove_timer(\&my_minute_timer);
77
79 This module encapsulates the state and functionality associated with a
80 BGP peering session. Each instance of a Net::BGP::Peer object
81 corresponds to a peering session with a distinct peer and presents a
82 programming interface to manipulate the peering session state and
83 exchange of routing information. Through the methods provided by the
84 Net::BGP::Peer module, a program can start or stop peering sessions,
85 send BGP routing UPDATE messages, and register callback functions which
86 are invoked whenever the peer receives BGP messages from its peer.
87
89 new() - create a new Net::BGP::Peer object
90 This is the constructor for Net::BGP::Peer objects. It returns a
92 reference to the newly created object. The following named parameters
93 may be passed to the constructor. Once the object is created, only the
94 callback function references can later be changed.
95 Start
97 Setting this parameter to a true value causes the peer to initiate a
98 session with its peer immediately after it is registered with the
99 Net::BGP::Process object's add_peer() method. If omitted or set to a
100 false value, the peer will remain in the Idle state until the start()
101 method is called explicitly by the program. When in the Idle state the
102 peer will refuse connections and will not initiate connection attempts.
103 ThisID
105 This parameter sets the BGP ID (IP address) of the Net::BGP::Peer
106 object. It takes a string in IP dotted decimal notation.
107 ThisAS
109 This parameter sets the BGP Autonomous System number of the
110 Net::BGP::Peer object. It takes an integer value in the range of a
111 16-bit unsigned integer.
112 PeerID
114 This parameter sets the BGP ID (IP address) of the object's peer. It
115 takes a string in IP dotted decimal notation.
116 PeerAS
118 This parameter sets the BGP Autonomous System number of the object's
119 peer. It takes an integer value in the range of a 16-bit unsigned
120 integer.
121 PeerPort
123 This parameter sets the TCP port number on the peer to which to
124 connect. It must be in the range of a valid TCP port number.
125 ConnectRetryTime
127 This parameter sets the BGP ConnectRetry timer duration, the value of
128 which is given in seconds.
129 HoldTime
131 This parameter sets the BGP Hold Time duration, the value of which is
132 given in seconds.
133 KeepAliveTime
135 This parameter sets the BGP KeepAlive timer duration, the value of
136 which is given in seconds.
137 Listen
139 This parameter specifies whether the Net::BGP::Peer will listen for and
140 accept connections from its peer. If set to a false value, the peer
141 will only initiate connections and will not accept connection attempts
142 from the peer (unless the Passive parameter is set to a true value).
143 Note that this behavior is not specified by RFC 1771 and should be
144 considered non-standard. However, it is useful under certain
145 circumstances and should not present problems as long as one side of
146 the connection is configured to listen.
147 Passive
149 This parameter specifies whether the Net::BGP::Peer will attempt to
150 initiate connections to its peer. If set to a true value, the peer will
151 only listen for connections and will not initate connections to its
152 peer (unless the Listen parameter is set to false value). Note that
153 this behavior is not specified by RFC 1771 and should be considered
154 non-standard. However, it is useful under certain circumstances and
155 should not present problems as long as one side of the connection is
156 configured to initiate connections.
157 Refresh
159 This parameter specifies whether the Net::BGP::Peer will annonce
160 support for route refresh ('soft re-configure' as specified by RFC
161 2918). No support for route refresh is implemented - only the
162 RefreshCallback function. This has no effect if SupportCapabilities is
163 FALSE.
164 SupportCapabilities
166 This parameter specifies whether the Net::BGP::Peer will attempt to
167 negotiate capabilities. You can set this to FALSE if talking to an old
168 BGP speaker that doesn't support it (you'll get a notification message
169 for an unsupported capability if this is the case). This defaults to
170 TRUE.
171 SupportMBGP
173 This parameter specifies whether the NET::BGP::Peer will attempt to
174 negotiate MBGP. Quagga (and probably others) need this if you want to
175 send the REFRESH capability. Today this just indicates support for IPv4
176 Unicast. This defaults to TRUE. This has no effect if
177 SupportCapabilities is FALSE.
178 SupportAS4
180 This paramemter specifies whether outgoing connections from
181 NET::BGP::Peer will attempt to negotiate AS4 (32 bit ASNs). For
182 received connections, this parameter has no effect - it only determines
183 whether or not AS4 is negotiated during outgoing connection. For
184 received connections, this will be changed to TRUE (on the listening
185 connection) whenever the appropriate OPEN capability is received. Note
186 that the SupportCapabilities must be true for this to be sent. This
187 defaults to FALSE.
188 OpenCallback
190 This parameter sets the callback function which is invoked when the
191 peer receives an OPEN message. It takes a subroutine reference. See
192 "CALLBACK FUNCTIONS" later in this manual for further details of the
193 conventions of callback invocation.
194 KeepaliveCallback
196 This parameter sets the callback function which is invoked when the
197 peer receives a KEEPALIVE message. It takes a subroutine reference.
198 See "CALLBACK FUNCTIONS" later in this manual for further details of
199 the conventions of callback invocation.
200 UpdateCallback
202 This parameter sets the callback function which is invoked when the
203 peer receives an UPDATE message. It takes a subroutine reference. See
204 "CALLBACK FUNCTIONS" later in this manual for further details of the
205 conventions of callback invocation.
206 RefreshCallback
208 This parameter sets the callback function which is invoked when the
209 peer receives a REFRESH message. It takes a subroutine reference. See
210 "CALLBACK FUNCTIONS" later in this manual for further details of the
211 conventions of callback invocation.
212 NotificationCallback
214 This parameter sets the callback function which is invoked when the
215 peer receives a NOTIFICATION message. It takes a subroutine reference.
216 See "CALLBACK FUNCTIONS" later in this manual for further details of
217 the conventions of callback invocation.
218 ErrorCallback
220 This parameter sets the callback function which is invoked when the
221 peer encounters an error and must send a NOTIFICATION message to its
222 peer. It takes a subroutine reference. See "CALLBACK FUNCTIONS" later
223 in this manual for further details of the conventions of callback
224 invocation.
225 renew - fetch the existing Net::BGP::Peer object from the "object
227 string".
228 This "reconstructor" returns a previeus constructed object from the
230 perl genereted string-context scalar of the object, eg.
231 Net::BGP::Peer=HASH(0x820952c).
232
234 start() - start the BGP peering session with the peer
235 $peer->start();
237 This method initiates the BGP peering session with the peer by
239 internally emitting the BGP Start event, which causes the peer to
240 initiate a transport-layer connection to its peer (unless the Passive
241 parameter was set to a true value in the constructor) and listen for a
242 connection from the peer (unless the Listen parameter is set to a false
243 value).
244 stop() - cease the BGP peering session with the peer
246 $peer->stop();
248 This method immediately ceases the peering session with the peer by
250 sending it a NOTIFICATION message with Error Code Cease, closing the
251 transport-layer connection, and entering the Idle state.
252 update() - send a BGP UPDATE message to the peer
254 $peer->update($update);
256 This method sends the peer an UPDATE message. It takes a reference to a
258 Net::BGP::Update object. See the Net::BGP::Update manual page for
259 details on setting UPDATE attributes.
260 refresh() - send a BGP REFRESH message to the peer
262 $peer->refresh($refresh);
264 This method sends the peer a REFRESH message. It takes a reference to a
266 Net::BGP::Refesh object. If no argument is provided, a default
267 Net::BGP::Refresh object is constructed. See the Net::BGP::Refresh
268 manual page for details on setting REFRESH attributes.
269 transport()
271 Returns the active transport object to the peer - See
273 Net::BGP::Transport.
274 transports()
276 Return a list of transport objects. The list will contain one or two
278 elements. The first will always be the primary transport object. If
279 there are two sessions (e.g. collision detection hasn't removed one of
280 them), the sibling will be returned as the second element of the list.
281 this_id()
283 this_as()
285 peer_id()
287 peer_as()
289 this_can_refresh()
291 support_capabilities()
293 support_mbgp()
295 is_listener()
297 is_passive()
299 version()
301 These are accessor methods for the corresponding constructor named
303 parameters. They retrieve the values set when the object was created,
304 but the values cannot be changed after object construction. Hence, they
305 take no arguments.
306 is_established()
308 This accessor method returns true if the peer has a established
310 transport connection - e.g. the peering is up.
311 peer_can_refresh()
313 This accessor method returns a true value if connected to a peer that
315 supports refresh messages - otherwise a false value.
316 asstring()
318 This accessor method returns a print friendly string with the local and
320 remote IP and AS numbers.
321 set_open_callback()
323 set_established_callback()
325 set_keepalive_callback()
327 set_update_callback()
329 set_refresh_callback()
331 set_reset_callback()
333 set_notification_callback()
335 set_error_callback()
337 These methods set the callback functions which are invoked whenever the
339 peer receives the corresponding BGP message type from its peer, or, in
340 the case of set_established_callback, transitions to the relevant
341 state. They can be set in the constructor as well as with these
342 methods. These methods each take one argument, which is the subroutine
343 reference to be invoked. A callback function can be removed by calling
344 the corresponding one of these methods and passing it the perl undef
345 value. For callback definition and invocation conventions see "CALLBACK
346 FUNCTIONS" later in this manual.
347 add_timer() - add a program defined timer callback function
349 $peer->add_timer(\&my_minute_timer, 60);
351 This method sets a program defined timer which invokes the specified
353 callback function when the timer expires. It takes two arguments: the
354 first is a code reference to the subroutine to be invoked when the
355 timer expires, and the second is the timer interval, in seconds. The
356 program may set as many timers as needed, and multiple timer callbacks
357 may share the same interval. Program timers add an asynchronous means
358 for user code to gain control of the program control flow - without
359 them user code would only be invoked whenever BGP events exposed by the
360 module occur. They may be used to perform any necessary action - for
361 example, sending UPDATEs, starting or stopping the peering session,
362 house-keeping, etc.
363 remove_timer() - remove a program defined timer callback function
365 $peer->remove_timer(\&my_minute_timer);
367 This method removes a program defined timer callback which has been
369 previously set with the add_timer() method. It takes a single argument:
370 a reference to the subroutine previously added.
371
373 Whenever a Net::BGP::Peer object receives one of the BGP protocol
374 messages - OPEN, KEEPALIVE, UPDATE, REFRESH, or NOTIFICATION - from its
375 peer, or whenever it encounters an error condition and must send a
376 NOTIFICATION message to its peer, the peer object will invoke a program
377 defined callback function corresponding to the event type, if one has
378 been provided, to inform the application about the event. These
379 callback functions are installed as described in the preceding section
380 of the manual. Whenever any callback function is invoked, it is passed
381 one or more arguments, depending on the BGP message type associated
382 with the callback. The first argument passed to all of the callbacks is
383 a reference to the Net::BGP::Peer object which the application may use
384 to identify which peer has signalled the event and to take appropriate
385 action. For OPEN and KEEPALIVE callbacks, this is the only argument
386 passed. It is very unlikely that applications will be interested in
387 OPEN and KEEPALIVE events, since the Net::BGP module handles all
388 details of OPEN and KEEPALIVE message processing in order to establish
389 and maintain BGP sessions. Callback handling for these messages is
390 mainly included for the sake of completeness. For UPDATE and
391 NOTIFICATION messages, however, most applications will install callback
392 handlers. Whenever an UPDATE, REFRESH, NOTIFICATION, or error handler
393 is called, the object will pass a second argument. In the first two
394 cases, this is a Net::BGP::Update or Net::BGP::Refresh object
395 respectivly encapsulating the information contained in the UPDATE or
396 REFRESH message, while in the latter two cases it is a
397 Net::BGP::Notification object encapsulating the information in the
398 NOTIFICATION message sent or received.
399 The RESET and ESTABLISHED callbacks are special, since they are used
401 whenever an established BGP session is reset, even though no message
402 has been recieved or sent. The REFRESH callback is also special, since
403 it is also called without a REFRESH object whenever a BGP session is
404 established. The two callbacks can be used to clear and retransmit a
405 RIB from/to the peer in question.
406 Whenever a callback function is to be invoked, the action occuring
408 internally is the invocation of one of the following methods,
409 corresponding to the event which has occured:
410 open_callback()
412 established_callback()
414 keepalive_callback()
416 update_callback()
418 refresh_callback()
420 reset_callback()
422 notification_callback()
424 error_callback()
426 Internally, each of these methods just checks to see whether a program
428 defined callback function has been set and calls it if so, passing it
429 arguments as described above. As an alternative to providing subroutine
430 references to the constructor or through the set_open_callback(),
431 set_established_callback(), set_keepalive_callback(),
432 set_update_callback(), set_refresh_callback(), set_reset_callback(),
433 set_notification_callback(), and set_error_callback() methods, an
434 application may effect a similar result by sub-classing the
435 Net::BGP::Peer module and overridding the defintions of the above
436 methods to perform whatever actions would have been executed by
437 ordinary callback functions. The overridden methods are passed the
438 same arguments as the callback functions. This method might offer an
439 advantage in organizing code according to different derived classes
440 which apply specifc routing policies.
441
443 There are two possibilities for error handling callbacks to be invoked.
444 The first case occurs when the peer receives a NOTIFICATION messages
445 from its peer. The second case occurs when the peer detects an error
446 condition while processing an incoming BGP message or when some other
447 protocol covenant is violated - for example if a KEEPALIVE or UPDATE
448 message is not received before the peer's Keepalive timer expires. In
449 this case, the peer responds by sending a NOTIFICATION message to its
450 peer. In the former case the notification_callback() method is invoked
451 as described above to handle the error, while in the latter the
452 error_callback() method is invoked to inform the application that it
453 has encountered an error. Both methods are passed a
454 Net::BGP::Notification object encapsulating the details of the error.
455 In both cases, the transport-layer connection and BGP session are
456 closed and the peer transitions to the Idle state. The error handler
457 callbacks can examine the cause of the error and take appropriate
458 action. This could be to attempt to re-establish the session (perhaps
459 after sleeping for some amount of time), or to unregister the peer
460 object from the Net::BGP::Process object and permanently end the
461 session (for the duration of the application's running time), or to log
462 the event to a file on the host system, or some combination of these or
463 none.
464
466 Net::BGP, Net::BGP::Process, Net::BGP::Update, Net::BGP::Transport,
467 Net::BGP::Refresh, Net::BGP::Notification
468
470 Stephen J. Scheck <code@neurosphere.com>
471perl v5.28.1 2015-01-27 Net::BGP::Peer(3)