| Class | NetAddr::CIDR |
| In: |
lib/cidr.rb
|
| Parent: | Object |
A class & series of methods for creating and manipulating CIDR network addresses. Both IPv4 and IPv6 are supported.
This class accepts a CIDR address, via the CIDR.create method, in (x.x.x.x/yy or xxxx::/yy) format for IPv4 and IPv6, or (x.x.x.x/y.y.y.y) for IPv4. CIDR.create then creates either a CIDRv4 or CIDRv6 object. An optional tag hash may be provided with each CIDR as a way of adding custom labels.
Upon initialization, the IP version is auto-detected and assigned to the CIDR. The original IP/Netmask passed within the CIDR is stored and then used to determine the confines of the CIDR block. Various properties of the CIDR block are accessible via several different methods. There are also methods for modifying the CIDR or creating new derivative CIDR‘s.
An example CIDR object is as follows:
NetAddr::CIDR.create('192.168.1.20/24')
This would create a CIDR object (192.168.1.0/24) with the following properties:
version = 4
base network = 192.168.1.0
ip address = 192.168.1.20
netmask = /24 (255.255.255.0)
size = 256 IP addresses
broadcast = 192.168.1.255
You can see how the CIDR object is based around the entire IP space defined by the provided IP/Netmask pair, and not necessarily the individual IP address itself.
Create a new CIDRv4 or CIDRv6 object. CIDR formatted netmasks take precedence over extended formatted ones. CIDR address defaults to a host network (/32 or /128) if netmask not provided. :Mask takes precedence over netmask given within CIDR addresses. Version will be auto-detected if not specified.
NetAddr::CIDR.create('192.168.1.1/24')
NetAddr::CIDR.create('192.168.1.1 255.255.255.0')
NetAddr::CIDR.create(0x0a010001,
:Mask => 0xffffff00
:Version => 4)
NetAddr::CIDR.create('192.168.1.1',
:WildcardMask => ['0.7.0.255', true])
NetAddr::CIDR.create('192.168.1.1',
:WildcardMask => [0x000007ff, true]
NetAddr::CIDR.create('192.168.5.0',
:WildcardMask => ['255.248.255.0'])
NetAddr::CIDR.create('fec0::/64')
NetAddr::CIDR.create('fec0::/64',
:Tag => {'interface' => 'g0/1'})
NetAddr::CIDR.create('::ffff:192.168.1.1/96')
:Mask -- Integer representing a binary IP Netmask
:Version -- IP version - Integer
:Tag -- Custom descriptor tag - Hash, tag => value.
:WildcardMask -- 2 element Array. First element contains a special bit mask used for
advanced IP pattern matching. The second element should be set to True if this
bit mask is bit flipped.
This method performs absolutely no error checking, and is meant to be used only by other internal methods for the sake of the speedier creation of CIDR objects. Please consider using #create unless you know what you are doing with 100% certainty.
Compare the sort order of the current CIDR with a provided CIDR and return:
Example:
cidr = NetAddr::CIDR.create('192.168.1.0/24')
cidr <=> '192.168.2.0/24' => -1
cidr <=> '192.168.0.0/24' => 1
cidr <=> '192.168.1.0/24' => 0
Provide the IP at the given index of the CIDR.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
cidr4[1] => 192.168.1.1/32
RFC 3531 describes a flexible method for IP subnet allocation from a larger parent network. Given the new netmask for subnet allocations from this CIDR, provide a list of those subnets arranged by the order in which they should be allocated.
Example:
cidr = NetAddr::CIDR.create('192.168.0.0/16')
cidr.allocate_rfc3531(21, :Strategy => :centermost) => ["192.168.0.0/21"... "192.168.248.0/21"]
:Objectify -- if true, return NetAddr::CIDR objects :Short -- if true, return IPv6 addresses in short-hand notation :Strategy -- allocation strategy to use. must be either :centermost or :leftmost (default)
Depending on the IP version of the current CIDR, return either an in-addr.arpa. or ip6.arpa. string. The netmask will be used to determine the length of the returned string.
Example:
cidr = NetAddr::CIDR.create('192.168.1.1/24')
cidr.arpa => "1.168.192.in-addr.arpa."
Provide number of bits in Netmask.
Example:
cidr = NetAddr::CIDR.create('192.168.1.1/24')
cidr.bits => 24
Compare the current CIDR with a provided CIDR and return:
Example:
cidr = NetAddr::CIDR.create('192.168.1.0/24')
cidr.cmp('192.168.1.0/25') => 1
cidr.cmp('192.168.1.0/24') => 0
cidr.cmp('192.168.0.0/23') => -1
cidr.cmp('10.0.0.0/24') => nil
Determines if this CIDR contains (is supernet of) the provided CIDR address or NetAddr::CIDR object.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
cidr6 = NetAddr::CIDR.create('fec0::/64')
cidr6_2 = NetAddr::CIDR.create('fec0::/96')
cidr4.contains?('192.168.1.2') => true
cidr6.contains?(cidr6_2) => true
Provide all IP addresses contained within the IP space of this CIDR.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
cidr6 = NetAddr::CIDR.create('fec0::/64')
cidr4.enumerate(:Limit => 4, :Bitstep => 32)
cidr6.enumerate(:Limit => 4, :Bitstep => 32, :Objectify => true)
:Bitstep -- enumerate in X sized steps - Integer :Limit -- limit returned list to X number of items - Integer :Objectify -- if true, return NetAddr::CIDR objects :Short -- if true, return IPv6 addresses in short-hand notation
Given a list of subnets of the current CIDR, return a new list with any holes (missing subnets) filled in.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
cidr4.fill_in(['192.168.1.0/27','192.168.1.64/26','192.168.1.128/25'])
:Objectify -- if true, return NetAddr::CIDR objects :Short -- if true, return IPv6 addresses in short-hand notation
Provide original IP address passed during initialization.
Example:
cidr = NetAddr::CIDR.create('192.168.1.1/24')
cidr.ip => "192.168.1.1"
:Objectify -- if true, return NetAddr::CIDR object :Short -- if true, return IPv6 addresses in short-hand notation
Determines if this CIDR is contained within (is subnet of) the provided CIDR address or NetAddr::CIDR object.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
cidr4.is_contained?('192.168.0.0/23')
Provide last IP address in this CIDR object.
Example:
cidr = NetAddr::CIDR.create('192.168.1.0/24')
cidr.last => "192.168.1.255"
:Objectify -- if true, return NetAddr::CIDR object :Short -- if true, return IPv6 addresses in short-hand notation
Given an IP address (or if a NetAddr::CIDR object, then the original IP of that object), determine if it falls within the range of addresses resulting from the combination of the IP and Wildcard Mask of this CIDR.
Example:
cidr4 = NetAddr.CIDRv4.create('10.0.0.0', :WildcardMask => ['0.7.0.255', true])
cidr4.matches?('10.0.0.22') -> true
cidr4.matches?('10.8.0.1') -> false
cidr4.matches?('10.1.0.1') -> true
cidr4.matches?('10.0.1.22') -> false
Assuming this CIDR is a valid multicast address (224.0.0.0/4 for IPv4 and ff00::/8 for IPv6), return its ethernet MAC address (EUI-48) mapping. MAC address is based on original IP address passed during initialization.
Example:
mcast = NetAddr::CIDR.create('224.0.0.6')
mcast.multicast_mac.address
:Objectify -- if true, return EUI objects
Example:
cidr = NetAddr::CIDR.create('192.168.1.0/24')
cidr.network => "192.168.1.0"
:Objectify -- if true, return NetAddr::CIDR object :Short -- if true, return IPv6 addresses in short-hand notation
Provide the next IP following the last available IP within this CIDR object.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
cidr6 = NetAddr::CIDR.create('fec0::/64')
cidr4.next_subnet()
cidr6.next_subnet(:Short => true)}
:Bitstep -- step in X sized steps - Integer :Objectify -- if true, return NetAddr::CIDR object :Short -- if true, return IPv6 addresses in short-hand notation
Provide the next subnet following this CIDR object. The next subnet will be of the same size as the current CIDR object.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
cidr6 = NetAddr::CIDR.create('fec0::/64')
cidr4.next_subnet()
cidr6.next_subnet(:Short => true)
:Bitstep -- step in X sized steps. - Integer :Objectify -- if true, return NetAddr::CIDR object :Short -- if true, return IPv6 addresses in short-hand notation
Provide the nth IP within this object.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
cidr4.nth(1)
cidr4.nth(1, :Objectify => true)
:Objectify -- if true, return NetAddr::CIDR objects :Short -- if true, return IPv6 addresses in short-hand notation
Given a set of index numbers for this CIDR, return all IP addresses within the CIDR that are between them (inclusive). If an upper bound is not provided, then all addresses from the lower bound up will be returned.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
cidr4.range(0, 1)
cidr4.range(0, 1, :Objectify => true)
cidr4.range(0, nil, :Objectify => true)
:Bitstep -- enumerate in X sized steps - Integer :Objectify -- if true, return NetAddr::CIDR objects :Short -- if true, return IPv6 addresses in short-hand notation
If you do not need all of the fancy options in this method, then please consider using the standard Ruby Range class as shown below.
Example:
start = NetAddr::CIDR.create('192.168.1.0')
fin = NetAddr::CIDR.create('192.168.2.3')
(start..fin).each {|addr| puts addr.desc}
Given a single subnet of the current CIDR, provide the remainder of the subnets. For example if the original CIDR is 192.168.0.0/24 and you provide 192.168.0.64/26 as the portion to exclude, then 192.168.0.0/26, and 192.168.0.128/25 will be returned as the remainders.
cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
cidr4.remainder('192.168.1.32/27')
cidr4.remainder('192.168.1.32/27', :Objectify => true)
:Objectify -- if true, return NetAddr::CIDR objects :Short -- if true, return IPv6 addresses in short-hand notation
Resize the current CIDR by changing the size of the Netmask. The original IP passed during initialization will be set to the base network address if it no longer falls within the bounds of the CIDR.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
cidr4.resize!(23)
Set the wildcard mask. Wildcard masks are typically used for matching entries in an access-list.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
cidr4.set_wildcard_mask('0.0.0.255', true)
cidr4.set_wildcard_mask('255.255.255.0')
Provide number of IP addresses within this CIDR.
Example:
cidr = NetAddr::CIDR.create('192.168.1.0/24')
cidr.size => 256
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)
: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
Hash of custom tags. Should be in the format tag => value.
Example:
cidr4.tag[:name] = 'IPv4 CIDR' puts cidr4.tag[:name]
Convert the requested attribute of the CIDR to an Integer.
Example:
cidr = NetAddr::CIDR.create('192.168.1.1/24')
cidr.to_i => 3232235776
cidr.to_i(:hostmask) => 255
cidr.to_i(:ip) => 3232235777
cidr.to_i(:netmask) => 4294967040
cidr.to_i(:wildcard_mask) => 4294967040
Returns network/netmask in CIDR format.
Example:
cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
cidr6 = NetAddr::CIDR.create('fec0::/64')
cidr4.desc(:IP => true) => "192.168.1.1/24"
cidr4.to_s => "192.168.1.0/24"
cidr6.to_s(:Short => true) => "fec0::/64"
:IP -- if true, return the original ip/netmask passed during initialization :Short -- if true, return IPv6 addresses in short-hand notation
Return the wildcard mask.
Example:
cidr = NetAddr::CIDR.create('10.1.0.0/24', :WildcardMask => ['0.7.0.255', true])
cidr.wildcard_mask => "255.248.255.0"
cidr.wildcard_mask(true) => "0.7.0.255"