Early review version

This code implements the Global Policy for Post Exhaustion
IPv4 Allocation by IANA. This version is designed for community
review prior to activation of the policy.

Author: kjd

.gitignore

@@ -0,0 +1,2 @@
+*.py[cod]
+.idea

readme.txt

@@ -0,0 +1,105 @@
+IPv4 Reclamation Algorithm (Beta)
+=================================
+
+OVERVIEW
+
+In May 2012, the ICANN Board ratified a global policy Global Policy for
+Post Exhaustion IPv4 Allocation by IANA.  This policy called for the
+establishment of a Recovered IPv4 Pool, which contains fragments leftover
+in the IANA and space that has been returned to the IANA by other means.
+The policy also called for IANA to make allocations from the Recovered
+IPv4 Pool once the pool is declared active.
+
+The pool will initially be declared active as soon as the first RIR has
+less than a /9 of IPv4 space in its inventory. The pool will also be
+declared active during “IPv4 allocation periods”, 6-month periods
+following 1 March or 1 September in each year.
+
+ICANN reported that we will use an open-source software program to 
+perform the address selection process. This code implements the IPv4 
+reclamation policy.
+
+This code is provisional and may be revised based on feedback from the
+community prior to its initial invocation by the Global Policy.
+
+REQUIREMENTS
+
+The Global Policy calls for the following:
+
+    When the Recovered IPv4 Pool is first activated and at the beginning
+    of each subsequent IPv4 allocation period, we will use software to
+    select 5 IPv4 allocation units (one for each RIR) from the current
+    IPv4 Recovered pool.
+
+    An IPv4 allocation unit is 1/5 of Recovered IPv4 pool, rounded down
+    to the next CIDR (power-of-2) boundary.
+
+    The minimum "IPv4 allocation unit" size will be a /24. If the
+    calculation used to determine the IPv4 allocation unit results in a
+    block smaller than a /24, the IANA will not distribute any addresses
+    in that IPv4 allocation period.
+
+The software should use the published ipv4-recovered-address-space
+registry XML file as input and output an updated XML file for check-in to
+the repository. Ideally, the software should try to allocate RIRs address
+space within /8s they already manage, based on the distribution in the
+ipv4-address-space registry.
+
+METHODOLOGY
+
+The algorithm determines the number of addresses that must be assigned
+to each RIR using the Global Policy. It determines the available ranges
+that can be re-allocated using the IANA recovered IPv4 address registry.
+It also determines a preference for each range using the current "WHOIS"
+records in the IPv4 address registry. The WHOIS record is a good indicator
+of which RIR is responsible for the covering /8 for a particular IP
+address.
+
+Based on these inputs, the algorithm iterates through each RIR and finds
+the best record to satisfy their need. Allocations are weighted toward
+(a) allocations that would be drawn from a range for which the
+RIR is responsible for the covering /8; (b) allocations that are larger;
+and (c) allocations that are the exact size of the needed space.
+
+HOW TO USE
+
+The algorithm is implemented as a command-line tool. Invoking the tool
+without arguments will fetch the most recent version of the two input
+registries from the IANA website. You can alternatively specify either a
+file-path or a URL as command line arguments to nominate alternate inputs.
+
+Using the "-o" or "--output" flags will save a revised version of the
+recovered IPv4 registry updated to reflect the new allocations. Note that
+allocations generated by this software will only take effect once the
+revised registries are published officially by ICANN.
+
+LICENSE
+
+Copyright (c) 2014, Internet Corporation for Assigned Names and
+Numbers. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+    * Neither the name of the ICANN nor the names of its contributors
+      may be used to endorse or promote products derived from this
+      software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY ICANN AND CONTRIBUTORS ``AS IS'' AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ICANN OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGE.