MFD Hyperv

Module for handling functionalities of HyperV hypervisor.

Usage

from mfd_hyperv.base import HyperV
from mfd_connect import LocalConnection

conn = LocalConnection()
hyperv = HyperV(connection=conn)
hyperv.hw_qos.delete_scheduler_queue("vSwitch00", "5")

Implemented methods

Hardware QoS Offload functionality:

• create_scheduler_queue(vswitch_name: str, sq_id: str, sq_name: str, limit: bool, tx_max: str, tx_reserve: str, rx_max: str) -> None - create scheduler queue
• update_scheduler_queue(vswitch_name: str, limit: str, tx_max: str, tx_reserve: str, rx_max: str, sq_id: str) -> None - update existing scheduler queue
• delete_scheduler_queue(vswitch_name: str, sq_id: str) -> None - delete existing scheduler queue
• get_qos_config(vswitch_name: str) -> Dict[str, Union[str, bool]] - get current QoS configuration for the vSwitch
• set_qos_config(vswitch_name: str, hw_caps: bool, hw_reserv: bool, sw_reserv: bool, flags: str) -> None - set QoS configuration on the vSwitch
• disassociate_scheduler_queues_with_vport(vswitch_name: str, vport: int) -> None - disassociate scheduler queues with virtual port
• list_scheduler_queues_with_vport(vswitch_name: str, vport: str) -> List[str] - list scheduler queues associated with virtual port
• associate_scheduler_queues_with_vport(vswitch_name: str, vport: str, sq_id: str, lid: int, lname: str) -> None - associate scheduler queues with virtual port
• get_vmswitch_port_name(switch_friendly_name: str, vm_name: str) -> str - get vmswitch port name
• is_scheduler_queues_created(vswitch_name: str, sq_id: int, sq_name: str, tx_max: str) -> bool - check if scheduler queues was properly created
• list_queue(vswitch_name: str) -> str - list queue from vSwitch
• get_queue_all_info(vswitch_name: str) -> str - get queue info for flag all
• get_queue_offload_info(vswitch_name: str, sq_id: int) -> str - get queue info for flag offload and indicated queue

Hypervisor:

• is_hyperv_enabled() -> bool - check status of Hyper-V service on the machine
• create_vm(vm_params: VMParams, owner: Optional[NetworkAdapterOwner] = None, hyperv=None, connection_timeout=3600, dynamic_mng_ip=False) -> VM - create Hyper-V Virtual Machine (VM). Passing "hyperv" object to created VM allows for using VM object methods.
• remove_vm(vm_name: str = "*") -> None - remove VM with given name or all VMs
• start_vm(vm_name: str = "*") -> None - start VM with given name or all VMs
• stop_vm(vm_name: str = "*", turnoff: bool = False) -> None - stop VM with given name or all VMs. Allows to choose between graceful shutdown and forcible turnoff.
• _vm_connectivity_test(ip_address: IPAddress) -> bool - check ping connectivity with provided IP address
• wait_vm_functional(vm_name: str, vm_mng_ip: IPAddress, timeout: int = 300) -> None - wait for VM status "Running" and successful ping response
• wait_vm_stopped(self, vm_name: str, timeout: int = 300) -> None - wait for VM status "Off"
• get_vm_state(vm_name: str) -> str - get current VM state
• restart_vm(vm_name: str = "*") -> None - restart VM with given name or all VMs
• clear_vm_locations() -> None - check paths all paths where VM files could be stored and delete all remaining files
• get_vm_attributes(vm_name: str) -> Dict[str, str] - get VM attributes from host
• get_vm_processor_attributes(vm_name: str) -> Dict[str, str] - get processor attributes of given VM
• set_vm_processor_attribute(vm_name: str, attribute: Union[VMProcessorAttributes, str], value: Union[str, int, bool]) -> None - set VM Processor attribute
• _get_disks_free_space() -> Dict[str, Dict[str, str]] - return information such as the amount of free space and the total amount of space for all fixed drives that are not the system partition C
• get_disk_paths_with_enough_space(bytes_required: int) -> str - get disk with free space that exceeds given amount
• copy_vm_image(vm_image: str, dst_location: "Path", src_location: str) -> str - copy VM image from source location to destination location. If available compressed archive file with image will be copied
• _get_file_metadata(file_path) -> Dict[str, str] - get metadata of file. Metadata consists of LastWriteTime and Length (size in bytes) of given file.
• _is_same_metadata(file_1, file_2, max_difference=300) -> bool - check if metadata are the same. LastWriteTime is allowed to differ provided maximum number pof seconds.
• is_latest_image(local_img_path: "Path", fresh_images_path: str) -> bool - check if given image is up-to-date with remote VM location.
• get_vm_template(vm_base_image: str, src_location: str) -> str - get local path to VM image that will serve as a template for differencing disks.
• create_differencing_disk(base_image_path: str, diff_disk_dir_path: str, diff_disk_name: str) -> str - create differencing disk for VM from base image.
• remove_differencing_disk(diff_disk_path: str) -> None - remove differencing disk.
• get_hyperv_vm_ips(file_path: str) -> List[IPAddress] - retrieve vm ip list from file.
• _get_mng_mask() -> int - return Network Mask of management adapter (managementvSwitch).
• get_free_ips(ips, required=5, timeout=600) -> List[str] - get IP addresses that are not taken and can't pi successfully pinged
• format_mac(ip, guest_mac_prefix: str = "52:5a:00") -> str - get MAC address string based on mng IP address.
• _wait_vm_mng_ips(vm_name: str = "*", timeout: int = 3600) -> str - wait for specified VM or all VMs management adapters to receive correct IP address.
• _remove_folder_contents(dir_path) -> None - remove files from specified folder.
• _is_folder_empty(dir_path) -> bool - check if specified folder is empty.
• get_file_size(path: str) -> int - return size in bytes of specified file.

