Class: VirtualBox::Net

Inherits:
Object
  • Object
show all
Defined in:
lib/virtual_box/net.rb,
lib/virtual_box/net/dhcp.rb

Overview

Descriptor for a virtual network managed by Virtual Box.

Defined Under Namespace

Classes: Dhcp

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Net

Creates a virtual network specification rule based on the given attributes.

The network is not automatically added to VirtualBox.

Parameters:

  • options (Hash<Symbol, Object>) (defaults to: {}) —

    ActiveRecord-style initial values for attributes; can be used together with Net#to_hash to save and restore



57
58
59
 
# File 'lib/virtual_box/net.rb', line 57

def initialize(options = {})
  options.each { |k, v| self.send :"#{k}=", v }
end

Instance Attribute Details

#dhcp ⇒ VirtualBox::Net::Dhcp, NilClass

The VirtualBox-powered DHCP server configured to serve this interface.

Returns:



39
40
41
 
# File 'lib/virtual_box/net.rb', line 39

def dhcp
  @dhcp
end

#if_name ⇒ String (readonly)

The name of the host’s virtual NIC that’s connected to this network.

VirtualBox’s CLI does not provide a way to set the NIC name. Therefore, this attribute is read-only, and it is automatically set when the network is registered with VirtualBox.

Returns:

  • (String) 


19
20
21
 
# File 'lib/virtual_box/net.rb', line 19

def if_name
  @if_name
end

#ip ⇒ String

The IP address received by the host computer on this virtual network.

Returns:

  • (String) 


7
8
9
 
# File 'lib/virtual_box/net.rb', line 7

def ip
  @ip
end

#mac ⇒ String (readonly)

The MAC address of the host’s virtual NIC that’s connected to this network.

VirtualBox’s CLI does not provide a way to set the MAC. Therefore, this attribute is read-only, and it is automatically set when the network is registered with VirtualBox.

Returns:

  • (String) 


35
36
37
 
# File 'lib/virtual_box/net.rb', line 35

def mac
  @mac
end

#name ⇒ String (readonly)

The name of the VirtualBox internal network.

VirtualBox’s CLI does not provide a way to set the internal network name. Therefore, this attribute is read-only, and it is automatically set when the network is registered with VirtualBox.

Returns:

  • (String) 


27
28
29
 
# File 'lib/virtual_box/net.rb', line 27

def name
  @name
end

#netmask ⇒ String

The network mask received by the host computer on this virtual network.

Returns:

  • (String) 


11
12
13
 
# File 'lib/virtual_box/net.rb', line 11

def netmask
  @netmask
end

Class Method Details

.all ⇒ Array<VirtualBox::Net>

The virtual networks added to VirtualBox.

Returns:



127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/virtual_box/net.rb', line 127

def self.all
  dhcps = VirtualBox::Net::Dhcp.all
  
  output = VirtualBox.run_command! ['VBoxManage', '--nologo', 'list',
                                    '--long', 'hostonlyifs']
  output.split("\n\n").map do |net_info|
    net = new.from_net_info(net_info)
    net.dhcp = dhcps[net.name]
    net
  end
end

.host_nics ⇒ Array<Hash<Symbol, Object>>

Information about the NICs attached to the computer.

Returns:

  • (Array<Hash<Symbol, Object>>) —

    an array with one hash per NIC; hashes have the following keys:

    :name

    the NIC device’s name (use when setting a Nic’s net_name)

    :ip

    the IP address (compare against 0.0.0.0 to see if it’s live)

    :mask

    the network mask used to figure out broadcasting

    :mac

    the NICs MAC address (format: “AB0123456789”)



167
168
169
 
# File 'lib/virtual_box/net.rb', line 167

def self.host_nics
  @host_nics ||= host_nics!
end

.host_nics! ⇒ Array<Hash<Symbol, Object>>

Queries VirtualBox for the network interfaces on the computer.

