Method: NetAddr::CIDR#subnet

Defined in:

lib/cidr.rb

#subnet(options = nil) ⇒ Object

Synopsis

Create subnets for this CIDR. There are 2 ways to create subnets:

* By providing the netmask (in bits) of the new subnets with :Bits.
* By providing the number of IP addresses needed in the new subnets with :IPCount

:NumSubnets is used to determine how the CIDR is subnetted. For example, if I request the following operation:

NetAddr::CIDR.create(‘192.168.1.0/24’).subnet(:Bits => 26, :NumSubnets => 1)

then I would get back the first /26 subnet of 192.168.1.0/24 and the remainder of the IP space as summary CIDR addresses (e.g. 192.168.1.0/26, 192.168.1.64/26, and 192.168.1.128/25). If I were to perform the same operation without the :NumSubnets directive, then 192.168.1.0/24 will be fully subnetted into X number of /26 subnets (e.g. 192.168.1.0/26, 192.168.1.64/26, 192.168.1.128/26, and 192.168.1.192/26).

If neither :Bits nor :IPCount is provided, then the current CIDR will be split in half. If both :Bits and :IPCount are provided, then :Bits takes precedence.

Example: cidr4 = NetAddr::CIDR.create(‘192.168.1.0/24’) cidr6 = NetAddr::CIDR.create(‘fec0::/64’) cidr4.subnet(:Bits => 28, :NumSubnets => 3) cidr4.subnet(:IPCount => 19) cidr4.subnet(:Bits => 28) cidr6.subnet(:Bits => 67, :NumSubnets => 4, :Short => true)

Arguments:

• options = Hash with the following keys:

  :Bits --  Netmask (in bits) of new subnets - Integer
  :IPCount -- Minimum number of IP's that new subnets should contain - Integer
  :NumSubnets -- Number of X sized subnets to return - Integer
  :Objectify -- if true, return NetAddr::CIDR objects
  :Short -- if true, return IPv6 addresses in short-hand notation
  

Returns:

• Array of Strings, or Array of NetAddr::CIDR objects

# File 'lib/cidr.rb', line 1780

def subnet(options=nil)
    known_args = [:Bits, :IPCount, :NumSubnets, :Objectify, :Short]
    my_network = self.to_i(:network)
    my_mask = self.bits
    subnet_bits = my_mask + 1
    min_count = nil 
    objectify = false
    short = false

    if (options)
        if (!options.kind_of? Hash)
            raise ArgumentError, "Expected Hash, but #{options.class} provided."
        end
        NetAddr.validate_args(options.keys,known_args)

        if ( options.has_key?(:IPCount) )
            subnet_bits = NetAddr.ip_count_to_size(options[:IPCount], @version)
        end

        if ( options.has_key?(:Bits) )
            subnet_bits = options[:Bits]
        end

        if ( options.has_key?(:NumSubnets) )
            num_subnets = options[:NumSubnets]
        end

        if( options.has_key?(:Short) && options[:Short] == true )
            short = true
        end

        if( options.has_key?(:Objectify) && options[:Objectify] == true )
            objectify = true
        end

    end

    # get number of subnets possible with the requested subnet_bits
    num_avail = 2**(subnet_bits - my_mask)

    # get the number of bits in the next supernet and
    # make sure num_subnets is a power of 2
    bits_needed = 1
    num_subnets = num_avail if (!num_subnets)
    until (2**bits_needed >= num_subnets)
        bits_needed += 1
    end
    num_subnets = 2**bits_needed
    next_supernet_bits = subnet_bits - bits_needed


    # make sure subnet isnt bigger than available bits
    if (subnet_bits > @address_len)
        raise BoundaryError, "Requested subnet (#{subnet_bits}) does not fit " +
              "within the bounds of IPv#{@version}."
    end

    # make sure subnet is larger than mymask
    if (subnet_bits < my_mask)
        raise BoundaryError, "Requested subnet (#{subnet_bits}) is too large for " +
              "current CIDR space."
    end

    # make sure MinCount is smaller than available subnets
    if (num_subnets > num_avail)
        raise "Requested subnet count (#{num_subnets}) exceeds subnets " +
              "available for allocation (#{num_avail})."
    end

    # list all 'subnet_bits' sized subnets of this cidr block
    # with a limit of num_subnets
    bitstep = 2**(@address_len - subnet_bits)
    subnets = self.enumerate(:Bitstep => bitstep, :Limit => num_subnets, :Objectify => true)

    # save our subnets
    new_subnets = []
    subnets.each do |subnet|
        if (!objectify)
            if (short && @version == 6)
                new_subnets.push("#{subnet.network(:Short => true)}/#{subnet_bits}")
            else
                new_subnets.push("#{subnet.network}/#{subnet_bits}")
            end
        else
            new_subnets.push( NetAddr.cidr_build(@version, subnet.to_i(:network), NetAddr.bits_to_mask(subnet_bits,version) ) )
        end
    end

    # now go through the rest of the cidr space and make the rest
    # of the subnets. we want these to be as tightly merged as possible
    next_supernet_bitstep = (bitstep * num_subnets)
    next_supernet_ip = my_network + next_supernet_bitstep
    until (next_supernet_bits == my_mask)
        if (!objectify)
            next_network = NetAddr.ip_int_to_str(next_supernet_ip, @version)
            next_network = NetAddr.shorten(next_network) if (short && @version == 6)
            new_subnets.push("#{next_network}/#{next_supernet_bits}")
        else
            new_subnets.push(NetAddr.cidr_build(@version, next_supernet_ip, NetAddr.bits_to_mask(next_supernet_bits,version) ) )
        end

        next_supernet_bits -= 1
        next_supernet_ip = next_supernet_ip + next_supernet_bitstep
        next_supernet_bitstep = next_supernet_bitstep << 1
    end

    return(new_subnets)
end