VSwitch manager:

• create_vswitch(interface_names: List[str], vswitch_name: str = vswitch_name_prefix, enable_iov: bool = False, enable_teaming: bool = False, mng: bool = False, interfaces: Optional[List[WindowsNetworkInterface]] = None) -> VSwitch - create vSwitch. Passing interfaces object to created VSwitch allows for using VSwitch object methods.
• _generate_name(vswitch_name: str, enable_teaming: bool) -> str - create unified vswitch name with updated counter
• create_mng_vswitch() -> VSwitch - create management vSwitch. Only object is created when management vSwitch is already present on the machine
• remove_vswitch(interface_name: str) -> None - remove vswitch identified by its 'interface_name'.
• get_vswitch_mapping(self) -> dict[str, str] - Get a list of Hyper-V vSwitches and the adapters they are mapped to. Returns: Dictionary where key are names of vswitches, values are Friendly names of an interfaces connect to (NetAdapterInterfaceDescription field from powershell output)
• get_vswitch_attributes(interface_name: str) -> Dict[str, str] - get vSwitch attributes in form of dictionary.
• set_vswitch_attribute(interface_name: str, attribute: Union[VSwitchAttributes, str], value: Union[str, int, bool]) -> None - set attribute on VSwitch.
• remove_tested_vswitches() -> None - remove all tested vSwitches, doesn't remove management vSwitch.
• is_vswitch_present(interface_name: str) -> bool - check if given virtual switch is present.
• wait_vswitch_present(vswitch_name: str, timeout: int = 60, interval: int = 10) -> None - wait for timeout duration for vSwitch to appear present.
• rename_vswitch(interface_name: str, new_name: str) -> None: - rename vSwitch and check if the change was successful

VMNetworkInterfaceManager manager:

• create_vm_network_interface(vm_name: str, vswitch_name: str | None = None, sriov: bool = False, vmq: bool = True, get_attributes: bool = False, vm: VM | None = None, vswitch: VSwitch | None = None) -> VMNetworkInterface - add network interface to VM.
• remove_vm_interface(vm_interface_name: str, vm_name: str) -> None - remove network interface from VM.
• connect_vm_interface(vm_interface_name: str, vm_name: str, vswitch_name: str) -> None - connect vm adapter to virtual switch.
• disconnect_vm_interface(vm_interface_name: str, vm_name: str) -> None - disconnect VM Network Interface from vswitch.
• clear_vm_interface_attributes_cache(self, vm_name=None) -> None - clear cached vnics attributes information of specified VM.
• set_vm_interface_attribute(vm_interface_name: str, vm_name: str, attribute: Union[VMNetworkInterfaceAttributes, str], value: Union[str, int]) -> None - set attribute on vm adapter.
• get_vm_interface_attributes(vm_interface_name: str, vm_name: str) -> Dict[str, str] - get attributes of VM network interface.
• get_vm_interfaces(vm_name: str) -> List[Dict[str, str]] - return dictionary of VM Network interfaces.
• _generate_name(vm_name) -> str - create unified vn adapter interface name with updated counter
• set_vm_interface_vlan(state, vm_name, interface_name, vlan_type, vlan_id, management_os) -> None - configures the VLAN settings for the traffic through a virtual network adapter.
• set_vm_interface_rdma(vm_name, interface_name, state) -> None - set RDMA on VM nic (enable or disable)
• get_vm_interface_vlan(vm_name, interface_name) -> Dict[str, str] - get VLAN settings for the traffic through a virtual network adapter.
• get_vm_interface_rdma(vm_name, interface_name) -> Dict[str, str] - get RDMA settings for VM network adapter.
• get_adapters_vf_datapath_active() -> bool - Return Vfdatapathactive status of all VM adapters.
• get_vm_interface_attached_to_vswitch(self, vswitch_name: str) -> str - get the VMNetworkAdapter name that is attached to the vswitch. Parameters: :param vswitch_name: name of vswitch interface Raises: HyperVExecutionException on any Powershell command execution error Returns: name of interfaces attached to the vswitch_name
• get_vlan_id_for_vswitch(self, vswitch_name: str) -> int - get VLAN tagging set for Hyper-V vSwitch. Only access and untagged modes are supported at this point. Parameters: :param vswitch_name: vswitch adapter object Raises: HyperVExecutionException on any Powershell command execution error Returns: vlan number. 0 if untagged

VSwitch:

• interfaces() - interfaces property representing list of interfaces that vswitch is created on.
• interfaces(value) - interfaces property setter
• interfaces_binding() -> None - create bindings between vswitch and network interfaces objects
• get_attributes() -> Dict[str, str] - return vSwitch attributes in form of dictionary.
• set_and_verify_attribute(attribute: Union[VSwitchAttributes, str], value: Union[str, int, bool], sleep_duration: int = 1) -> bool - set specified vswitch attribute to specified value and check if results where applied in the OS.
• remove() - remove vswitch identified by its 'interface_name'
• rename(new_name: str) -> None - rename vswitch with a specific name

OS supported:

• WINDOWS

Issue reporting

If you encounter any bugs or have suggestions for improvements, you're welcome to contribute directly or open an issue here.