| Dir : /proc/self/root/opt/saltstack/salt/lib/python3.10/site-packages/salt/utils/ |
| Server: Linux ngx353.inmotionhosting.com 4.18.0-553.22.1.lve.1.el8.x86_64 #1 SMP Tue Oct 8 15:52:54 UTC 2024 x86_64 IP: 209.182.202.254 |
| Dir : //proc/self/root/opt/saltstack/salt/lib/python3.10/site-packages/salt/utils/virtualbox.py |
"""
Utilities to help make requests to virtualbox
The virtualbox SDK reference can be found at http://download.virtualbox.org/virtualbox/SDKRef.pdf
This code assumes vboxapi.py from VirtualBox distribution
being in PYTHONPATH, or installed system-wide
"""
import logging
import re
import time
import salt.utils.compat
import salt.utils.data
from salt.utils.timeout import wait_for
log = logging.getLogger(__name__)
HAS_LIBS = False
try:
import vboxapi
HAS_LIBS = True
except ImportError:
VirtualBoxManager = None
log.trace("Couldn't import VirtualBox API")
_virtualboxManager = None
"""
Attributes we expect to have when converting an XPCOM object to a dict
"""
XPCOM_ATTRIBUTES = {
"IMachine": [
"id",
"name",
"accessible",
"description",
"groups",
"memorySize",
"OSTypeId",
"state",
],
"INetworkAdapter": [
"adapterType",
"slot",
"enabled",
"MACAddress",
"bridgedInterface",
"hostOnlyInterface",
"internalNetwork",
"NATNetwork",
"genericDriver",
"cableConnected",
"lineSpeed",
"lineSpeed",
],
}
UNKNOWN_MACHINE_STATE = ("Unknown", "This state is unknown to us. Might be new?")
MACHINE_STATE_LIST = [
("Null", "Null value (never used by the API)"),
(
"PoweredOff",
"The machine is not running and has no saved execution state; "
"it has either never been started or been shut down successfully.",
),
(
"Saved",
"The machine is not currently running, but the execution state of the machine"
" has been saved to an external file when it was running, from where it can be"
" resumed.",
),
(
"Teleported",
"The machine was teleported to a different host (or process) and then powered"
" off. Take care when powering it on again may corrupt resources it shares with"
" the teleportation target (e.g. disk and network).",
),
(
"Aborted",
"The process running the machine has terminated abnormally. This may indicate a"
" crash of the VM process in host execution context, or the VM process has been"
" terminated externally.",
),
("Running", "The machine is currently being executed."),
("Paused", "Execution of the machine has been paused."),
(
"Stuck",
"Execution of the machine has reached the 'Guru Meditation' condition. This"
" indicates a severe error in the hypervisor itself.",
),
(
"Teleporting",
"The machine is about to be teleported to a different host or process. It is"
" possible to pause a machine in this state, but it will go to the"
" TeleportingPausedVM state and it will not be possible to resume it again"
" unless the teleportation fails.",
),
(
"LiveSnapshotting",
"A live snapshot is being taken. The machine is running normally, but some of"
" the runtime configuration options are inaccessible. Also, if paused while in"
" this state it will transition to OnlineSnapshotting and it will not be resume"
" the execution until the snapshot operation has completed.",
),
(
"Starting",
"Machine is being started after powering it on from a zero execution state.",
),
(
"Stopping",
"Machine is being normally stopped powering it off, or after the guest OS has"
" initiated a shutdown sequence.",
),
("Saving", "Machine is saving its execution state to a file."),
(
"Restoring",
"Execution state of the machine is being restored from a file after powering it"
" on from the saved execution state.",
),
(
"TeleportingPausedVM",
"The machine is being teleported to another host or process, but it is not "
"running. This is the paused variant of the Teleporting state.",
),
("TeleportingIn", "Teleporting the machine state in from another host or process."),
(
"FaultTolerantSyncing",
"The machine is being synced with a fault tolerant VM running else-where.",
),
(
"DeletingSnapshotOnline",
"Like DeletingSnapshot , but the merging of media is ongoing in the "
"background while the machine is running.",
),
(
"DeletingSnapshotPaused",
"Like DeletingSnapshotOnline , but the machine was paused when "
"the merging of differencing media was started.",
),
(
"OnlineSnapshotting",
"Like LiveSnapshotting , but the machine was paused when the merging "
"of differencing media was started.",
),
(
"RestoringSnapshot",
"A machine snapshot is being restored; this typically does not take long.",
),
(
"DeletingSnapshot",
"A machine snapshot is being deleted; this can take a long time since this may"
" require merging differencing media. This value indicates that the machine is"
" not running while the snapshot is being deleted.",
),
("SettingUp", "Lengthy setup operation is in progress."),
("Snapshotting", "Taking an (offline) snapshot."),
(
"FirstOnline",
"Pseudo-state: first online state (for use in relational expressions).",
),
(
"LastOnline",
"Pseudo-state: last online state (for use in relational expressions).",
),
(
"FirstTransient",
"Pseudo-state: first transient state (for use in relational expressions).",
),
(
"LastTransient",
"Pseudo-state: last transient state (for use in relational expressions).",
),
]
MACHINE_STATES = dict(MACHINE_STATE_LIST)
"""
Dict of states {
<number>: ( <name>, <description> )
}
"""
MACHINE_STATES_ENUM = dict(enumerate(MACHINE_STATE_LIST))
def vb_get_manager():
"""
Creates a 'singleton' manager to communicate with a local virtualbox hypervisor.
@return:
@rtype: VirtualBoxManager
"""
global _virtualboxManager
if _virtualboxManager is None and HAS_LIBS:
salt.utils.compat.reload(vboxapi)
_virtualboxManager = vboxapi.VirtualBoxManager(None, None)
return _virtualboxManager
def vb_get_box():
"""
Needed for certain operations in the SDK e.g creating sessions
@return:
@rtype: IVirtualBox
"""
vb_get_manager()
try:
# This works in older versions of the SDK, but does not seem to work anymore.
vbox = _virtualboxManager.vbox
except AttributeError:
vbox = _virtualboxManager.getVirtualBox()
return vbox
def vb_get_max_network_slots():
"""
Max number of slots any machine can have
@return:
@rtype: number
"""
sysprops = vb_get_box().systemProperties
totals = [
sysprops.getMaxNetworkAdapters(adapter_type)
for adapter_type in [
1, # PIIX3 A PIIX3 (PCI IDE ISA Xcelerator) chipset.
2, # ICH9 A ICH9 (I/O Controller Hub) chipset
]
]
return sum(totals)
def vb_get_network_adapters(machine_name=None, machine=None):
"""
A valid machine_name or a machine is needed to make this work!
@param machine_name:
@type machine_name: str
@param machine:
@type machine: IMachine
@return: INetorkAdapter's converted to dicts
@rtype: [dict]
"""
if machine_name:
machine = vb_get_box().findMachine(machine_name)
network_adapters = []
for i in range(vb_get_max_network_slots()):
try:
inetwork_adapter = machine.getNetworkAdapter(i)
network_adapter = vb_xpcom_to_attribute_dict(
inetwork_adapter, "INetworkAdapter"
)
network_adapter["properties"] = inetwork_adapter.getProperties("")
network_adapters.append(network_adapter)
except Exception: # pylint: disable=broad-except
pass
return network_adapters
def vb_wait_for_network_address(
timeout, step=None, machine_name=None, machine=None, wait_for_pattern=None
):
"""
Wait until a machine has a network address to return or quit after the timeout
@param timeout: in seconds
@type timeout: float
@param step: How regularly we want to check for ips (in seconds)
@type step: float
@param machine_name:
@type machine_name: str
@param machine:
@type machine: IMachine
@type wait_for_pattern: str
@param wait_for_pattern:
@type machine: str
@return:
@rtype: list
"""
kwargs = {
"machine_name": machine_name,
"machine": machine,
"wait_for_pattern": wait_for_pattern,
}
return wait_for(
vb_get_network_addresses,
timeout=timeout,
step=step,
default=[],
func_kwargs=kwargs,
)
def _check_session_state(xp_session, expected_state="Unlocked"):
"""
@param xp_session:
@type xp_session: ISession from the Virtualbox API
@param expected_state: The constant descriptor according to the docs
@type expected_state: str
@return:
@rtype: bool
"""
state_value = getattr(
_virtualboxManager.constants, "SessionState_" + expected_state
)
return xp_session.state == state_value
def vb_wait_for_session_state(xp_session, state="Unlocked", timeout=10, step=None):
"""
Waits until a session state has been reached, checking at regular intervals.
@param xp_session:
@type xp_session: ISession from the Virtualbox API
@param state: The constant descriptor according to the docs
@type state: str
@param timeout: in seconds
@type timeout: int | float
@param step: Intervals at which the value is checked
@type step: int | float
@return: Did we reach the state?
@rtype: bool
"""
args = (xp_session, state)
wait_for(
_check_session_state, timeout=timeout, step=step, default=False, func_args=args
)
def vb_get_network_addresses(machine_name=None, machine=None, wait_for_pattern=None):
"""
TODO distinguish between private and public addresses
A valid machine_name or a machine is needed to make this work!
!!!
Guest prerequisite: GuestAddition
!!!
Thanks to Shrikant Havale for the StackOverflow answer http://stackoverflow.com/a/29335390
More information on guest properties: https://www.virtualbox.org/manual/ch04.html#guestadd-guestprops
@param machine_name:
@type machine_name: str
@param machine:
@type machine: IMachine
@return: All the IPv4 addresses we could get
@rtype: str[]
"""
if machine_name:
machine = vb_get_box().findMachine(machine_name)
ip_addresses = []
log.debug("checking for power on:")
if machine.state == _virtualboxManager.constants.MachineState_Running:
log.debug("got power on:")
# wait on an arbitrary named property
# for instance use a dhcp client script to set a property via VBoxControl guestproperty set dhcp_done 1
if wait_for_pattern and not machine.getGuestPropertyValue(wait_for_pattern):
log.debug("waiting for pattern:%s:", wait_for_pattern)
return None
_total_slots = machine.getGuestPropertyValue("/VirtualBox/GuestInfo/Net/Count")
# upon dhcp the net count drops to 0 and it takes some seconds for it to be set again
if not _total_slots:
log.debug("waiting for net count:%s:", wait_for_pattern)
return None
try:
total_slots = int(_total_slots)
for i in range(total_slots):
try:
address = machine.getGuestPropertyValue(
f"/VirtualBox/GuestInfo/Net/{i}/V4/IP"
)
if address:
ip_addresses.append(address)
except Exception as e: # pylint: disable=broad-except
log.debug(e.message)
except ValueError as e:
log.debug(e.message)
return None
log.debug("returning ip_addresses:%s:", ip_addresses)
return ip_addresses
def vb_list_machines(**kwargs):
"""
Which machines does the hypervisor have
@param kwargs: Passed to vb_xpcom_to_attribute_dict to filter the attributes
@type kwargs: dict
@return: Untreated dicts of the machines known to the hypervisor
@rtype: [{}]
"""
manager = vb_get_manager()
machines = manager.getArray(vb_get_box(), "machines")
return [
vb_xpcom_to_attribute_dict(machine, "IMachine", **kwargs)
for machine in machines
]
def vb_create_machine(name=None):
"""
Creates a machine on the virtualbox hypervisor
TODO pass more params to customize machine creation
@param name:
@type name: str
@return: Representation of the created machine
@rtype: dict
"""
vbox = vb_get_box()
log.info("Create virtualbox machine %s ", name)
groups = None
os_type_id = "Other"
new_machine = vbox.createMachine(
None, name, groups, os_type_id, None # Settings file # flags
)
vbox.registerMachine(new_machine)
log.info("Finished creating %s", name)
return vb_xpcom_to_attribute_dict(new_machine, "IMachine")
def vb_clone_vm(name=None, clone_from=None, clone_mode=0, timeout=10000, **kwargs):
"""
Tells virtualbox to create a VM by cloning from an existing one
@param name: Name for the new VM
@type name: str
@param clone_from:
@type clone_from: str
@param timeout: maximum time in milliseconds to wait or -1 to wait indefinitely
@type timeout: int
@return dict of resulting VM
"""
vbox = vb_get_box()
log.info("Clone virtualbox machine %s from %s", name, clone_from)
source_machine = vbox.findMachine(clone_from)
groups = None
os_type_id = "Other"
new_machine = vbox.createMachine(
None, name, groups, os_type_id, None # Settings file # flags
)
progress = source_machine.cloneTo(
new_machine, clone_mode, None # CloneMode # CloneOptions : None = Full?
)
progress.waitForCompletion(timeout)
log.info("Finished cloning %s from %s", name, clone_from)
vbox.registerMachine(new_machine)
return vb_xpcom_to_attribute_dict(new_machine, "IMachine")
def _start_machine(machine, session):
"""
Helper to try and start machines
@param machine:
@type machine: IMachine
@param session:
@type session: ISession
@return:
@rtype: IProgress or None
"""
try:
return machine.launchVMProcess(session, "", "")
except Exception as e: # pylint: disable=broad-except
log.debug(e.message, exc_info=True)
return None
def vb_start_vm(name=None, timeout=10000, **kwargs):
"""
Tells Virtualbox to start up a VM.
Blocking function!
@param name:
@type name: str
@param timeout: Maximum time in milliseconds to wait or -1 to wait indefinitely
@type timeout: int
@return untreated dict of started VM
"""
# Time tracking
start_time = time.time()
timeout_in_seconds = timeout / 1000
max_time = start_time + timeout_in_seconds
vbox = vb_get_box()
machine = vbox.findMachine(name)
session = _virtualboxManager.getSessionObject(vbox)
log.info(
"Starting machine %s in state %s", name, vb_machinestate_to_str(machine.state)
)
try:
# Keep trying to start a machine
args = (machine, session)
progress = wait_for(_start_machine, timeout=timeout_in_seconds, func_args=args)
if not progress:
progress = machine.launchVMProcess(session, "", "")
# We already waited for stuff, don't push it
time_left = max_time - time.time()
progress.waitForCompletion(time_left * 1000)
finally:
_virtualboxManager.closeMachineSession(session)
# The session state should best be unlocked otherwise subsequent calls might cause problems
time_left = max_time - time.time()
vb_wait_for_session_state(session, timeout=time_left)
log.info("Started machine %s", name)
return vb_xpcom_to_attribute_dict(machine, "IMachine")
def vb_stop_vm(name=None, timeout=10000, **kwargs):
"""
Tells Virtualbox to stop a VM.
This is a blocking function!
@param name:
@type name: str
@param timeout: Maximum time in milliseconds to wait or -1 to wait indefinitely
@type timeout: int
@return untreated dict of stopped VM
"""
vbox = vb_get_box()
machine = vbox.findMachine(name)
log.info("Stopping machine %s", name)
session = _virtualboxManager.openMachineSession(machine)
try:
console = session.console
progress = console.powerDown()
progress.waitForCompletion(timeout)
finally:
_virtualboxManager.closeMachineSession(session)
vb_wait_for_session_state(session)
log.info(
"Stopped machine %s is now %s", name, vb_machinestate_to_str(machine.state)
)
return vb_xpcom_to_attribute_dict(machine, "IMachine")
def vb_destroy_machine(name=None, timeout=10000):
"""
Attempts to get rid of a machine and all its files from the hypervisor
@param name:
@type name: str
@param timeout int timeout in milliseconds
"""
vbox = vb_get_box()
log.info("Destroying machine %s", name)
machine = vbox.findMachine(name)
files = machine.unregister(2)
progress = machine.deleteConfig(files)
progress.waitForCompletion(timeout)
log.info("Finished destroying machine %s", name)
def vb_xpcom_to_attribute_dict(
xpcom,
interface_name=None,
attributes=None,
excluded_attributes=None,
extra_attributes=None,
):
"""
Attempts to build a dict from an XPCOM object.
Attributes that don't exist in the object return an empty string.
attribute_list = list of str or tuple(str,<a class>)
e.g attributes=[('bad_attribute', list)] --> { 'bad_attribute': [] }
@param xpcom:
@type xpcom:
@param interface_name: Which interface we will be converting from.
Without this it's best to specify the list of attributes you want
@type interface_name: str
@param attributes: Overrides the attributes used from XPCOM_ATTRIBUTES
@type attributes: attribute_list
@param excluded_attributes: Which should be excluded in the returned dict.
!!These take precedence over extra_attributes!!
@type excluded_attributes: attribute_list
@param extra_attributes: Which should be retrieved in addition those already being retrieved
@type extra_attributes: attribute_list
@return:
@rtype: dict
"""
# Check the interface
if interface_name:
m = re.search(rf"XPCOM.+implementing {interface_name}", str(xpcom))
if not m:
# TODO maybe raise error here?
log.warning(
"Interface %s is unknown and cannot be converted to dict",
interface_name,
)
return dict()
interface_attributes = set(attributes or XPCOM_ATTRIBUTES.get(interface_name, []))
if extra_attributes:
interface_attributes = interface_attributes.union(extra_attributes)
if excluded_attributes:
interface_attributes = interface_attributes.difference(excluded_attributes)
attribute_tuples = []
for attribute in interface_attributes:
if isinstance(attribute, tuple):
attribute_name = attribute[0]
attribute_class = attribute[1]
value = (attribute_name, getattr(xpcom, attribute_name, attribute_class()))
else:
value = (attribute, getattr(xpcom, attribute, ""))
attribute_tuples.append(value)
return dict(attribute_tuples)
def treat_machine_dict(machine):
"""
Make machine presentable for outside world.
!!!Modifies the input machine!!!
@param machine:
@type machine: dict
@return: the modified input machine
@rtype: dict
"""
machine.update(
{
"id": machine.get("id", ""),
"image": machine.get("image", ""),
"size": "{} MB".format(machine.get("memorySize", 0)),
"state": machine_get_machinestate_str(machine),
"private_ips": [],
"public_ips": [],
}
)
# Replaced keys
if "memorySize" in machine:
del machine["memorySize"]
return machine
def vb_machinestate_to_str(machinestate):
"""
Put a name to the state
@param machinestate: from the machine state enum from XPCOM
@type machinestate: int
@return:
@rtype: str
"""
return vb_machinestate_to_tuple(machinestate)[0]
def vb_machinestate_to_description(machinestate):
"""
Describe the given state
@param machinestate: from the machine state enum from XPCOM
@type machinestate: int | str
@return:
@rtype: str
"""
return vb_machinestate_to_tuple(machinestate)[1]
def vb_machinestate_to_tuple(machinestate):
"""
@param machinestate:
@type machinestate: int | str
@return:
@rtype: tuple(<name>, <description>)
"""
if isinstance(machinestate, int):
ret = MACHINE_STATES_ENUM.get(machinestate, UNKNOWN_MACHINE_STATE)
elif isinstance(machinestate, str):
ret = MACHINE_STATES.get(machinestate, UNKNOWN_MACHINE_STATE)
else:
ret = UNKNOWN_MACHINE_STATE
return salt.utils.data.decode(ret, preserve_tuples=True)
def machine_get_machinestate_tuple(machinedict):
return vb_machinestate_to_tuple(machinedict.get("state"))
def machine_get_machinestate_str(machinedict):
return vb_machinestate_to_str(machinedict.get("state"))
def vb_machine_exists(name):
"""
Checks in with the hypervisor to see if the machine with the given name is known
@param name:
@type name:
@return:
@rtype:
"""
try:
vbox = vb_get_box()
vbox.findMachine(name)
return True
except Exception as e: # pylint: disable=broad-except
if isinstance(e.message, str):
message = e.message
elif hasattr(e, "msg") and isinstance(getattr(e, "msg"), str):
message = getattr(e, "msg")
else:
message = ""
if 0 > message.find("Could not find a registered machine named"):
log.error(message)
return False
def vb_get_machine(name, **kwargs):
"""
Attempts to fetch a machine from Virtualbox and convert it to a dict
@param name: The unique name of the machine
@type name:
@param kwargs: To be passed to vb_xpcom_to_attribute_dict
@type kwargs:
@return:
@rtype: dict
"""
vbox = vb_get_box()
machine = vbox.findMachine(name)
return vb_xpcom_to_attribute_dict(machine, "IMachine", **kwargs)