Class: IPAddress::IPv6

Inherits:
Object
  • Object
show all
Includes:
Comparable, Enumerable, IPAddress
Defined in:
lib/ipaddress/ipv6.rb

Overview

Name

IPAddress::IPv6 - IP version 6 address manipulation library

Synopsis

require 'ipaddress'

Description

Class IPAddress::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:

1080:0000:0000:0000:0008:0800:200c:417a

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

1080::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:

1080::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.

Direct Known Subclasses

Loopback, Mapped, Unspecified

Defined Under Namespace

Classes: Loopback, Mapped, Unspecified

Constant Summary collapse

IN6FORMAT =

Format string to pretty print IPv6 addresses

("%.4x:"*8).chop

Constants included from IPAddress

AUTHORS, GEM, NAME

Class Method Summary collapse

Instance Method Summary collapse

Methods included from IPAddress

deprecate, parse, valid?, valid_ipv4?, valid_ipv4_netmask?, valid_ipv6?

Constructor Details

#initialize(str) ⇒ IPv6

Creates a new IPv6 address object.

An IPv6 address can be expressed in any of the following forms:

  • “1080:0000:0000:0000:0008:0800:200C:417A”: IPv6 address with no compression

  • “1080:0:0:0:8:800:200C:417A”: IPv6 address with leading zeros compression

  • “1080::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 = IPAddress "2001:db8::8:800:200c:417a/64"



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/ipaddress/ipv6.rb', line 89

def initialize(str)
  ip, netmask = str.split("/")

  if str =~ /:.+\./
    raise ArgumentError, "Please use #{self.class}::Mapped for IPv4 mapped addresses"
  end
  
  if IPAddress.valid_ipv6?(ip)
    @groups = self.class.groups(ip)
    @address = IN6FORMAT % @groups
    @compressed = compress_address
  else
    raise ArgumentError, "Invalid IP #{ip.inspect}"
  end

  @prefix = Prefix128.new(netmask ? netmask : 128)

end

Class Method Details

.compress(str) ⇒ Object

Compress an IPv6 address in its compressed form

IPAddress::IPv6.compress "2001:0DB8:0000:CD30:0000:0000:0000:0000"
  #=> "2001:db8:0:cd30::"



417
418
419
 
# File 'lib/ipaddress/ipv6.rb', line 417

def self.compress(str)
  self.new(str).compressed
end

.expand(str) ⇒ Object

Expands an IPv6 address in the canocical form

IPAddress::IPv6.expand "2001:0DB8:0:CD30::"
  #=> "2001:0DB8:0000:CD30:0000:0000:0000:0000"



407
408
409
 
# File 'lib/ipaddress/ipv6.rb', line 407

def self.expand(str)
  self.new(str).address
end

.groups(str) ⇒ Object

Extract 16 bits groups from a string



436
437
438
439
440
441
442
443
 
# File 'lib/ipaddress/ipv6.rb', line 436

def self.groups(str)
  l, r = if str =~ /^(.*)::(.*)$/
           [$1,$2].map {|i| i.split ":"}
         else
           [str.split(":"),[]]
         end
  (l + Array.new(8-l.size-r.size, '0') + r).map {|i| i.hex}
end

.parse_data(str) ⇒ Object

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 = IPAddress::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"



465
466
467
 
# File 'lib/ipaddress/ipv6.rb', line 465

def self.parse_data(str)
  self.new(IN6FORMAT % str.unpack("n8"))
end

.parse_hex(hex, prefix = 128) ⇒ Object

Creates a new IPv6 object from a number expressed in hexdecimal format:

ip6 = IPAddress::IPv6::parse_hex("20010db80000000000080800200c417a")
ip6.prefix = 64

ip6.to_s
  #=> "2001:db8::8:800:200c:417a/64"

The prefix parameter is optional:

ip6 = IPAddress::IPv6::parse_hex("20010db80000000000080800200c417a", 64)

ip6.to_s
  #=> "1080::8:800:200c:417a/64"



508
509
510
 
# File 'lib/ipaddress/ipv6.rb', line 508

def self.parse_hex(hex, prefix=128)
  self.parse_u128(hex.hex, prefix)
end

