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

NAME

6       Net::BGP - Border Gateway Protocol version 4 speaker/listener library
7

SYNOPSIS

9           use Net::BGP::Process;
10           use Net::BGP::Peer;
11
12           $bgp  = Net::BGP::Process->new();
13           $peer = Net::BGP::Peer->new(
14               Start    => 1,
15               ThisID   => '10.0.0.1',
16               ThisAS   => 64512,
17               PeerID   => '10.0.0.2',
18               PeerAS   => 64513
19           );
20
21           $bgp->add_peer($peer);
22           $peer->add_timer(\&my_timer_callback, 60);
23           $bgp->event_loop();
24

DESCRIPTION

26       This module is an implementation of the BGP-4 inter-domain routing
27       protocol.  It encapsulates all of the functionality needed to establish
28       and maintain a BGP peering session and exchange routing update
29       information with the peer.  It aims to provide a simple API to the BGP
30       protocol for the purposes of automation, logging, monitoring, testing,
31       and similar tasks using the power and flexibility of perl. The module
32       does not implement the functionality of a RIB (Routing Information
33       Base) nor does it modify the kernel routing table of the host system.
34       However, such operations could be implemented using the API provided by
35       the module.
36
37       The module takes an object-oriented approach to abstracting the
38       operations of the BGP protocol. It supports multiple peering sessions
39       and each peer corresponds to one instance of a Net::BGP::Peer object.
40       The details of maintaining each peering session are handled and
41       coordinated by an instance of a Net::BGP::Process object. BGP UPDATE
42       messages and the routing information they represent are encapsulated by
43       Net::BGP::Update objects.  Whenever protocol errors occur and a BGP
44       NOTIFICATION is sent or received, programs can determine the details of
45       the error via Net::BGP::Notification objects.
46
47       The module interacts with client programs through the paradigm of
48       callback functions. Whenever interesting protocol events occur, a
49       callback function supplied by the user is called and information
50       pertaining to the event is passed to the function for examination or
51       action. For instance, whenever an UPDATE message is received from a
52       peer, the module handles the details of decoding the message,
53       validating it, and encapsulating it in an object and passing the object
54       to the specific callback function supplied by the user for UPDATE
55       message handling. The callback function is free to do whatever with the
56       object - it might send a Net::BGP::Update object to other peers as
57       UPDATE messages, perhaps after modifying some of the UPDATE attributes,
58       log the routing information to a file, or do nothing at all. The
59       possibilities for implementing routing policy via such a mechanism are
60       limited only by the expressive capabilities of the perl language. It
61       should be noted however that the module is intended for the uses stated
62       above and probably would not scale well for very large BGP meshes or
63       routing tables.
64
65       The module must maintain periodic protocol keep-alive and other
66       processes, so once control is passed to the module's main event loop,
67       control flow only passes back to user code whenever one of the callback
68       functions is invoked. To provide more interaction with user programs,
69       the module allows user timers to be established and called periodically
70       to perform further processing. Multiple timers may be established, and
71       each is associated with a single peer. Whenever the timers expire, a
72       user supplied function is called and the timer is reset. The timer
73       callback functions can perform whatever actions are necessary - sending
74       UPDATEs, modifying the state of the peering session, house-keeping,
75       etc.
76

BUGS

78       The connection collision resolution code is broken. As currently
79       implemented, whenever a connection is received from a peer, the
80       Net::BGP::Peer object is cloned and each peer object proceeds through
81       the session establishment process until the collision resolution
82       procedure is reached. At this point, if the cloned object is chosen by
83       the collison resolution procedure, the original peer object is
84       destroyed, leaving the cloned object. Unfortunately, a user program
85       will only have a reference to the original peer object it created and
86       will have no way of accessing the cloned object. It is therefore
87       recommended that Net::BGP::Peer objects be instantiated with the Listen
88       parameter set to a false value. This prevents the peer object from
89       receiving connections from its BGP peer, although it will continue
90       actively attempting to establish sessions. This problem will be
91       addressed in a future revision of Net::BGP.
92
93       As an initial revision, the code has not been subjected to a thorough
94       security audit. It is possible and likely that exploitable code exists
95       in the packet decoding routines. Therefore, it is recommended that the
96       module only be used to establish peering sessions with trusted peers,
97       particularly if programs using the module will be run with root
98       priviliges (which is necessary if programs want to modify the kernel
99       routing table or bind to the well-known BGP port 179).
100

SEE ALSO

102       RFC 1771, and the perldocs for Net::BGP::Process, Net::BGP::Peer,
103       Net::BGP::Update, and Net::BGP::Notification
104

AUTHOR

106       Stephen J. Scheck <sscheck@cpan.org>
107
108
109
110perl v5.30.0                      2019-08-06                       Net::BGP(3)
Impressum