Returns:

  • (Array<Hash<Symbol, Object>>) —

    an array with one hash per NIC; hashes have the following keys:

    :name

    the NIC device’s name (use when setting a Nic’s net_name)

    :ip

    the IP address (compare against 0.0.0.0 to see if it’s live)

    :mask

    the network mask used to figure out broadcasting

    :mac

    the NICs MAC address (format: “AB0123456789”)



174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/virtual_box/net.rb', line 174

def self.host_nics!
  output = VirtualBox.run_command! ['VBoxManage', '--nologo', 'list',
                                    '--long', 'hostifs']
  output.split("\n\n").map do |nic_info|
    info = Hash[nic_info.split("\n").map { |line|
      line.split(':', 2).map(&:strip)
    }]
    {
      :name => info['Name'], :ip => info['IPAddress'],
      :mask => info['NetworkMask'],
      :mac => info['HardwareAddress'].upcase.gsub(/[^0-9A-F]/, '')
    }
  end
end

Instance Method Details

#add ⇒ VirtualBox::Net

Adds this virtual network specification to VirtualBox.

Returns:



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/virtual_box/net.rb', line 80

def add
  unless if_name.nil?
    raise "Virtual network already added to VirtualBox"
  end
  
  # Create the network and pull its name.
  output = VirtualBox.run_command! ['VBoxManage', '--nologo', 'hostonlyif',
                                    'create']
  unless match = /^interface\s+'(.*)'\s+.*created/i.match(output)
    raise "VirtualBox output does not include interface name"
  end
  @if_name = match[1]
  
  # Now list all the networks to pull the rest of the information.
  networks = self.class.all
  network = networks.find { |net| net.if_name == if_name }
  @name = network.name
  @mac = network.mac
  
  if (ip && ip != network.ip) || (netmask && netmask != network.netmask)
    VirtualBox.run_command! ['VBoxManage', '--nologo', 'hostonlyif',
        'ipconfig', if_name, '--ip', ip, '--netmask', netmask]
  else
    self.ip = network.ip
    self.netmask = network.netmask
  end
  
  # Register the DHCP server, if it's connected.
  dhcp.add self if dhcp
  
  self
end

#from_net_info(net_info) ⇒ VirtualBox::Net

Parses information about a DHCP server returned by VirtualBox.

The parsed information is used to replace this network’s specification.

Parameters:

  • net_info (String) —

    output from “VBoxManage list –long hostonlyifs” for one network

Returns:



145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/virtual_box/net.rb', line 145

def from_net_info(net_info)
  info = Hash[net_info.split("\n").map { |line|
    line.split(':', 2).map(&:strip)
  }]
  
  @if_name = info['Name']
  @name = info['VBoxNetworkName']
  @mac = info['HardwareAddress'].upcase.gsub(/[^0-9A-F]/, '')
  self.ip = info['IPAddress']
  self.netmask = info['NetworkMask']
  self
end

#live? ⇒ Boolean

True if this virtual network has been added to VirtualBox.

Returns:

  • (Boolean) —

    true if this network exists, false otherwise



71
72
73
74
75
 
# File 'lib/virtual_box/net.rb', line 71

def live?
  networks = self.class.all
  network = networks.find { |net| net.if_name == if_name }
  network ? true : false
end

#remove ⇒ VirtualBox::Net

Removes this virtual network from VirtualBox’s database.

Returns:



116
117
118
119
120
121
122
 
# File 'lib/virtual_box/net.rb', line 116

def remove
  unless if_name.nil?
    dhcp.remove self if dhcp
    VirtualBox.run_command ['VBoxManage', 'hostonlyif', 'remove', if_name]
  end
  self
end

#to_hash ⇒ Hash<Symbol, Object>

Hash capturing this specification. Can be passed to Net#new.

Returns:

  • (Hash<Symbol, Object>) —

    Ruby-friendly Hash that can be used to re-create this virtual network specification



65
66
67
 
# File 'lib/virtual_box/net.rb', line 65

def to_hash
  { :ip => ip, :netmask => netmask, :dhcp => dhcp && dhcp.to_hash }
end