.parse_u128(u128, prefix = 128) ⇒ Object

Creates a new IPv6 object from an unsigned 128 bits integer.

ip6 = IPAddress::IPv6::parse_u128(21932261930451111902915077091070067066)
ip6.prefix = 64

ip6.to_s
  #=> "1080::8:800:200c:417a/64"

The prefix parameter is optional:

ip6 = IPAddress::IPv6::parse_u128(21932261930451111902915077091070067066, 64)

ip6.to_s
  #=> "1080::8:800:200c:417a/64"



486
487
488
489
 
# File 'lib/ipaddress/ipv6.rb', line 486

def self.parse_u128(u128, prefix=128)
  str = IN6FORMAT % (0..7).map{|i| (u128>>(112-16*i))&0xffff}
  self.new(str + "/#{prefix}")
end

Instance Method Details

#[](index) ⇒ Object Also known as: group

Returns the 16-bits value specified by index

ip = IPAddress("2001:db8::8:800:200c:417a/64")

ip[0]
  #=> 8193
ip[1]
  #=> 3512
ip[2]
  #=> 0
ip[3]
  #=> 0



250
251
252
 
# File 'lib/ipaddress/ipv6.rb', line 250

def [](index)
  @groups[index]
end

#address ⇒ Object

Returns the IPv6 address in uncompressed form:

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.address
  #=> "2001:0db8:0000:0000:0008:0800:200c:417a"



116
117
118
 
# File 'lib/ipaddress/ipv6.rb', line 116

def address
  @address
end

#bits ⇒ Object

Returns the address portion of an IP in binary format, as a string containing a sequence of 0 and 1

ip6 = IPAddress("2001:db8::8:800:200c:417a")

ip6.bits 
  #=> "0010000000000001000011011011100000 [...] "



397
398
399
 
# File 'lib/ipaddress/ipv6.rb', line 397

def bits
  data.unpack("B*").first
end

#compressed ⇒ Object

Compressed form of the IPv6 address

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.compressed
  #=> "2001:db8::8:800:200c:417a"



357
358
359
 
# File 'lib/ipaddress/ipv6.rb', line 357

def compressed
  @compressed
end

#data ⇒ Object

Returns the address portion of an IPv6 object in a network byte order format.

ip6 = IPAddress "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

a = Socket.open(params) # socket details here
ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
binary_data = ["Address: "].pack("a*") + ip.data

# Send binary data
a.puts binary_data



286
287
288
 
# File 'lib/ipaddress/ipv6.rb', line 286

def data
  @groups.pack("n8")
end

#groups ⇒ Object

Returns an array with the 16 bits groups in decimal format:

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.groups
  #=> [8193, 3512, 0, 0, 8, 2048, 8204, 16762]



129
130
131
 
# File 'lib/ipaddress/ipv6.rb', line 129

def groups
  @groups
end

#hexs ⇒ Object

Returns an array of the 16 bits groups in hexdecimal format:

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.hexs
  #=> ["2001", "0db8", "0000", "0000", "0008", "0800", "200c", "417a"]

Not to be confused with the similar IPv6#to_hex method.



301
302
303
 
# File 'lib/ipaddress/ipv6.rb', line 301

def hexs
  @address.split(":")
end

#include?(oth) ⇒ Boolean

Checks whether a subnet includes the given IP address.

Example:

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
addr = IPAddress "2001:db8::8:800:200c:1/128"

ip6.include? addr
  #=> true

ip6.include? IPAddress("2001:db8:1::8:800:200c:417a/76")
  #=> false

Returns:

  • (Boolean) 


345
346
347
 
# File 'lib/ipaddress/ipv6.rb', line 345

def include?(oth)
  @prefix <= oth.prefix and network_u128 == self.class.new(oth.address+"/#@prefix").network_u128
end

#literal ⇒ Object

Literal version of the IPv6 address

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.literal
  #=> "2001-0db8-0000-0000-0008-0800-200c-417a.ipv6-literal.net"



429
430
431
 
# File 'lib/ipaddress/ipv6.rb', line 429

def literal
  @address.gsub(":","-") + ".ipv6-literal.net"
end

#loopback? ⇒ Boolean

Returns true if the address is a loopback address

