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



59
60
61
 
# File 'lib/virtual_box/net.rb', line 59

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:



41
42
43
 
# File 'lib/virtual_box/net.rb', line 41

def dhcp
  @dhcp
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) 


37
38
39
 
# File 'lib/virtual_box/net.rb', line 37

def mac
  @mac
end

#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 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

#vbox_name ⇒ String (readonly)

The name of the VirtualBox internal network.

This is most likely not useful outside the VirtualBox API.

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) 


29
30
31
 
# File 'lib/virtual_box/net.rb', line 29

def vbox_name
  @vbox_name
end

Class Method Details

.all(with_dhcp = true) ⇒ Array<VirtualBox::Net>

The virtual networks added to VirtualBox.

Parameters:

  • with_dhcp (Boolean) (defaults to: true) —

    if false, the returned VirtualBox::Net instances will have their dhcp property set to nil, even if they have DHCP servers; this saves a CLI call when DHCP information is not needed

Returns:



131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/virtual_box/net.rb', line 131

def self.all(with_dhcp = true)
  dhcps = with_dhcp ? 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.vbox_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”)



184
185
186
 
# File 'lib/virtual_box/net.rb', line 184

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”)



191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/virtual_box/net.rb', line 191

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

.named(name, with_dhcp = true) ⇒ Object

The virtual network added to VirtualBox with a given name.

This is a convenience for calling find on Net.all, so it’s just as inefficient.

Parameters:

  • name (String) —

    the name to look for

  • with_dhcp (Boolean) (defaults to: true) —

    if false, the returned VirtualBox::Net instance will have its dhcp property set to nil, even if it has a DHCP server; this saves a CLI call when DHCP information is not needed



151
152
153
154
 
# File 'lib/virtual_box/net.rb', line 151

def self.named(name, with_dhcp = true)
  networks = all with_dhcp
  networks.find { |net| net.name == name }
end

Instance Method Details

#add ⇒ VirtualBox::Net

Adds this virtual network specification to VirtualBox.

Returns:



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
112
 
# File 'lib/virtual_box/net.rb', line 82

def add
  unless 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
  @name = match[1]
  
  # Query VirtualBox to pull the rest of the information.
  network = self.class.named name
  @vbox_name = network.vbox_name
  @mac = network.mac
  
  if (ip && ip != network.ip) || (netmask && netmask != network.netmask)
    VirtualBox.run_command! ['VBoxManage', '--nologo', 'hostonlyif',
        'ipconfig', 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:



162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/virtual_box/net.rb', line 162

def from_net_info(net_info)
  info = Hash[net_info.split("\n").map { |line|
    line.split(':', 2).map(&:strip)
  }]
  
  @name = info['Name']
  @vbox_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



73
74
75
76
77
 
# File 'lib/virtual_box/net.rb', line 73

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

#remove ⇒ VirtualBox::Net

Removes this virtual network from VirtualBox’s database.

Returns:



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

def remove
  unless name.nil?
    dhcp.remove self if dhcp
    VirtualBox.run_command ['VBoxManage', 'hostonlyif', 'remove', 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



67
68
69
 
# File 'lib/virtual_box/net.rb', line 67

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