File Coverage

blib/lib/Net/BGP.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1             #!/usr/bin/perl
2              
3             package Net::BGP;
4              
5 3     3   2115 use strict;
  3         8  
  3         93  
6 3     3   14 use vars qw( $VERSION );
  3         5  
  3         237  
7              
8             ## Inheritance and Versioning ##
9              
10             $VERSION = '0.17';
11              
12             ## End Code Section ##
13              
14             =pod
15              
16             =head1 NAME
17              
18             Net::BGP - Border Gateway Protocol version 4 speaker/listener library
19              
20             =head1 SYNOPSIS
21              
22             use Net::BGP::Process;
23             use Net::BGP::Peer;
24              
25             $bgp = Net::BGP::Process->new();
26             $peer = Net::BGP::Peer->new(
27             Start => 1,
28             ThisID => '10.0.0.1',
29             ThisAS => 64512,
30             PeerID => '10.0.0.2',
31             PeerAS => 64513
32             );
33              
34             $bgp->add_peer($peer);
35             $peer->add_timer(\&my_timer_callback, 60);
36             $bgp->event_loop();
37              
38             =head1 DESCRIPTION
39              
40             This module is an implementation of the BGP-4 inter-domain routing protocol.
41             It encapsulates all of the functionality needed to establish and maintain a
42             BGP peering session and exchange routing update information with the peer.
43             It aims to provide a simple API to the BGP protocol for the purposes of
44             automation, logging, monitoring, testing, and similar tasks using the power
45             and flexibility of perl. The module does not implement the functionality of
46             a RIB (Routing Information Base) nor does it modify the kernel routing table
47             of the host system. However, such operations could be implemented using the
48             API provided by the module.
49              
50             The module takes an object-oriented approach to abstracting the operations
51             of the BGP protocol. It supports multiple peering sessions and each peer
52             corresponds to one instance of a B object. The details of
53             maintaining each peering session are handled and coordinated by an instance
54             of a B object. BGP UPDATE messages and the routing
55             information they represent are encapsulated by B objects.
56             Whenever protocol errors occur and a BGP NOTIFICATION is sent or received,
57             programs can determine the details of the error via B
58             objects.
59              
60             The module interacts with client programs through the paradigm of callback
61             functions. Whenever interesting protocol events occur, a callback function
62             supplied by the user is called and information pertaining to the event is
63             passed to the function for examination or action. For instance, whenever an
64             UPDATE message is received from a peer, the module handles the details of
65             decoding the message, validating it, and encapsulating it in an object and
66             passing the object to the specific callback function supplied by the user
67             for UPDATE message handling. The callback function is free to do whatever
68             with the object - it might send a Net::BGP::Update object to other peers
69             as UPDATE messages, perhaps after modifying some of the UPDATE attributes,
70             log the routing information to a file, or do nothing at all. The
71             possibilities for implementing routing policy via such a mechanism are
72             limited only by the expressive capabilities of the perl language. It should
73             be noted however that the module is intended for the uses stated above and
74             probably would not scale well for very large BGP meshes or routing tables.
75              
76             The module must maintain periodic protocol keep-alive and other processes,
77             so once control is passed to the module's main event loop, control flow
78             only passes back to user code whenever one of the callback functions is
79             invoked. To provide more interaction with user programs, the module allows
80             user timers to be established and called periodically to perform further
81             processing. Multiple timers may be established, and each is associated with
82             a single peer. Whenever the timers expire, a user supplied function is called
83             and the timer is reset. The timer callback functions can perform whatever
84             actions are necessary - sending UPDATEs, modifying the state of the peering
85             session, house-keeping, etc.
86              
87             =head1 BUGS
88              
89             The connection collision resolution code is broken. As currently implemented,
90             whenever a connection is received from a peer, the B object
91             is cloned and each peer object proceeds through the session establishment
92             process until the collision resolution procedure is reached. At this point, if
93             the cloned object is chosen by the collison resolution procedure, the original
94             peer object is destroyed, leaving the cloned object. Unfortunately, a user
95             program will only have a reference to the original peer object it created and
96             will have no way of accessing the cloned object. It is therefore recommended
97             that B objects be instantiated with the B parameter
98             set to a false value. This prevents the peer object from receiving connections
99             from its BGP peer, although it will continue actively attempting to establish
100             sessions. This problem will be addressed in a future revision of B.
101              
102             As an initial revision, the code has not been subjected to a thorough security
103             audit. It is possible and likely that exploitable code exists in the packet
104             decoding routines. Therefore, it is recommended that the module only be used
105             to establish peering sessions with trusted peers, particularly if programs
106             using the module will be run with root priviliges (which is necessary if
107             programs want to modify the kernel routing table or bind to the well-known
108             BGP port 179).
109              
110             =head1 SEE ALSO
111              
112             RFC 1771, and the perldocs for Net::BGP::Process, Net::BGP::Peer, Net::BGP::Update,
113             and Net::BGP::Notification
114              
115             =head1 AUTHOR
116              
117             Stephen J. Scheck
118              
119             =cut
120              
121             ## End Package Net::BGP ##
122              
123             1;