Class: Libvirt::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/libvirt/connection.rb

Overview

Describes a connection to an instance of libvirt. This instance may be local or remote.

Initiating a Connection

Basic

A basic example of initiating a connection is to just allow the libvirt client library to choose the best (first available) hypervisor for you. If you're only running one hypervisor or you're not sure what is available on your machine, then this is the easiest option to get started:

conn = Libvirt::Connection.new

A shortcut is also provided for your convenience:

conn = Libvirt.connect

Specifying a URI

Libvirt connections are made by giving a URI to libvirt, which can describe a local or remote libvirt instance (remote being that libvirtd is running). The following is an example of a local VirtualBox connection:

conn = Libvirt::Connection.new("vbox:///session")

And perhaps a remote qemu connection:

conn = Libvirt::Connection.new("qemu+tcp://10.0.0.1/system")

Readonly Connections

A readonly connection can be made by specifying the readonly option to be truthy. A couple examples follow:

conn = Libvirt::Connection.new("vbox:///session", :readonly => true)
conn = Libvirt::Connection.new(:readonly => true)

Basic Information of a Connection

Once you have a connection object, you can gather basic information about it by using methods such as #hypervisor, #capabilities, etc.:

puts "Hypervisor type: #{conn.hypervisor}"
puts "Hypervisor version: #{conn.hypervisor_verison}"
puts "Library version: #{conn.lib_version}"

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Connection

Opens a new connection to libvirt. This connection may be local or remote. If a uri is given, an attempt to connect to the given URI is made. The URI can be used to specify the location of libvirt along with the hypervisor to connect to.

Parameters:

  • uri (String) 


56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/libvirt/connection.rb', line 56

def initialize(*args)
  opts = args.last.is_a?(Hash) ? args.pop : {}
  uri = args.first

  if args.first.is_a?(FFI::Pointer)
    # Store away the pointer and increase the reference count, since
    # we're taking ownership of this pointer directly.
    @pointer = args.first
    FFI::Libvirt.virConnectRef(self)
  end

  # If the pointer is not yet set, attempt to open a connection with
  # the specified URI.
  @pointer ||= if opts[:readonly]
    FFI::Libvirt.virConnectOpenReadOnly(uri)
  else
    FFI::Libvirt.virConnectOpen(uri)
  end

  ObjectSpace.define_finalizer(self, method(:finalize))
end

Instance Method Details

#capabilities ⇒ String

Returns the capabilities of the connected hypervisor/driver. Returns them as an XML string. This method calls virConnectGetCapabilities. This will probably be parsed into a more useful format in the future.

Returns:

  • (String) 


129
130
131
 
# File 'lib/libvirt/connection.rb', line 129

def capabilities
  FFI::Libvirt.virConnectGetCapabilities(self)
end

#domains ⇒ Collection::DomainCollection

Returns the domains (both active and inactive) related to this connection. The various states of the domains returned can be queried using Domain#state.

Returns:



83
84
85
 
# File 'lib/libvirt/connection.rb', line 83

def domains
  Collection::DomainCollection.new(self)
end

#encrypted? ⇒ Boolean

Returns a boolean of whether the connection is encrypted or not.

Returns:

  • (Boolean) 


169
170
171
172
173
 
# File 'lib/libvirt/connection.rb', line 169

def encrypted?
  result = FFI::Libvirt.virConnectIsEncrypted(self)
  return nil if result == -1
  result == 1
end

#hostname ⇒ String

Returns the system hostname on which the hypervisor is running. Therefore, if connected to a remote libvirtd daemon, then it will return the hostname of that machine.

Returns:

  • (String) 


138
139
140
 
# File 'lib/libvirt/connection.rb', line 138

def hostname
  FFI::Libvirt.virConnectGetHostname(self)
end

#hypervisor_version ⇒ Array

Returns the version of the hypervisor. This version is returned as an array representation as [major, minor, patch].

Returns:

  • (Array) 


188
189
190
191
192
 
# File 'lib/libvirt/connection.rb', line 188

def hypervisor_version
  output_ptr = FFI::MemoryPointer.new(:ulong)
  FFI::Libvirt.virConnectGetVersion(self, output_ptr)
  FFI::Libvirt::Util.parse_version_number(output_ptr.get_ulong(0))
end

#interfaces ⇒ Collection::InterfaceCollection

Returns the interfaces (both active and inactive) related to this connection.

Returns:



91
92
93
 
# File 'lib/libvirt/connection.rb', line 91

def interfaces
  Collection::InterfaceCollection.new(self)
end

#lib_version ⇒ Array

Returns the version of libvirt which the daemon on the other side is running. If not connected to a remote daemon, it will return the version of libvirt on this machine. The result is an array representatin of the version, as [major, minor, patch].

Returns:

  • (Array) 


200
201
202
203
204
 
# File 'lib/libvirt/connection.rb', line 200

def lib_version
  output_ptr = FFI::MemoryPointer.new(:ulong)
  FFI::Libvirt.virConnectGetLibVersion(self, output_ptr)
  FFI::Libvirt::Util.parse_version_number(output_ptr.get_ulong(0))
end

#max_virtual_cpus(type) ⇒ Integer

Returns the maximum number of virtual CPUs for a given domain type.

Returns:

  • (Integer) 


162
163
164
 
# File 'lib/libvirt/connection.rb', line 162

def max_virtual_cpus(type)
  FFI::Libvirt.virConnectGetMaxVcpus(self, type)
end

#networks ⇒ Collection::NetworkCollection

Returns the networks related to this connection.

Returns:



98
99
100
 
# File 'lib/libvirt/connection.rb', line 98

def networks
  Collection::NetworkCollection.new(self)
end

#node ⇒ Node

Returns a node object to retrieve information about the node which this connection is established to.

Returns:



120
121
122
 
# File 'lib/libvirt/connection.rb', line 120

def node
  Node.new(self)
end

#nwfilters ⇒ Collection::NWFilterCollection

Returns the network filters related to this connection.

Returns:



105
106
107
 
# File 'lib/libvirt/connection.rb', line 105

def nwfilters
  Collection::NWFilterCollection.new(self)
end

#secure? ⇒ Boolean

Returns a boolean of whether the connection is secure or not.

Returns:

  • (Boolean) 


178
179
180
181
182
 
# File 'lib/libvirt/connection.rb', line 178

def secure?
  result = FFI::Libvirt.virConnectIsSecure(self)
  return nil if result == -1
  result == 1
end

#storage_pools ⇒ Collection::StoragePoolCollection

Returns the storage pools related to this connection

Returns:



112
113
114
 
# File 'lib/libvirt/connection.rb', line 112

def storage_pools
  Collection::StoragePoolCollection.new(self)
end

#to_ptr ⇒ FFI::Pointer

Provides the pointer of the connection. This allows this object to be used directly with the FFI layer, as if this object were actually a virConnectPtr.

Returns:

  • (FFI::Pointer) 


211
212
213
 
# File 'lib/libvirt/connection.rb', line 211

def to_ptr
  @pointer
end

#type ⇒ String Also known as: hypervisor

Returns the name of the hypervisor. This is named "type" since that is the terminology which libvirt itself uses. This is also aliased as hypervisor since that is more friendly.

Returns:

  • (String) 


154
155
156
 
# File 'lib/libvirt/connection.rb', line 154

def type
  FFI::Libvirt.virConnectGetType(self)
end

#uri ⇒ String

Returns the URI of the connection.

Returns:

  • (String) 


145
146
147
 
# File 'lib/libvirt/connection.rb', line 145

def uri
  FFI::Libvirt.virConnectGetURI(self)
end