class Subnet::IPv6
- Subnet::IPv6
- Reference
- Object
Overview
Class Subnet::IPv6 is used to handle IPv6 type addresses.
IPv6 addresses
IPv6 addresses are 128 bits long, in contrast with IPv4 addresses which are only 32 bits long. An IPv6 address is generally written as eight groups of four hexadecimal digits, each group representing 16 bits or two octect. For example, the following is a valid IPv6 address:
2001:0db8:
Letters in an IPv6 address are usually written downcase, as per RFC. You can create a new IPv6 object using uppercase letters, but they will be converted.
Compression
Since IPv6 addresses are very long to write, there are some semplifications and compressions that you can use to shorten them.
- Leading zeroes: all the leading zeroes within a group can be omitted: "0008" would become "8"
- A string of consecutive zeroes can be replaced by the string "::". This can be only applied once.
Using compression, the IPv6 address written above can be shorten into the following, equivalent, address
2001:db8::8:800:200c:417a
This short version is often used in human representation.
Network Mask
As we used to do with IPv4 addresses, an IPv6 address can be written using the prefix notation to specify the subnet mask:
2001:db8::8:800:200c:417a/64
The /64 part means that the first 64 bits of the address are representing the network portion, and the last 64 bits are the host portion.
Included Modules
- Comparable(Subnet)
- Enumerable(Subnet::IPv6)
- Iterator(Subnet::IPv6)
- Subnet
Direct Known Subclasses
Defined in:
subnet/ipv6.crConstant Summary
-
IN6FORMAT =
("%04x:" * 8).chomp(':')
-
Format string to pretty print IPv6 addresses
Constructors
-
.new(str : String)
Creates a new IPv6 address object.
- .new(value : JSON::PullParser) : Subnet::IPv6
Class Method Summary
-
.compress(str)
Compress an IPv6 address in its compressed form
-
.expand(str)
Expands an IPv6 address in the canocical form
-
.groups(str)
Extract 16 bits groups from a string
-
.parse_data(data)
Creates a new IPv6 object from binary data, like the one you get from a network stream.
-
.parse_hex(hexstring, prefix = 128)
Creates a new IPv6 object from a number expressed in hexdecimal format:
-
.parse_u128(u128, prefix = 128)
Creates a new IPv6 object from an unsigned 128 bits integer.
Instance Method Summary
-
#<=>(oth)
Spaceship operator to compare IPv6 objects
-
#[](index)
Returns the 16-bits value specified by index
-
#[]=(index, value)
Updated the octet specified at index
-
#address : String
Returns the IPv6 address in uncompressed form:
-
#allocate(skip = 0)
Allocates a new ip from the current subnet.
-
#arpa
Returns the IPv6 address in a DNS reverse lookup string, as per RFC3172 and RFC2874.
-
#bits
Returns the address portion of an IP in binary format, as a string containing a sequence of 0 and 1
-
#broadcast_u128
Returns the broadcast address in Unsigned 128bits format
-
#compressed : String
Compressed form of the IPv6 address
-
#data
Returns the address portion of an IPv6 object in a network byte order format.
-
#each(&block)
Iterates over all the IP addresses for the given network (or IP address).
-
#group(index)
Returns the 16-bits value specified by index
-
#groups : Array(Int32)
Returns an array with the 16 bits groups in decimal format:
-
#hex_groups
Returns an array of the 16 bits groups in hexdecimal format:
-
#hexstring
Returns a Base16 number representing the IPv6 address
-
#includes?(oth)
Checks whether a subnet includes the given IP address.
-
#link_local?
Checks if an IPv6 address objects belongs to a link-local network RFC4291
-
#literal
Literal version of the IPv6 address
-
#loopback?
Returns true if the address is a loopback address
-
#mapped?
Returns true if the address is a mapped address
-
#network
Returns a new IPv6 object with the network number for the given IP.
-
#network?
True if the IPv6 address is a network
-
#network_u128
Returns the network number in Unsigned 128bits format
-
#next
Returns the next IP address in the network, or
Iterator::Stop::INSTANCE
when out of addresses. -
#pred
Returns the predecessor to the IP address
-
#prefix : Prefix128
Returns an instance of the prefix object
-
#prefix=(num)
Set a new prefix number for the object
-
#reverse
Returns the IPv6 address in a DNS reverse lookup string, as per RFC3172 and RFC2874.
-
#size
Returns the number of IP addresses included in the network.
-
#succ
Returns the successor to the IP address
-
#to_big_i
Return the address as a
BigInt
-
#to_i
Returns a the address in as a
BigInt
(will return aUInt128
once support for that is finished in the stdlib) - #to_json(json : JSON::Builder)
-
#to_s : String
Returns the IPv6 address in a human readable form, using the compressed address.
-
#to_string
Returns the IPv6 address in a human readable form, using the compressed address.
-
#to_string_uncompressed
Unlike its counterpart IPv6#to_string method, IPv6#to_string_uncompressed returns the whole IPv6 address and prefix in an uncompressed form
-
#to_u128
Returns a the address in as a
BigInt
(will return aUInt128
once support for that is finished in the stdlib) -
#unique_local?
Checks if an IPv6 address objects belongs to a unique-local network RFC4193
-
#unspecified?
Returns true if the address is an unspecified address
Instance methods inherited from module Subnet
ipv4?
ipv4?,
ipv6?
ipv6?,
to_json(json : JSON::Builder)
to_json
Constructor methods inherited from module Subnet
new(value : JSON::PullParser) : Subnet
new,
parse(str) : Subnet
parse
Class methods inherited from module Subnet
deprecate(message = nil)
deprecate,
ntoa(uint)
ntoa,
valid?(addr)
valid?,
valid_ip?(addr)
valid_ip?,
valid_ipv4?(addr)
valid_ipv4?,
valid_ipv4_netmask?(addr)
valid_ipv4_netmask?,
valid_ipv4_subnet?(addr)
valid_ipv4_subnet?,
valid_ipv6?(addr)
valid_ipv6?,
valid_ipv6_subnet?(addr)
valid_ipv6_subnet?
Constructor Detail
Creates a new IPv6 address object.
An IPv6 address can be expressed in any of the following forms:
- "2001:0db8:0000:0000:0008:0800:200C:417A": IPv6 address with no compression
- "2001:db8:0:0:8:800:200C:417A": IPv6 address with leading zeros compression
- "2001:db8::8:800:200C:417A": IPv6 address with full compression
In all these 3 cases, a new IPv6 address object will be created, using the default subnet mask /128
You can also specify the subnet mask as with IPv4 addresses:
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
Class Method Detail
Compress an IPv6 address in its compressed form
Subnet::IPv6.compress "2001:0DB8:0000:CD30:0000:0000:0000:0000"
# => "2001:db8:0:cd30::"
Expands an IPv6 address in the canocical form
Subnet::IPv6.expand "2001:0DB8:0:CD30::"
# => "2001:0DB8:0000:CD30:0000:0000:0000:0000"
Creates a new IPv6 object from binary data, like the one you get from a network stream.
For example, on a network stream the IP
"2001:db8::8:800:200c:417a"
is represented with the binary data
" \001\r\270\000\000\000\000\000\b\b\000 \fAz"
With that data you can create a new IPv6 object:
ip6 = Subnet::IPv6::parse_data " \001\r\270\000\000\000\000\000\b\b\000 \fAz"
ip6.prefix = 64
ip6.to_s
# => "2001:db8::8:800:200c:417a/64"
Creates a new IPv6 object from a number expressed in hexdecimal format:
ip6 = Subnet::IPv6::parse_hex("20010db80000000000080800200c417a")
ip6.prefix = 64
ip6.to_string
# => "2001:db8::8:800:200c:417a/64"
The #prefix
parameter is optional:
ip6 = Subnet::IPv6::parse_hex("20010db80000000000080800200c417a", 64)
ip6.to_string
# => "2001:db8::8:800:200c:417a/64"
Creates a new IPv6 object from an unsigned 128 bits integer.
ip6 = Subnet::IPv6::parse_u128(
The #prefix
parameter is optional:
ip6 = Subnet::IPv6::parse_u128(
Instance Method Detail
Spaceship operator to compare IPv6 objects
Comparing IPv6 addresses is useful to ordinate them into lists that match our intuitive perception of ordered IP addresses.
The first comparison criteria is the u128 value. For example, 2001:db8:1::1 will be considered to be less than 2001:db8:2::1, because, in a ordered list, we expect 2001:db8:1::1 to come before 2001:db8:2::1.
The second criteria, in case two IPv6 objects have identical addresses, is the prefix. An higher prefix will be considered greater than a lower prefix. This is because we expect to see 2001:db8:1::1/64 come before 2001:db8:1::1/65
Example:
ip1 = Subnet.parse "2001:db8:1::1/64"
ip2 = Subnet.parse "2001:db8:2::1/64"
ip3 = Subnet.parse "2001:db8:1::1/65"
ip1 < ip2
# => true
ip1 < ip3
# => false
[ip1, ip2, ip3].sort.map { |i| i.to_string }
# => ["2001:db8:1::1/64","2001:db8:1::1/65","2001:db8:2::1/64"]
Returns the 16-bits value specified by index
ip = Subnet::IPv6.new("2001:db8::8:800:200c:417a/64")
ip[0]
# => 8193
ip[1]
# => 3512
ip[2]
# => 0
ip[3]
# => 0
Returns the IPv6 address in uncompressed form:
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.address
# => "2001:0db8:0000:0000:0008:0800:200c:417a"
Allocates a new ip from the current subnet. Optional skip parameter can be used to skip addresses.
Will raise StopIteration exception when all addresses have been allocated
Example:
ip = Subnet::IPv6.new("10.0.0.0/24")
ip.allocate
# => "10.0.0.1/24"
ip.allocate
# => "10.0.0.2/24"
ip.allocate(2)
# => "10.0.0.5/24"
Uses an internal @allocator which tracks the state of allocated addresses.
Returns the IPv6 address in a DNS reverse lookup string, as per RFC3172 and RFC2874.
ip6 = Subnet.parse "3ffe:505:2::f"
ip6.reverse
# => "f.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.0.0.0.5.0.5.0.e.f.f.3.ip6.arpa"
Returns the address portion of an IP in binary format, as a string containing a sequence of 0 and 1
ip6 = Subnet::IPv6.new("2001:db8::8:800:200c:417a")
ip6.bits
# => "0010000000000001000011011011100000 [...] "
Returns the broadcast address in Unsigned 128bits format
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.broadcast_u128
# => 42540766411282592875350729025363378175
Please note that there is no Broadcast concept in IPv6 addresses as in IPv4 addresses, and this method is just an helper to other functions.
Compressed form of the IPv6 address
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.compressed
# => "2001:db8::8:800:200c:417a"
Returns the address portion of an IPv6 object in a network byte order format.
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.data
# => " \001\r\270\000\000\000\000\000\b\b\000 \fAz"
It is usually used to include an IP address in a data packet to be sent over a socket
Iterates over all the IP addresses for the given network (or IP address).
The object yielded is a new IPv6 object created from the iteration.
ip6 = Subnet::IPv6.new("2001:db8::4/125")
ip6.each do |i|
p i.compressed
end
# => "2001:db8::"
# => "2001:db8::1"
# => "2001:db8::2"
# => "2001:db8::3"
# => "2001:db8::4"
# => "2001:db8::5"
# => "2001:db8::6"
# => "2001:db8::7"
WARNING: if the host portion is very large, this method can be very slow and possibly hang your system!
Returns the 16-bits value specified by index
ip = Subnet::IPv6.new("2001:db8::8:800:200c:417a/64")
ip[0]
# => 8193
ip[1]
# => 3512
ip[2]
# => 0
ip[3]
# => 0
Returns an array with the 16 bits groups in decimal format:
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.groups
# => [8193, 3512, 0, 0, 8, 2048, 8204, 16762]
Returns an array of the 16 bits groups in hexdecimal format:
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.hex_groups
# => ["2001", "0db8", "0000", "0000", "0008", "0800", "200c", "417a"]
Not to be confused with the similar IPv6#hexstring
method.
Returns a Base16 number representing the IPv6 address
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.hexstring
# => "20010db80000000000080800200c417a"
Checks whether a subnet includes the given IP address.
Example:
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
addr = Subnet.parse "2001:db8::8:800:200c:1/128"
ip6.includes? addr
# => true
ip6.includes? Subnet::IPv6.new("2001:db8:1::8:800:200c:417a/76")
# => false
Checks if an IPv6 address objects belongs to a link-local network RFC4291
Example:
ip = Subnet.parse "fe80::1"
ip.link_local?
# => true
Literal version of the IPv6 address
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.literal
# => "2001-0db8-0000-0000-0008-0800-200c-417a.ipv6-literal.net"
```
Returns true if the address is a loopback address
See Subnet::IPv6::Loopback for more information
Returns true if the address is a mapped address
See Subnet::IPv6::Mapped for more information
Returns a new IPv6 object with the network number for the given IP.
ip = Subnet.parse "2001:db8:1:1:1:1:1:1/32"
ip.network.to_string
# => "2001:db8::/32"
True if the IPv6 address is a network
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.network?
# => false
ip6 = Subnet.parse "2001:db8:8:800::/64"
ip6.network?
# => true
Returns the network number in Unsigned 128bits format
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.network_u128
# => 42540766411282592856903984951653826560
Returns the next IP address in the network, or
Iterator::Stop::INSTANCE
when out of
addresses.
Returns the predecessor to the IP address
Example:
ip = Subnet.parse("192.168.45.23/16")
ip.pred.to_string
=> "192.168.45.22/16"
Returns an instance of the prefix object
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.prefix
# => 64
Set a new prefix number for the object
This is useful if you want to change the prefix to an object created with IPv6::parse_u128 or if the object was created using the default prefix of 128 bits.
ip6 = Subnet::IPv6.new("2001:db8::8:800:200c:417a")
puts ip6.to_string
# => "2001:db8::8:800:200c:417a/128"
ip6.prefix = 64
puts ip6.to_string
# => "2001:db8::8:800:200c:417a/64"
Returns the IPv6 address in a DNS reverse lookup string, as per RFC3172 and RFC2874.
ip6 = Subnet.parse "3ffe:505:2::f"
ip6.reverse
# => "f.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.0.0.0.5.0.5.0.e.f.f.3.ip6.arpa"
Returns the number of IP addresses included in the network. It also counts the network address and the broadcast address.
ip6 = Subnet::IPv6.new("2001:db8::8:800:200c:417a/64")
ip6.size
# => 18446744073709551616
Returns the successor to the IP address
Example:
ip = Subnet.parse("192.168.45.23/16")
ip.succ.to_string
=> "192.168.45.24/16"
Returns a the address in as a BigInt
(will return a
UInt128
once support for that is finished in
the stdlib)
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.to_i
# => 42540766411282592856906245548098208122
Returns the IPv6 address in a human readable form, using the compressed address.
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.to_s
# => "2001:db8::8:800:200c:417a"
Returns the IPv6 address in a human readable form, using the compressed address.
ip6 = Subnet.parse "2001:0db8:0000:0000:0008:0800:200c:417a/64"
ip6.to_string
# => "2001:db8::8:800:200c:417a/64"
Unlike its counterpart IPv6#to_string method, IPv6#to_string_uncompressed returns the whole IPv6 address and prefix in an uncompressed form
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.to_string_uncompressed
# => "2001:0db8:0000:0000:0008:0800:200c:417a/64"
Returns a the address in as a BigInt
(will return a
UInt128
once support for that is finished in
the stdlib)
ip6 = Subnet.parse "2001:db8::8:800:200c:417a/64"
ip6.to_i
# => 42540766411282592856906245548098208122
Checks if an IPv6 address objects belongs to a unique-local network RFC4193
Example:
ip = Subnet.parse "fc00::1"
ip.unique_local?
# => true
Returns true if the address is an unspecified address
See Subnet::IPv6::Unspecified for more information