See IPAddress::IPv6::Loopback for more information

Returns:

  • (Boolean) 


375
376
377
 
# File 'lib/ipaddress/ipv6.rb', line 375

def loopback?
  @prefix == 128 and @compressed == "::1"
end

#mapped? ⇒ Boolean

Returns true if the address is a mapped address

See IPAddress::IPv6::Mapped for more information

Returns:

  • (Boolean) 


384
385
386
 
# File 'lib/ipaddress/ipv6.rb', line 384

def mapped?
  to_u128 >> 32 == 0xffff
end

#network? ⇒ Boolean

True if the IPv6 address is a network

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.network?
  #=> false

ip6 = IPAddress "2001:db8:8:800::/64"

ip6.network?
  #=> true

Returns:

  • (Boolean) 


232
233
234
 
# File 'lib/ipaddress/ipv6.rb', line 232

def network?
  to_u128 | @prefix.to_u128 == @prefix.to_u128
end

#network_u128 ⇒ Object

Returns the network number in Unsigned 128bits format

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.network_u128
  #=> 42540766411282592856903984951653826560



327
328
329
 
# File 'lib/ipaddress/ipv6.rb', line 327

def network_u128
  to_u128 & @prefix.to_u128
end

#prefix ⇒ Object

Returns an instance of the prefix object

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.prefix
  #=> 64



141
142
143
 
# File 'lib/ipaddress/ipv6.rb', line 141

def prefix
  @prefix
end

#prefix=(num) ⇒ Object

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 = IPAddress("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"



162
163
164
 
# File 'lib/ipaddress/ipv6.rb', line 162

def prefix=(num)
  @prefix = Prefix128.new(num)
end

#reverse ⇒ Object Also known as: arpa

Returns the IPv6 address in a DNS reverse lookup string, as per RFC3172 and RFC2874.

ip6 = IPAddress "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"



314
315
316
 
# File 'lib/ipaddress/ipv6.rb', line 314

def reverse
  to_hex.reverse.gsub(/./){|c| c+"."} + "ip6.arpa"
end

#to_hex ⇒ Object

Returns a Base16 number representing the IPv6 address

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.to_hex
  #=> "20010db80000000000080800200c417a"



264
265
266
 
# File 'lib/ipaddress/ipv6.rb', line 264

def to_hex
  hexs.join("")
end

#to_i ⇒ Object Also known as: to_u128

Returns a decimal format (unsigned 128 bit) of the IPv6 address

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.to_i
  #=> 42540766411282592856906245548098208122



214
215
216
 
# File 'lib/ipaddress/ipv6.rb', line 214

def to_i
  to_hex.hex
end

#to_s ⇒ Object

Returns the IPv6 address in a human readable form, using the compressed address.

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.to_s
  #=> "2001:db8::8:800:200c:417a"



201
202
203
 
# File 'lib/ipaddress/ipv6.rb', line 201

def to_s
  @compressed
end

#to_string ⇒ Object

Returns the IPv6 address in a human readable form, using the compressed address.

ip6 = IPAddress "2001:0db8:0000:0000:0008:0800:200c:417a/64"

ip6.to_string
  #=> "2001:db8::8:800:200c:417a/64"



188
189
190
 
# File 'lib/ipaddress/ipv6.rb', line 188

def to_string
  "#@compressed/#@prefix"
end

#to_string_uncompressed ⇒ Object

Unlike its counterpart IPv6#to_string method, IPv6#to_string_uncompressed returns the whole IPv6 address and prefix in an uncompressed form

ip6 = IPAddress "2001:db8::8:800:200c:417a/64"

ip6.to_string_uncompressed
  #=> "2001:0db8:0000:0000:0008:0800:200c:417a/64"



175
176
177
 
# File 'lib/ipaddress/ipv6.rb', line 175

def to_string_uncompressed
  "#@address/#@prefix"
end

#unspecified? ⇒ Boolean

Returns true if the address is an unspecified address

See IPAddress::IPv6::Unspecified for more information

Returns:

  • (Boolean) 


366
367
368
 
# File 'lib/ipaddress/ipv6.rb', line 366

def unspecified?
  @prefix == 128 and @compressed == "::"
end