======================
Welcome to IPAllocator
======================
:Author: Garry Dolley
:Date: 01-14-2009
:Version: v0.1
A class that helps ISP's subnet their IPv4 and IPv6 address space.
Example uses include:
* Allocating IPs to customers
* Allocating subnets to downstream networks
* Allocating subnets for internal use
Default allocation strategy uses the "centermost" scheme of RFC 3531.
RFC 3531 is a generalization of RFC 1219 ("On the Assignment of Subnet
Numbers"). Its first intended use is for IPv6, but can be used for any
bit length addressing scheme (e.g. IPv4).
When allocating IPs, we want to balance two goals:
* Minimize fragmentation of blocks
- For example, if you have a /19, and you allocate several /24's and /25's,
you still want a /23 and /22 to be available if needed.
You don't want the /24's and /25's to be allocated in such a way that
they are subnets of all the available /22's, thus making no further /22's
available for reassignment.
* Allow existing allocations to "grow" into larger allocations by simply
changing the subnet mask, instead of allocating a second, non-contiguous
block.
- This lessens the number of distinct routes seen by routing protocols,
which places less burden on routers and saves FIB space.
Of these, minimizing fragmentation of blocks is given higher priority.
The latest code is available on GitHub:
* git://github.com/up_the_irons/ip_allocator.git
Status
------
A very young class. Current specs pass, but more are needed, especially for
edge cases and IPv6. Correctness testing is incomplete. Performance has not
been touched.
Makes use of NetAddr module and is not optimized for speed.
Requirements
------------
* RubyGems
* NetAddr
Installation
------------
Install NetAddr gem from RubyForge::
gem install -r netaddr
Put this code somewhere and require it in your code::
require 'rubygems'
require 'ip_allocator'
Example
-------
::
require 'rubygems'
require 'ip_allocator'
@supernet = NetAddr::CIDR.create('208.79.88.0/21')
@allocated = [NetAddr::CIDR.create('208.79.89.0/25'),
NetAddr::CIDR.create('208.79.91.0/24')]
@allocator = IPAllocator.new(@supernet, @allocated)
# Give me a /24
@allocator.first_unused(24).to_s => '208.79.88.0/24'
TODO
----
* Specs
- Correctness
- IPv6
* Some performance testing
Author
------
Garry C. Dolley
gdolley [at] NOSPAM- ucla.edu
AIM: garry97531
IRC: up_the_irons in #pledgie, #git, #caboose on Freenode (and usually many
other channels)
Formatting
----------
This README is formatted in reStructredText [RST]_. It has the best
correlation between what a document looks like as plain text vs. its
formatted output (HTML, LaTeX, etc...). What I like best is, markup doesn't
look like markup, even though it is.
.. [RST] http://docutils.sourceforge.net/rst.html
RDoc sucks.
Copyright
---------
Copyright (c) 2009 Garry C. Dolley
IPAllocator is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
IPAllocator is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
IPAllocator; if not, write to the Free Software Foundation, Inc., 51 Franklin
Street, Fifth Floor, Boston, MA 02110-1301, USA
) is private.
