pyvss

Manager

This module sends request to the ITS Private Cloud API.

API Reference.

class pyvss.manager.VssManager(tk=None, api_endpoint=None, debug=False, timeout=None, dry_run=False)

Bases: object

Class containing methods to interact with the VSS REST API.

Example:

vss = VssManager(tk='access-token')
vss.whoami()
vss.ping()

If tk is none it will get the token from the VSS_API_TOKEN environment variable.

Example:

vss = VssManager()
vss.whoami()

DELETE = 'DELETE'

GET = 'GET'

OPTIONS = 'OPTIONS'

PATCH = 'PATCH'

POST = 'POST'

PUT = 'PUT'

ack_user_message(m_id)

Acknowledge given user message.

Parameters:

m_id (int) – message id

Returns:

message object

ack_vm_alarm(vm_id, moref, **kwargs)

Acknowledge given Virtual Machine triggered alarm.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• moref – Virtual Machine Alarm managed object reference

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

cancel_retirement_request(request_id: int)

Cancel retirement request.

cancel_scheduled_change_request(request_id)

Cancel scheduled execution of a given change request.

Parameters:

request_id (int) – Change request id

Returns:

request status

clear_vm_alarm(vm_id, moref, **kwargs)

Clear given Virtual Machine alarm.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• moref – Virtual Machine Alarm managed object reference

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

confirm_retirement_request(request_id: int)

Confirm retirement request.

Parameters:

request_id (int) – retirement request id

Returns:

object

consolidate_vm_disks(vm_id, **kwargs)

Submit a Virtual Machine disk consolidation request.

Parameters:

vm_id – virtual machine moref or uuid

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

create_folder(moref, name)

Create logical folder under given managed object reference.

Parameters:

• moref (str) – Parent folder managed object id

• name (str) – New folder name

Returns:

folder request object

create_inventory_file(props=None, filters=None, transfer=False, fmt='json')

Submit a request to generate a full inventory report of your VMs.

The report will be transferred if set to your space at VSKEY-STOR and also be available via download_inventory_result().

Parameters:

• props (list) – properties to include in report. exec get_inventory_properties() to get a full list.

• transfer (bool) – whether to transfer to personal store at vskey-stor

• fmt (str) – report format <json|csv>. default json

• filters (list) – Filters to add in the inventory report. attr:value format.

Returns:

inventory request object

Note

See Inventory Docs for more information

create_user_ssh_key(public_key)

Create a new SSH Public Key entry.

Parameters:

public_key (str) – SSH Public Key string

Returns:

create_user_ssh_key_path(public_key_path)

Create a new SSH Public Key entry from file path.

Parameters:

public_key_path (str) – Full path to SSH Public Key string

Returns:

create_vm(os: str, built: str, client: str, description: str, folder: str, networks: List[Dict], disks: List[int] | List[Dict], scsi: List[str] | List[Dict] | None = None, name: str | None = None, iso: str | None = None, notes: Dict | None = None, usage: str | None = 'Test', cpu: int | Dict | None = 1, memoryGB: int = 1, vss_service: str | None = None, extra_config: List[Dict] | None = None, power_on: bool | None = False, template: bool | None = False, firmware: str | None = None, tpm: bool | None = False, storage_type: str | None = False, retirement: Dict | None = None, **kwargs)

Create single Virtual Machine.

Parameters:

• os (str) – Operating system id.

• built – built process

• client (str) – Client department

• description (str) – VM description

• folder (str) – Target VM folder moref

• networks – list of network adapter objects created based on the network index, then first item in the list is mapped to network adapter 1. If not specified, will be same as source.

Example:

{'network': 'moref', 'type': 'valid_type'}

Parameters:

• disks (list) –

  list of disk sizes in gb or list of disk specification including capacity_gb, backing_mode and backing_sharing.

  Example:

  {"capacity_gb": 100, "backing_mode": "persistent"}
  {"capacity_gb": 500, "backing_mode": "independent_persistent"}
  

• scsi (list) –

  list of scsi controllers types or list of scsi specification including type, bus and sharing.

  Example:

  {"type": "lsilogic", "bus": 0}
  {"type": "paravirtual", "bus": 1}
  

• name (str) – name of the new virtual machine

• iso (str) – ISO image path to be mounted after creation

• notes (dict) – Custom Notes in key value format to store in the Virtual Machine annotation as meta-data.

• usage (str) – virtual machine usage

• cpu (int, dict) –

  vCPU count or count and core per socket configuration

  Example:

  {"count": 4, "cores_per_socket": 2}
  

• memoryGB (int) – Memory size in GB

• vss_service (str or int) – VSS Service definition.

• extra_config (list) – Set VMware guestinfo interface which are available to the VM guest operating system via VMware Tools These properties are stored within the VMX prefixed with “guestinfo.” string. This parameter also can include supported properties available from get_supported_extra_cfg_options().

• power_on (bool) – Power on virtual machine after successful deployment

• template (bool) – Mark resulting vm as template.

• firmware (str) – type of firmware to use. Supported types are available get_supported_firmware_types().

• retirement (dict) – vm retirement payload. Expected either get_retirement_datetime_spec() or get_retirement_timedelta_spec().

• tpm (bool) – add trusted platform module to virtual machine.

• storage_type (str) – type of storage to use. Supported types are available: get_supported_storage_types().

• kwargs – key value arguments

Returns:

new request object

See also

get_os() for os parameter,

get_images() for image, get_folder() for folder, get_networks() for networks, get_vss_services() for vss_service, get_retirement_datetime_spec() or

get_retirement_timedelta_spec() for retirement.

Note

more information about required attributes available in Virtual Machine

create_vm_cd(vm_id, backings=None, **kwargs)

Create CD/DVD drives.

By default it creates a single CD/DVD unit backed by client pass-through.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• backings – either client or iso path or iso image id. I.e [“client”, “iso_id_or_path”]

• backings – list

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

create_vm_custom_spec(vm_id, custom_spec, **kwargs)

Create a custom specification for a given virtual machine.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• custom_spec (dict) – OS customization specification. Required if the resulting virtual machine needs to be reconfigure upon first boot. The current version of VMware Tools must be installed on the virtual machine or template to customize the guest operating system during cloning or deployment.

• kwargs –

Returns:

Note

Virtual machine must be powered on and VMware Tools must be installed.

See also

get_custom_spec() for customization specification.

create_vm_disk(vm_id, disks, **kwargs)

Create virtual machine disks with a given specs.

For every value in GB in the list a virtual disk will be assigned.

Example:

disks = [40, 100, 50]

or

disks = [
  {"capacity_gb": 40},
  {
   "capacity_gb": 100,
   "backing_mode": "independent_persistent",
   "backing_vmdk":
   "[vssUser-xfers] vskey/<user>/FOLDER/disk-0.vmdk"
   },
]

vss.create_vm_disk(vm_id, disks=disks)

Parameters:

• vm_id (str) – virtual machine moref or uuid

• disks (list) – a list of disk capacities in GB or disk specs.

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

create_vm_extra_cfg_options(vm_id, options)

Create VM extra configuration settings.

Extra configuration options are either guestinfo.* or allowed options.

Extra config guestinfo.* options can be queried from the Guest Operating system using VMware Tools:

Example:

vmtoolsd --cmd "info-get guestinfo.<option>"

Parameters:

• vm_id (str) – virtual machine moref or uuid

• options – list of dictionaries with key-value options to create.

Type:

list

Returns:

object

create_vm_floppy(vm_id, backings=None, **kwargs)

Create Floppy drives.

By default, it creates a single CD/DVD unit backed by client pass-through.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• backings – either client or image path or image id. I.e [“client”, “image_id_or_path”]

• backings – list

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

create_vm_from_clone(source: str, description: str, name: str | None = None, os: str | None = None, client: str | None = None, folder: str | None = None, networks: List[Dict] | None = None, scsi: List[str] | List[Dict] | None = None, disks: List[int] | List[Dict] | None = None, notes: Dict | None = None, usage: str | None = None, cpu: int | Dict | None = None, memoryGB: int | None = None, custom_spec: Dict | None = None, vss_service: str | None = None, extra_config: List[Dict] | None = None, firmware: str | None = None, power_on: bool | None = False, template: bool | None = False, tpm: bool | None = False, storage_type: str | None = None, source_snap_id: int | None = None, retirement: Dict | None = None, **kwargs)

Deploy virtual machine by cloning from any given source.

Parameters:

• source (str) – Source virtual machine moref or uuid

• description (str) – Brief description of what the virtual machine will host

• name (str) – Virtual machine name. If not specified, will create a new name based on source

• os (str) – Operating system id. If not specified, will be same as source.

• client (str) – client department. If not specified, will be same as source.

• folder (str) – Target folder moref. This is the logical folder storing the new virtual machine. If not specified, will be same as source.

• networks – list of network adapter objects created based on the network index, then first item in the list is mapped to network adapter 1. If not specified, will be same as source.

Example:

{'network': 'moref', 'type': 'valid_type'}

Parameters:

• disks (list) –

  list of disk sizes in gb or list of disk specification including capacity_gb, backing_mode and backing_sharing.

  Example:

  {"capacity_gb": 100, "backing_mode": "persistent"}
  {"capacity_gb": 500, "backing_mode": "independent_persistent"}
  

• scsi (list) –

  list of scsi controllers types or list of scsi specification including type, bus and sharing.

  Example:

  {"type": "lsilogic", "bus": 0}
  {"type": "paravirtual", "bus": 1}
  

• notes (dict) – Custom Notes in key value format to store in the Virtual Machine annotation as meta-data.

• usage (str) – virtual machine usage. If not specified, will be same as source.

• cpu (int, dict) –

  vCPU count or count and core per socket configuration

  Example:

  {"count": 4, "cores_per_socket": 2}
  

  ..note: When setting this parameter

  refer to https://kb.vmware.com/s/article/1010184 for further details.

• memoryGB (int) – Memory size in GB. If not specified, will be same as source.

• custom_spec (dict) – OS customization specification. Required if the resulting virtual machine needs to be reconfigure upon first boot. The current version of VMware Tools must be installed on the virtual machine or template to customize the guest operating system during cloning or deployment.

• vss_service (str or int) – VSS Service definition.

• extra_config (list) – Set VMware guestinfo interface which are available to the VM guest operating system via VMware Tools These properties are stored within the VMX prefixed with “guestinfo.” string. This parameter also can include supported properties available from get_supported_extra_cfg_options().

• power_on (bool) – Power on virtual machine after successful deployment

• template (bool) – Mark resulting vm as template.

• firmware (str) – type of firmware to use. Supported types are available get_supported_firmware_types().

• tpm (bool) – add trusted platform module to virtual machine.

• source_snap_id (int) – source virtual machine snapshot identifier. get_vm_snapshots(). If set, clone will be a result from the given snapshot id state.

• retirement (dict) – vm retirement payload. Expected either get_retirement_datetime_spec() or get_retirement_timedelta_spec().

• storage_type (str) – type of storage to use. Supported types are available: get_supported_storage_types().

• kwargs –

Returns:

new request object

See also

get_templates() for virtual machine templates get_os() for os parameter, get_images() for image, get_folder() for folder, get_networks() for networks, get_custom_spec() for customization specification, get_vss_services() for vss_service.

Note

more information about required attributes available in Virtual Machine

create_vm_from_image(os: str, image: str, client: str, description: str, folder: str, networks: List[Dict], disks: List[int] | List[Dict], scsi: List[str] | List[Dict] | None = None, notes: Dict | None = None, usage: str = 'Test', name: str | None = None, cpu: int | Dict | None = 1, memoryGB: int | None = 1, vss_service: str | None = None, extra_config: List[Dict] | None = None, power_on: bool | None = False, template: bool | None = False, firmware: str | None = None, tpm: bool | None = False, retirement: Dict | None = None, storage_type: str | None = None, **kwargs)

Create a new Virtual Machine from OVA or OVF.

Parameters:

• os (str) – Operating system id.

• image (str) – OVA/OVF filename

• client (str) – Client department

• description (str) – Brief description of what the virtual machine will host.

• folder (str) – Target folder moref. This is the logical folder storing the new virtual machine.

• networks – list of network adapter objects created based on the network index, then first item in the list is mapped to network adapter 1. If not specified, will be same as source.

Example:

{'network': 'moref', 'type': 'valid_type'}

Parameters:

• disks (list) –

  list of disk sizes in gb or list of disk specification including capacity_gb, backing_mode and backing_sharing.

  Example:

  {"capacity_gb": 100, "backing_mode": "persistent"}
  {"capacity_gb": 500, "backing_mode": "independent_persistent"}
  

• scsi (list) –

  list of scsi controllers types or list of scsi specification including type, bus and sharing.

  Example:

  {"type": "lsilogic", "bus": 0}
  {"type": "paravirtual", "bus": 1}
  

• notes (dict) – Custom Notes in key value format to store in the Virtual Machine annotation as meta-data.

• usage (str) – virtual machine usage. Defaults to Test

• name (str) – Virtual Machine name. If not set, will be generated dynamically by the API

• cpu (int, dict) –

  vCPU count or count and core per socket configuration

  Example:

  {"count": 4, "cores_per_socket": 2}
  

  ..note: When setting this parameter

  refer to https://kb.vmware.com/s/article/1010184 for further details.

• memoryGB (int) – Memory size in GB. Defaults to 1GB

• vss_service (str or int) – VSS Service definition.

• extra_config (list) – Set VMware guestinfo interface which are available to the VM guest operating system via VMware Tools These properties are stored within the VMX prefixed with “guestinfo.” string. This parameter also can include supported properties available from get_supported_extra_cfg_options().

• power_on (bool) – Power on virtual machine after successful deployment

• template (bool) – Mark resulting vm as template.

• firmware (str) – type of firmware to use. Supported types are available get_supported_firmware_types().

• tpm (bool) – add trusted platform module to virtual machine.

• retirement (dict) – vm retirement payload. Expected either get_retirement_datetime_spec() or get_retirement_timedelta_spec().

• storage_type (str) – type of storage to use. Supported types are available: get_supported_storage_types().

• kwargs –

Returns:

new request object

See also

get_os() for os parameter, get_images() for image, get_folder() for folder, get_networks() for networks, get_vss_services() for vss_service.

Note

more information about required attributes available in Virtual Machine

create_vm_gpu(vm_id: str, profile: str, **kwargs)

Create GPU on VM.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• profile – vGPU profile to use. Supported profiles are available here get_supported_gpu_types() or through get_vm_host_gpu_profiles() for existing bound profiles.

Returns:

change request object

create_vm_nic(vm_id, networks, **kwargs)

Create Virtual Machine NICs.

For every network in the list a network adapter number will be assigned.

Example:

networks = [
    {'network': 'dvmoref-01'},
    {'network': 'dvmoref-02', 'type': 'vmxnet3'}
]

vss.create_vm_nic(vm_id, networks=networks)

Parameters:

• vm_id (str) – virtual machine moref or uuid

• networks (list) – list of network adapter objects. For example: {‘network’: ‘moref’, ‘type’: ‘valid_type’}

Returns:

change request object

Note

For more information about network interface types, refer to get_supported_nic_types().

Note

If type is not found in network interface object, the default value will be used.

Note

If duplicated networks are included, the API will ignore them since no VM is to have two adapters on the same network.

create_vm_scsi_device(vm_id, devices, **kwargs)

Create Virtual Machine SCSI controllers given specs.

For every item in the devices list, a new SCSI controller will be created matching the provided type.

Example:

devices = ['paravirtual', 'lsilogic']

or

devices = [
    {"type": "lsilogic"},
    {
     "type": "paravirtual", "sharing":
     "virtualSharing"
    }
]

vss.create_vm_scsi_device(vm_id, devices=devices)

Parameters:

• vm_id (str) – virtual machine moref or uuid

• devices (list) – SCSI bus number

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

Note

For more information about SCSI controller types, refer to get_supported_scsi_controllers().

Note

For more information about SCSI controller sharing, refer to get_supported_scsi_sharing().

create_vm_snapshot(vm_id: str, desc: str, date_time: str | None = None, valid: int | None = 24, consolidate: bool | None = True, with_memory: bool | None = True)

Create a Virtual Machine snapshot on a given date and time.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• desc (str) – A brief description of the snapshot.

• date_time – Timestamp with the following format %Y-%m-%d %H:%M. If date is in the past, the change request will be processed right away, otherwise it will wait. If date_time is None, the value is set to now.

• valid (int) – Number of hours (max 72) the snapshot will live

• consolidate (bool) – Whether to consolidate when snapshot has been removed

• with_memory (bool) – whether to include memory in snapshot

Returns:

snapshot request object

create_vm_tpm(vm_id)

Create VM vTPM.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

create_vms(count: int, name: str, os: str, built: str, client: str, description: str, folder: str, networks: List[Dict], disks: List[int] | List[Dict], scsi: List[str] | List[Dict] | None = None, iso: str | None = None, notes: Dict | None = None, usage: str = 'Test', cpu: int | Dict | None = 1, memoryGB: int = 1, vss_service: str | None = None, extra_config: List[Dict] | None = None, power_on: bool | None = False, template: bool | None = False, firmware: str | None = None, tpm: bool | None = False, storage_type: str | None = False, retirement: Dict | None = None, **kwargs)

Create multiple Virtual Machines.

Names are generated by appending name_number.

Parameters:

• count (int) – number of virtual machines to deploy

• name (str) – name of the new virtual machines

• os (str) – Operating system id.

• built – built process

• client (str) – Client department

• description (str) – Brief description of what the virtual machine will host.

• folder (str) – Target folder moref. This is the logical folder storing the new virtual machine.

• networks – list of network adapter objects created based on the network index, then first item in the list is mapped to network adapter 1. If not specified, will be same as source.

Example:

{'network': 'moref', 'type': 'valid_type'}

Parameters:

• disks (list) –

  list of disk sizes in gb or list of disk specification including capacity_gb, backing_mode and backing_sharing.

  Example:

  {"capacity_gb": 100, "backing_mode": "persistent"}
  {"capacity_gb": 500, "backing_mode": "independent_persistent"}
  

• scsi (list) –

  list of scsi controllers types or list of scsi specification including type, bus and sharing.

  Example:

  {"type": "lsilogic", "bus": 0}
  {"type": "paravirtual", "bus": 1}
  

• iso (str) – ISO image path to be mounted after creation

• notes (dict) – Custom Notes in key value format to store in the Virtual Machine annotation as meta-data.

• usage (str) – virtual machine usage

• cpu (int, dict) –

  vCPU count or count and core per socket configuration

  Example:

  {"count": 4, "cores_per_socket": 2}
  

  ..note: When setting this parameter

  refer to https://kb.vmware.com/s/article/1010184 for further details.

• memoryGB (int) – Memory size in GB. Defaults to 1GB

• vss_service (str or int) – VSS Service definition.

• extra_config (list) – Set VMware guestinfo interface which are available to the VM guest operating system via VMware Tools These properties are stored within the VMX prefixed with “guestinfo.” string. This parameter also can include supported properties available from get_supported_extra_cfg_options().

• power_on (bool) – Power on virtual machine after successful deployment

• template (bool) – Mark resulting vm as template.

• firmware (str) – type of firmware to use. Supported types are available get_supported_firmware_types().

• tpm (bool) – add trusted platform module to virtual machine.

• retirement (dict) – vm retirement payload. Expected either get_retirement_datetime_spec() or get_retirement_timedelta_spec().

• storage_type (str) – type of storage to use. Supported types are available: get_supported_storage_types().

• kwargs –

Returns:

new request object

See also

get_os() for os parameter, get_images() for image, get_folder() for folder, get_networks() for networks, get_vss_services() for vss_service..

Note

more information about required attributes available in Virtual Machine

create_vms_from_clone(source: str, description: str, count: int = 1, name: str | None = None, os: str | None = None, client: str | None = None, folder: str | None = None, networks: List[Dict] | None = None, scsi: List[str] | List[Dict] | None = None, disks: List[int] | List[Dict] | None = None, notes: Dict | None = None, usage: str | None = None, cpu: int | Dict | None = None, memoryGB: int | None = None, custom_spec: Dict | None = None, vss_service: str | None = None, extra_config: List[Dict] | None = None, power_on: bool | None = False, template: bool | None = False, firmware: str | None = None, tpm: bool | None = False, storage_type: str | None = False, source_snap_id: int | None = None, retirement: Dict | None = None, **kwargs)

Deploy multiple or a single VM from a source VM.

Useful when you need to deploy multiple virtual machine instances from a single source. Not recommended when using custom_spec for guest OS customization specification.

Use create_vm_from_clone() in a loop for deploying multiple virtual machines with different custom_spec.

Parameters:

• source – Source virtual machine moref or uuid (powered off)

• description (str) – Brief description of what the virtual machine will host

• count – Number or virtual machines to deploy. Defaults to 1.

• name (str) – Virtual machine name. If not specified, will create all new virtual machines based on source VM name appending the number of item.

• os (str) – Operating system id. If not specified, will be same as source.

• client (str) – client department. If not specified, will be same as source.

• folder (str) – Target folder moref. This is the logical folder storing the new virtual machine. If not specified, will be same as source.

• networks – list of network adapter objects created based on the network index, then first item in the list is mapped to network adapter 1. If not specified, will be same as source.

Example:

{'network': 'moref', 'type': 'valid_type'}

Parameters:

• disks (list) –

  list of disk sizes in gb or list of disk specification including capacity_gb, backing_mode and backing_sharing.

  Example:

  {"capacity_gb": 100, "backing_mode": "persistent"}
  {"capacity_gb": 500, "backing_mode": "independent_persistent"}
  

• scsi (list) –

  list of scsi controllers types or list of scsi specification including type, bus and sharing.

  Example:

  {"type": "lsilogic", "bus": 0}
  {"type": "paravirtual", "bus": 1}
  

• notes (dict) – Custom Notes in key value format to store in the Virtual Machine annotation as meta-data.

• usage (str) – virtual machine usage. If not specified, will be same as source.

• cpu (int, dict) –

  vCPU count or count and core per socket configuration

  Example:

  {"count": 4, "cores_per_socket": 2}
  

  ..note: When setting this parameter

  refer to https://kb.vmware.com/s/article/1010184 for further details.

• memoryGB (int) – Memory size in GB. If not specified, will be same as source.

• custom_spec (dict) – OS customization specification. Required if the resulting virtual machine needs to be reconfigure upon first boot. The current version of VMware Tools and Perl must be installed on the virtual machine or template to customize the guest operating system during cloning or deployment.

• vss_service (str or int) – VSS Service definition.

• extra_config (list) – Set VMware guestinfo interface which are available to the VM guest operating system via VMware Tools These properties are stored within the VMX prefixed with “guestinfo.” string. This parameter also can include supported properties available from get_supported_extra_cfg_options().

• power_on (bool) – Power on virtual machine after successful deployment

• template (bool) – Mark resulting vm as template.

• firmware (str) – type of firmware to use. Supported types are available get_supported_firmware_types().

• tpm (bool) – add trusted platform module to virtual machine.

• source_snap_id (int) – source virtual machine snapshot identifier. get_vm_snapshots(). If set, clone will be a result from the given snapshot id state.

• retirement (dict) – vm retirement payload. Expected either get_retirement_datetime_spec() or get_retirement_timedelta_spec().

• storage_type (str) – type of storage to use. Supported types are available: get_supported_storage_types().

• kwargs –

Returns:

new request object

See also

get_vms() for virtual machine get_os() for os parameter, get_images() for image, get_folder() for folder, get_networks() for networks, get_custom_spec() for customization specification, get_vss_services() for vss_service.

Note

more information about required attributes available in Virtual Machine

delete_folder(moref)

Delete virtual machine folder.

Parameters:

moref (str) – Parent folder managed object id

Returns:

folder request object

delete_template(vm_id)

Decommission given Virtual Machine Template.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

delete_user_ssh_key(key_id)

Delete given SSH Key id.

Parameters:

key_id (int) – SSH Key id to delete

Returns:

dict with request status

delete_user_token(token_id)

Delete token id.

Parameters:

token_id (int) – Token id to delete

Returns:

dict with request status

delete_vm(vm_id, force=False, prune=False)

Decommission given Virtual Machine.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• force (bool) – Force deletion if vm is on

• prune (bool) – Completely delete vm. Skip Trash folder.

Returns:

change request object

delete_vm_disk(vm_id, unit, **kwargs)

Delete given Virtual Machine disk unit.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – unit to delete

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

delete_vm_disk_notes(vm_id, unit)

Delete vm disk notes.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – unit to update

Returns:

delete_vm_disks(vm_id, units, **kwargs)

Delete given Virtual Machine disk units.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• units (list) – disk units to delete

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

delete_vm_extra_cfg_option(vm_id, option)

Delete VM extra configuration key.

Extra configuration options are either guestinfo.* or allowed options.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• option – single option key to delete

Type:

str

Returns:

object

delete_vm_extra_cfg_options(vm_id, options)

Delete VM extra configuration keys using the guestinfo.* prefix.

Parameters:

• vm_id (str) – Virtual Machine moref or uuid

• options – list of keys to delete

Type:

list

Returns:

object

delete_vm_floppies(vm_id, units, **kwargs)

Delete given Virtual Machine floppy units.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• units (list) – floppy units to delete

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

delete_vm_gpu(vm_id: str, **kwargs)

Delete vm gpu device.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

delete_vm_nic(vm_id, unit, **kwargs)

Delete Virtual Machine NIC unit.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – Network interface card number

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

delete_vm_nics(vm_id, units, **kwargs)

Delete Virtual Machine NIC units.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• units (list) – Network interface card numbers

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

delete_vm_scsi_device(vm_id, bus, **kwargs)

Delete given Virtual Machine SCSI controller.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• bus (int) – bus number

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

delete_vm_scsi_devices(vm_id, buses, **kwargs)

Delete given Virtual Machine SCSI controller units.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• buses (list) – disk units to delete

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

delete_vm_snapshot(vm_id, snapshot)

Delete given Virtual Machine snapshot.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• snapshot (int) – Snapshot Id

Returns:

snapshot request object

delete_vm_tpm(vm_id)

Delete VM vTPM.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

delete_vm_vss_ha_group(vm_id)

Remove VM from availability group.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

obj

delete_vm_vss_preference(vm_id, preference, **kwargs)

Disable virtual machine vss option by name.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• preference (str) – Vss pref name

Returns:

dict

deploy_vm_from_clib_item(item_id: str, os: str, client: str, description: str, folder: str, networks: List[Dict], disks: List[int] | List[Dict], scsi: List[str] | List[Dict] | None = None, notes: Dict | None = None, usage: str | None = 'Test', name: str | None = None, cpu: int | Dict | None = 1, memory_gb: int | None = 1, vss_service: str | None = None, extra_config: List[Dict] | None = None, additional_parameters: Dict | None = None, power_on: bool | None = False, template: bool | None = False, firmware: str | None = None, tpm: bool | None = False, storage_type: str | None = None, retirement: Dict | None = None, **kwargs)

Deploy virtual machine from content library item.

Parameters:

• item_id (str) – Content library deployable item id. get_content_library_vm_items() or get_content_library_ovf_items() or

• os (str) – Operating system id.

• client (str) – Client department

• description (str) – Brief description of what the virtual machine will host.

• folder (str) – Target folder moref. This is the logical folder storing the new virtual machine.

• networks – list of network adapter objects created based on the network index, then first item in the list is mapped to network adapter 1. If not specified, will be same as source.

Example:

{'network': 'moref', 'type': 'valid_type'}

Parameters:

• disks (list) –

  list of disk sizes in gb or list of disk specification including capacity_gb, backing_mode and backing_sharing.

  Example:

  {"capacity_gb": 100, "backing_mode": "persistent"}
  {"capacity_gb": 500, "backing_mode": "independent_persistent"}
  

• scsi (list) –

  list of scsi controllers types or list of scsi specification including type, bus and sharing.

  Example:

  {"type": "lsilogic", "bus": 0}
  {"type": "paravirtual", "bus": 1}
  

• notes (dict) – Custom Notes in key value format to store in the Virtual Machine annotation as meta-data.

• usage (str) – virtual machine usage. Defaults to Test

• name (str) – Virtual Machine name. If not set, will be generated dynamically by the API

• cpu (int, dict) –

  vCPU count or count and core per socket configuration

  Example:

  {"count": 4, "cores_per_socket": 2}
  

  ..note: When setting this parameter

  refer to https://kb.vmware.com/s/article/1010184 for further details.

• memory_gb (int) – Memory size in GB. Defaults to 1GB

• vss_service (str or int) – VSS Service definition.

• extra_config (list) – Set VMware guestinfo interface which are available to the VM guest operating system via VMware Tools These properties are stored within the VMX prefixed with “guestinfo.” string. This parameter also can include supported properties available from get_supported_extra_cfg_options().

• additional_parameters –

  Set OVF parameters or deployment options. These options are included in the OVF descriptor <ProductSection/> and are mapped based on the ovf:key attribute. Each property can be injected via a dictionary of PropertyParams and DeploymentOptionParams keys. The following example applies for an Ubuntu Cloud image:

  Example:

  {
   "PropertyParams": {
     "hostname": "ubuntu-web",
     "public-keys": "ssh-rsa ...",
     "user-data": "IyEvYmluL3NoCmVjaG8gImhpIHdvcmxkIgo=",
     "password": "RANDOM"
    }
   }
  

• power_on (bool) – Power on virtual machine after successful deployment

• template (bool) – Mark resulting vm as template.

• firmware (str) – type of firmware to use. Supported types are available get_supported_firmware_types().

• tpm (bool) – add trusted platform module to virtual machine.

• storage_type (str) – type of storage to use. Supported types are available: get_supported_storage_types().

• retirement (dict) – vm retirement payload. Expected either get_retirement_datetime_spec() or get_retirement_timedelta_spec().

• kwargs –

Returns:

new request object

See also

get_os() for os parameter, get_images() for image, get_folder() for folder, get_networks() for networks, get_vss_services() for vss_service.

Note

more information about required attributes available in Virtual Machine

deploy_vm_from_template(source_template: str, description: str, name: str | None = None, os: str | None = None, client: str | None = None, folder: str | None = None, networks: List[Dict] | None = None, scsi: List[str] | List[Dict] | None = None, disks: List[int] | List[Dict] | None = None, notes: Dict | None = None, usage: str | None = None, cpu: int | Dict | None = 1, memoryGB: int | None = None, custom_spec: Dict | None = None, vss_service: str | None = None, extra_config: List[Dict] | None = None, power_on: bool | None = False, template: bool | None = False, firmware: str | None = None, tpm: bool | None = False, storage_type: str | None = None, retirement: str | None = None, **kwargs)

Deploy single virtual machine from template.

Recommended approach for multiple virtual machine deployment from template with independent specification, including custom_spec configuration.

Parameters:

• source_template – Source virtual machine template

• description (str) – Brief description of what the virtual machine will host

• name (str) – Virtual machine name. If not specified, will create new virtual machine based on source template name appending the -clone suffix.

• os (str) – Operating system id. If not specified, will be same as source.

• client (str) – client department. If not specified, will be same as source.

• folder (str) – Target folder moref. This is the logical folder storing the new virtual machine. If not specified, will be same as source.

• networks – list of network adapter objects created based on the network index, then first item in the list is mapped to network adapter 1. If not specified, will be same as source.

Example:

{'network': 'moref', 'type': 'valid_type'}

Parameters:

• disks (list) –

  list of disk sizes in gb or list of disk specification including capacity_gb, backing_mode and backing_sharing.

  Example:

  {"capacity_gb": 100, "backing_mode": "persistent"}
  {"capacity_gb": 500, "backing_mode": "independent_persistent"}
  

• scsi (list) –

  list of scsi controllers types or list of scsi specification including type, bus and sharing.

  Example:

  {"type": "lsilogic", "bus": 0}
  {"type": "paravirtual", "bus": 1}
  

• notes (dict) – Custom Notes in key value format to store in the Virtual Machine annotation as meta-data.

• usage (str) – virtual machine usage. If not specified, will be same as source.

• cpu (int, dict) –

  vCPU count or count and core per socket configuration

  Example:

  {"count": 4, "cores_per_socket": 2}
  

  ..note: When setting this parameter

  refer to https://kb.vmware.com/s/article/1010184 for further details.

• memoryGB (int) – Memory size in GB. If not specified, will be same as source.

• custom_spec (dict) – OS customization specification. Required if the resulting virtual machine needs to be reconfigure upon first boot. The current version of VMware Tools and Perl must be installed on the virtual machine or template to customize the guest operating system during cloning or deployment.

• vss_service (str or int) – VSS Service definition.

• extra_config (list) – Set VMware guestinfo interface which are available to the VM guest operating system via VMware Tools These properties are stored within the VMX prefixed with “guestinfo.” string. This parameter also can include supported properties available from get_supported_extra_cfg_options().

• power_on (bool) – Power on virtual machine after successful deployment

• template (bool) – Mark resulting vm as template.

• firmware (str) – type of firmware to use. Supported types are available get_supported_firmware_types().

• tpm (bool) – add trusted platform module to virtual machine.

• retirement (dict) – vm retirement payload. Expected either get_retirement_datetime_spec() or get_retirement_timedelta_spec().

• storage_type (str) – type of storage to use. Supported types are available: get_supported_storage_types().

• kwargs –

Returns:

new request object

See also

get_templates() for virtual machine templates get_os() for os parameter, get_images() for image, get_folder() for folder, get_networks() for networks, get_custom_spec() for customization specification, get_vss_services() for vss_service.

Note

more information about required attributes available in Virtual Machine

deploy_vms_from_template(source_template: str, description: str, count: int = 1, name: str | None = None, os: str | None = None, client: str | None = None, folder: str | None = None, networks: List[Dict] | None = None, disks: List[int] | List[Dict] | None = None, scsi: List[str] | List[Dict] | None = None, notes: Dict | None = None, usage: str | None = None, cpu: int | Dict | None = 1, memoryGB: int | None = None, custom_spec: Dict | None = None, vss_service: str | None = None, extra_config: List[Dict] | None = None, power_on: bool | None = False, template: bool | None = False, firmware: str | None = None, tpm: bool | None = False, storage_type: str | None = None, retirement: Dict | None = None, **kwargs)

Deploy multiple or a single virtual machine from template.

Useful when you need to deploy multiple virtual machine instances from a single source. Not recommended when using custom_spec for guest OS customization specification.

Use deploy_vm_from_template() in a loop for deploying multiple virtual machines with different custom_spec.

Parameters:

• source_template – Source virtual machine template

• description (str) – Brief description of what the virtual machine will host

• count – Number or virtual machines to deploy. Defaults to 1.

• name (str) – Virtual machine name. If not specified, will create all new virtual machines based on source template name appending the number of item.

• os (str) – Operating system id. If not specified, will be same as source.

• client (str) – client department. If not specified, will be same as source.

• folder (str) – Target folder moref. This is the logical folder storing the new virtual machine. If not specified, will be same as source.

• networks – list of network adapter objects created based on the network index, then first item in the list is mapped to network adapter 1. If not specified, will be same as source.

Example:

{'network': 'moref', 'type': 'valid_type'}

Parameters:

• disks (list) –

  list of disk sizes in gb or list of disk specification including capacity_gb, backing_mode and backing_sharing.

  Example:

  {"capacity_gb": 100, "backing_mode": "persistent"}
  {"capacity_gb": 500, "backing_mode": "independent_persistent"}
  

• scsi (list) –

  list of scsi controllers types or list of scsi specification including type, bus and sharing.

  Example:

  {"type": "lsilogic", "bus": 0}
  {"type": "paravirtual", "bus": 1}
  

• notes (dict) – Custom Notes in key value format to store in the Virtual Machine annotation as meta-data.

• usage (str) – virtual machine usage. If not specified, will be same as source.

• cpu (int, dict) –

  vCPU count or count and core per socket configuration

  Example:

  {"count": 4, "cores_per_socket": 2}
  

  ..note: When setting this parameter

  refer to https://kb.vmware.com/s/article/1010184 for further details.

• memoryGB (int) – Memory size in GB. If not specified, will be same as source.

• custom_spec (dict) – OS customization specification. Required if the resulting virtual machine needs to be reconfigure upon first boot. The current version of VMware Tools and Perl must be installed on the virtual machine or template to customize the guest operating system during cloning or deployment.

• vss_service (str or int) – VSS Service definition.

• extra_config (list) – Set VMware guestinfo interface which are available to the VM guest operating system via VMware Tools These properties are stored within the VMX prefixed with “guestinfo.” string. This parameter also can include supported properties available from get_supported_extra_cfg_options().

• power_on (bool) – Power on virtual machine after successful deployment

• template (bool) – Mark resulting vm as template.

• firmware (str) – type of firmware to use. Supported types are available get_supported_firmware_types().

• tpm (bool) – add trusted platform module to virtual machine.

• retirement (dict) – vm retirement payload. Expected either get_retirement_datetime_spec() or get_retirement_timedelta_spec().

• storage_type (str) – type of storage to use. Supported types are available: get_supported_storage_types().

• kwargs –

Returns:

new request object

See also

get_templates() for virtual machine templates get_os() for os parameter, get_images() for image, get_folder() for folder, get_networks() for networks, get_custom_spec() for customization specification, get_vss_services() for vss_service.

Note

more information about required attributes available in Virtual Machine

disable_totp(user: str | None = None, password: str | None = None)

Disable TOTP on account.

Parameters:

• user (str) – Username

• password (str) – Username password

Returns:

disable_totp_confirm(token: str, user: str | None = None, password: str | None = None)

Disable TOTP on account with confirmation token.

Parameters:

• token (str) – Confirmation token

• user (str) – Username

• password (str) – Username password

Returns:

disable_user_message_digest()

Disable Message weekly digest.

Returns:

updated email settings object

disable_user_request_all_notification()

Disable all email notification from requests.

Returns:

updated object

disable_user_request_completion_notification()

Disable notification by completion from requests.

Stop receiving notification if a request (change, new, etc.) has completed successfully.

Returns:

updated email settings object

disable_user_request_error_notification()

Disable notification by errors from requests.

Stop receiving notification if a request (change, new, etc.) has resulted in error.

Returns:

updated email settings object

disable_user_request_submission_notification()

Disable notification by submission from requests.

Stop receiving notification if a request (change, new, etc.) has submitted successfully.

Returns:

updated email settings object

disable_user_token(token_id)

Disable access token id.

Parameters:

token_id (int) – token id to disable

Returns:

status dict

disable_vm_cpu_hot_add(vm_id, **kwargs)

Disable virtual machine CPU hot add.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

disable_vm_cpu_hot_remove(vm_id, **kwargs)

Disable virtual machine CPU hot remove.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

disable_vm_memory_hot_add(vm_id, **kwargs)

Disable virtual machine Memory hot add.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

disable_vm_secure_boot(vm_id, **kwargs)

Enable vm secure boot.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

disable_vm_vbs(vm_id)

Disable VM Virtualization Based Security.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

disable_vm_vmrc_copy_paste(vm_id, **kwargs)

Disable the Copy/Paste between the VMRC client and Windows VM.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

obj

disable_vm_vss_option(vm_id, option_name, **kwargs)

Disable virtual machine vss option by name.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• option_name (str) – Vss option name

Returns:

dict

disable_vss_ubuntu_pro(vm_id, **kwargs)

Disable ubuntu pro for virtual machine.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

dict

disable_vss_vpn(user=None, password=None)

Disable VSS-VPN.

Provided either by function argument or env var: - VSS_API_USER: username - VSS_API_USER_PASS: password

Parameters:

• user (str) – Username

• password (str) – Username password

download_inventory_result(request_id, directory=None)

Download given inventory report.

Parameters:

• request_id – Inventory request id

• directory – Directory to download file

Returns:

full path to written file

Example:

vss.download_inventory_result(request_id=123,
                              directory='~/Downloads')

vss.download_inventory_result(request_id=123)

Note

See Inventory Docs for more information

property dry_run

Get dry_run value.

enable_totp(user: str | None = None, password: str | None = None, method: str | None = 'EMAIL', **kwargs) → Dict

Enable totp on account.

Provided either by function argument or env var: - VSS_API_USER: username - VSS_API_USER_PASS: password

Parameters:

• user (str) – Username

• password (str) – Username password

• method (str) – Method to enable TOTP (SMS, AUTHENTICATOR, EMAIL).

Returns:

enable_user_message_digest()

Enable Message weekly digest.

Returns:

updated email settings object

enable_user_request_all_notification()

Enable all email notification from requests.

Returns:

updated object

enable_user_request_completion_notification()

Enable notification by completion from requests.

Receive notification if a request (change, new, etc.) has completed successfully.

Returns:

updated email settings object

enable_user_request_error_notification()

Enable notification by errors from requests.

Receive notification if a request (change, new, etc.) has resulted in error.

Returns:

updated email settings object

enable_user_request_submission_notification()

Enable notification by submission from requests.

Receive notification if a request (change, new, etc.) has submitted successfully.

Returns:

updated email settings object

enable_vm_cpu_hot_add(vm_id, **kwargs)

Enable virtual machine CPU hot add.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

enable_vm_cpu_hot_remove(vm_id, **kwargs)

Enable virtual machine CPU hot remove.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

enable_vm_memory_hot_add(vm_id, **kwargs)

Enable virtual machine Memory hot add.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

enable_vm_secure_boot(vm_id, **kwargs)

Enable vm secure boot.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• kwargs –

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

enable_vm_vbs(vm_id)

Enable Virtualization Based Security on VM.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

enable_vm_vss_option(vm_id, option_name, **kwargs)

Enable virtual machine vss option by name.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• option_name (str) – Vss option name

Returns:

dict

enable_vss_ubuntu_pro(vm_id, **kwargs)

Enable ubuntu pro for virtual machine.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

dict

enable_vss_vpn(user=None, password=None, otp=None)

Enable VSS-VPN.

Provided either by function argument or env var: - VSS_API_USER: username - VSS_API_USER_PASS: password - VSS_API_USER_OTP: one time password

Parameters:

• user (str) – Username

• password (str) – Username password

• otp (str) – one time password

Returns:

log or VssError

export_vm(vm_id)

Export given Virtual Machine to OVF.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

export request object

Note

Once the export completes, will be transferred to VSKEY-STOR

extend_snapshot_request(request_id, duration)

Extend valid snapshot request to a given number of hours.

Parameters:

• request_id (int) – Snapshot request id

• duration (int) – new duration

Returns:

tuple with status and new snapshot data

get_change_request(request_id)

Get given change request data.

Parameters:

request_id (int) – change request id to get

Returns:

object

get_change_requests(show_all=False, **kwargs)

Get change requests submitted for every change to a VM.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_change_requests(filter='status,eq,ERROR',
                        per_page=100)

get_content_libraries(show_all: bool = False, per_page: int = 5, **kwargs) → List[Dict] | None

Get content libraries.

Parameters:

• show_all (bool) – Whether to show all items or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

Note

keyword arguments implement paging, filtering and sorting. Refer to the official documentation for further details.

get_content_library_iso_items(show_all: bool = False, per_page: int = 5, **kwargs)

Get content library ISO items.

Parameters:

• show_all (bool) – Whether to show all items or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

get_content_library_item(item_id: str) → Dict | None

Get content library item.

Parameters:

item_id (str) – item identifier

:returns object

get_content_library_items(show_all: bool = False, per_page: int = 5, **kwargs) → List[Dict] | None

Get content library items.

Parameters:

• show_all (bool) – Whether to show all items or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

Note

keyword arguments implement paging, filtering and sorting. Refer to the official documentation for further details.

get_content_library_ovf_items(show_all: bool = False, per_page: int = 5, **kwargs)

Get content library virtual machine OVF items.

Parameters:

• show_all (bool) – Whether to show all items or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

get_content_library_vm_items(show_all: bool = False, per_page: int = 5, **kwargs)

Get content library virtual machine template items.

Parameters:

• show_all (bool) – Whether to show all items or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

static get_custom_spec(hostname, domain, interfaces, dns=None)

Generate a customization specification.

Parameters:

• hostname (str) – The network host name of the virtual machine.

• domain (str) – A DNS domain suffix such as eis.utoronto.ca.

• interfaces (list) – A list of interface objects based on get_custom_spec_interface()

• dns (list) – A list of server IP addresses to use for DNS lookup in a Windows guest operating system.

Returns:

static get_custom_spec_interface(dhcp, ip=None, mask=None, gateway=None)

Generate an interface object item for a customization specification.

Customization specification reference get_custom_spec().

Parameters:

• dhcp (bool) – Whether the virtual machine acquires IP config from DHCP. If set to true, parameters ip, subnet dns and gateway will be ignored.

• ip (str) – Specification to obtain a unique IP address for this virtual network adapter.

• mask (str) – Subnet mask for this virtual network adapter.

• gateway (list) – For a virtual network adapter with a static IP address, this data object type contains a list of gateways, in order of preference.

Returns:

get_domain(moref, **kwargs)

Get fault domain data.

Parameters:

moref (str) – managed object id

Returns:

object

get_domains(show_all=False, per_page=250, **kwargs)

Get available Fault Domains.

Parameters:

• show_all (bool) – Whether to show all items

• per_page (int) – how many results per page

Returns:

list of objects

get_export_request(request_id, **kwargs)

Get given export request data.

Parameters:

request_id (int) – export request id to get

Returns:

object

get_export_requests(show_all=False, **kwargs)

Get virtual machine export requests.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_export_requests(filter='status,eq,PROCESSED',
                        per_page=100)

get_floppies(show_all=False, per_page=250, **kwargs)

Get list of global and user floppy images.

Parameters:

• show_all (bool) – Whether to show all floppy images or just the default count

• per_page (int) – how many results per pege

Returns:

list of objects

Note

keyword arguments implement paging, filtering and sorting. Refer to the official documentation for further details. See Floppy Images

Example:

vss.get_floppies(filter='name,like,pvscsi%')

get_folder(moref, **kwargs)

Get logical folder data.

Parameters:

moref (str) – managed object id

Returns:

object

get_folder_children(moref, **kwargs)

Get children folders on given folder.

Parameters:

moref – managed object id

Returns:

list of objects

get_folder_permission(moref)

Get Folder permission list.

Parameters:

moref (str) – Folder managed object id

Returns:

list of key value objects

get_folder_request(request_id, **kwargs)

Get given folder request data.

Parameters:

request_id (int) – folder request id to get

Returns:

object

get_folder_requests(show_all=False, **kwargs)

Get folder requests.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_folder_requests(filter='status,eq,PROCESSED',
                        per_page=100)

get_folders(show_all=False, per_page=250, **kwargs)

Get list of folders available for your account.

Parameters:

• show_all (bool) – Whether to show all items

• per_page (int) – how many results per page

Returns:

list of objects

Note

keyword arguments implement paging, filtering and sorting. Refer to the official documentation for further details. See Folders

Example:

vss.get_folders(filter='path,like,%Parent > MyFolder%',
                sort='name,asc')

vss.get_folders(filter='parent_moref,eq,group-v303',
                sort='label,desc')

get_group(g_id)

Get group info.

Parameters:

g_id (int) – group identifier

Returns:

object

get_group_members(g_id)

Get group members.

Parameters:

g_id – group identifier

Returns:

list

get_groups(show_all=False, **kwargs)

Get groups.

Returns:

list of str

get_image_sync_request(request_id, **kwargs)

Get image synchronization request data.

Parameters:

request_id (int) – image synchronization request id to get

Returns:

object

get_image_sync_requests(show_all=False, **kwargs)

Get image synchronization requests.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_image_sync_requests(filter='status,eq,PROCESSED',
                            per_page=100)

get_images(show_all=False, per_page=250, **kwargs)

Get list of global OVA/OVF images.

Parameters:

• show_all (bool) – Whether to show all OVA/OVF VM images or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

Note

keyword arguments implement paging, filtering and sorting. Refer to the official documentation for further details. See OVA/OVF Images

Example:

vss.get_images(filter='name,like,ub%', sort='name,asc')

vss.get_images(filter='name,like,Win%', sort='path,desc')

get_inventory_properties()

List available properties to create an inventory report.

Returns:

list

get_inventory_request(request_id, **kwargs)

Get given inventory request data.

Parameters:

request_id (int) – inventory request id to get

Returns:

object

get_inventory_requests(show_all=False, **kwargs)

Get inventory requests.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_inventory_requests(filter='transferred,eq,true',
                           per_page=100)

get_isos(show_all=False, per_page=250, **kwargs)

Get list of global and user iso images.

Parameters:

• show_all (bool) – Whether to show all ISO images or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

Note

keyword arguments implement paging, filtering and sorting. Refer to the official documentation for further details. See ISO Images

Example:

vss.get_isos(filter='name,like,ub%', sort='name,asc')

vss.get_isos(filter='name,like,Win%', sort='path,desc')

get_network(moref, **kwargs)

Get details of given network.

Parameters:

• moref – network managed object id

• kwargs – additional parameters

Returns:

list of virtual machine objects

get_network_permission(moref)

Get Network permission list.

Parameters:

moref (str) – Network managed object id

Returns:

list of key value objects

get_networks(show_all=False, per_page=250, **kwargs)

Get list of networks available for your account.

Parameters:

• show_all (bool) – Whether to show all items

• per_page (int) – how many results per page

Returns:

list of objects

Note

keyword arguments implement paging, filtering and sorting. Refer to the official documentation for further details. See Networks

Example:

vss.get_networks(filter='name,like,%PUBLIC%', sort='name,asc')

vss.get_networks(filter='vlan_id,eq,1234', sort='label,desc')

get_new_request(request_id)

Get given new request data.

Parameters:

request_id (int) – new request id to get

Returns:

object

get_new_request_custom_spec(request_id)

Get given new request submitted custom specification.

Parameters:

request_id (int) – new request id to get

Returns:

object

get_new_request_meta_data(request_id)

Get given new request meta data.

Parameters:

request_id (int) – new request id to get

Returns:

object

get_new_request_user_data(request_id, decode=False)

Get given new request submitted user data.

Cloud-init user_data to preconfigure the guest os upon first boot.

Note

Experimental feature and currently tested with Ubuntu Cloud Images and VMware Photon OS. Only supported on OVA/OVF deployments.

Parameters:

• request_id (int) – new request id to get

• decode (bool) – whether to decode user_data

Returns:

object

get_new_requests(show_all=False, **kwargs)

Get new vm deployment requests.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_new_requests(sort='created_on,desc', per_page=100)

get_os(name=None, show_all=True, **kwargs)

Get Virtual Machine supported Guest Operating systems.

Attribute definition: - name: Guest operating system full name. i.e. CentOS 4/5 - id: Guest operating system id. i.e. centosGuest

Parameters:

• show_all (bool) – Whether to show all requests or just the default count

• name – Filter by Guest OS full name

• kwargs – arguments to pass such as: - guest_id: Guest OS identifier - full_name: Guest OS full name.

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Operating Systems

Example:

vss.get_os(sort='created_on,desc', per_page=100)

get_requests(**kwargs)

Get Summary of current requests submitted.

Returns:

list of objects

get_restore_requests(show_all=False, **kwargs)

Get virtual machine restore requests submitted.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Example:

vss.get_restore_requests(filter='status,eq,ERROR',
                         per_page=100)

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

static get_retirement_datetime_spec(date_time: str) → Dict

Get retirement specification for datetime.

Parameters:

date_time (str) – Timestamp with the following format %Y-%m-%d %H:%M.

Returns:

object

get_retirement_request(request_id) → Dict | None

Get given retirement request data.

Parameters:

request_id (int) – retirement request id to get

Returns:

object

get_retirement_requests(show_all=False, **kwargs) → List[Dict] | None

Get retirement requests submitted for every change to a VM.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_retirement_requests(
    filter='status,eq,ERROR',
    per_page=100)

static get_retirement_timedelta_spec(hours: int | None = 0, days: int | None = 0, months: int | None = 0) → Dict

Get retirement specification for timedelta.

Parameters:

• hours (int) – number of hours from now until retirement.

• days (int) – number of days from now until retirement.

• months (int) – number of months from now until retirement.

Returns:

object

get_session_motd()

Get message of the day.

get_snapshot_request(request_id, **kwargs)

Get given snapshot request data.

Parameters:

request_id (int) – snapshot request id to get

Returns:

object

get_snapshot_requests(show_all=False, **kwargs)

Get snapshot requests.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_snapshot_request(filter='status,eq,PROCESSED',
                        per_page=100)

get_supported_build_types(only_type: bool = True) → Dict | List[str]

Get supported VM build types.

Parameters:

only_type – return only types (no description)

Returns:

list

get_supported_disk_backing_modes(only_type=True)

Get supported Virtual Machine Disk Backing modes.

Parameters:

only_type – return only types (no description)

Returns:

list

get_supported_disk_sharing(only_type=True)

Get supported Virtual Machine Disk Sharing modes.

Parameters:

only_type – return only types (no description)

Returns:

list

get_supported_extra_cfg_options(only_option=True)

Get Virtual Machine Extra Config Options supported.

Parameters:

only_option – return only option (no description)

Returns:

list

get_supported_firmware_types(only_type=True)

Get Virtual Machine Firmware types supported.

Parameters:

only_type –

Returns:

get_supported_gpu_types(only_type: bool = True) → Dict | List[str]

Get supported vM GPU types.

get_supported_nic_types(only_type: bool = True) → Dict | List[str]

Get supported Virtual Machine network adapter types.

Parameters:

only_type – return only types (no description)

Returns:

list

get_supported_scsi_controllers(only_type: bool = True)

Get supported Virtual Machine scsi controller types.

Parameters:

only_type – return only types (no description)

Returns:

list

get_supported_scsi_sharing(only_type: bool = True) → List[str | Dict]

Get supported Virtual Machine scsi controller sharing.

Parameters:

only_type – return only types (no description)

Returns:

list

get_supported_storage_types(only_type=True)

Get virtual machine storage types.

get_supported_vmx_types(only_type=True)

Get Virtual Machine virtual hardware versions supported.

Parameters:

only_type – return only types (no description)

Returns:

list

get_supported_vss_options(only_option=True)

Get Virtual Machine VSS Options supported.

Parameters:

only_option – return only option (no description)

Returns:

list

get_supported_vss_prefs(only_option=True)

Get VM VSS Preferences supported.

only_option: return only option (no description) :return:

get_template(vm_id, **kwargs)

Get basic information of given virtual machine template.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

Virtual Machine attributes include:

• storage

• state

• snapshot

• note

• devices

• memory

• cpu

• guest

• folder

Note

more information about required attributes available in Virtual Machine

get_templates(show_all=False, per_page=250, **kwargs)

Get list of virtual machines templates available.

param show_all:

Whether to show all items

type show_all:

bool

param per_page:

how many results per page

type per_page:

int

return:

list of objects

Note

keyword arguments implement paging, filtering and sorting. Refer to the official documentation for further details. See Virtual Machine

• name: filter by name

• folder.path: filter by VM path (folder.path)

Returns:

list of virtual machine template objects

Example:

vss.get_templates(filter='name,like,1%vm%',
                  sort='name,desc')

get_token(user=None, password=None, otp=None)

Generate token based username and password.

Provided either by function argument or env var: - VSS_API_USER: username - VSS_API_USER_PASS: password - VSS_API_USER_OTP: one time password

Parameters:

• user (str) – Username

• password (str) – Username password

• otp (str) – one time password

Returns:

generated token or VssError

get_user_digest_settings()

Get current user digest settings.

Weekly digests are notifications sent summarizing a group of objects. :return: object

get_user_floppies(show_all=False, per_page=250, **kwargs)

Obtain list of user Floppy images in personal store.

If you have uploaded a .flp image to VSKEY-STOR already and is not listed, run sync_user_floppies().

Parameters:

• show_all (bool) – Whether to show all floppy images or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

get_user_groups(show_all=False, **kwargs)

Get current user groups.

Returns:

list of str

get_user_isos(show_all=False, per_page=250, **kwargs)

Obtain list of user ISO images in personal store.

If you have uploaded an iso to VSKEY-STOR already and is not listed, run sync_user_isos().

Parameters:

• show_all (bool) – Whether to show all ISO images or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

get_user_ldap()

Get account ldap info.

Attributes included: - pwd_account_locked_time: shows whether your LDAP account is locked - pwd_change_time: time stamp when you changed your pwd - mail: associated emails - auth_timestamp: last authenticated time stamp

Returns:

object

get_user_message(m_id)

Get given user message.

Parameters:

m_id (int) – message id

Returns:

message object

get_user_message_digest()

Get current user weekly message digest settings.

Returns:

object

get_user_messages(show_all=False, **kwargs)

Get user messages.

Parameters:

show_all (bool) – Whether to show all messages or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See User

Example:

vss.get_user_messages(filter='kind,eq,NOTICE',
                      per_page=10)

get_user_notification_format()

Get notification format.

Returns:

dict

get_user_notification_method()

Get notification method.

Returns:

object

get_user_notification_settings()

Get all notification settings.

Returns:

object

get_user_personal()

Get your account info.

Such as email, phone, username and full name.

Returns:

object

get_user_request_notification_settings()

Get all notification request settings.

Returns:

object

get_user_roles()

Get both request and access roles of current user.

Returns:

object

get_user_ssh_key(key_id)

Get SSH Key id data.

Attributes included: - fingerprint - type - value - comment

Parameters:

key_id (int) – SSHKey id

Returns:

object

get_user_ssh_keys(show_all=False, **kwargs)

Get user ssh-keys.

Parameters:

show_all (bool) – Whether to show all SSH Keys or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details.

Example:

vss.get_user_ssh_keys(filter='type,eq,ssh-rsa',
                      per_page=10)

get_user_status()

Get your account current status.

Attributes included: - active: whether user is active or not - created_on: time stamp when user was created - last_access: most recent access time stamp - updated_on: last time user was updated

Returns:

object

get_user_token(token_id)

Get token id data.

Attributes included: - value - status

Parameters:

token_id (int) – Access token id to manage

Returns:

object

get_user_tokens(show_all=False, **kwargs)

Get user tokens.

Parameters:

show_all (bool) – Whether to show all tokens or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See User

Example:

vss.get_user_tokens(filter='active,eq,true',
                    per_page=10)

get_user_totp()

Get account MFA TOTP status.

Attributes included: - enabled: whether mfa totp is enabled - enabled_onn: time stamp when user enabled mfa - disabled_on: time stamp when user disabled mfa - method: mfa totp token generation method

Returns:

object

get_user_vm_images(show_all=False, per_page=250, **kwargs)

Obtain list of user OVA/OVF VM images in personal store.

If you have uploaded an OVF/OVA image to VSKEY-STOR already and is not listed, run sync_user_vm_images().

Parameters:

• show_all (bool) – Whether to show all vm images or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

get_user_vmdks(show_all=False, per_page=250, **kwargs)

Obtain list of user VMDK files in personal store.

If you have uploaded an iso to VSKEY-STOR already and is not listed, run sync_user_vmdks().

Parameters:

• show_all (bool) – Whether to show all VMDK files or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

get_vm(vm_id, **kwargs)

Get basic information of given virtual machine.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

Virtual Machine attributes include:

• storage

• state

• snapshot

• note

• devices

• memory

• cpu

• guest

• folder

Note

more information about required attributes available in Virtual Machine

get_vm_alarm(vm_id, moref)

Get Virtual Machine triggered Alarm info.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• moref (str) – Alarm managed object id

Returns:

list of objects

get_vm_alarms(vm_id)

Get Virtual Machine triggered Alarms.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_boot(vm_id)

Get given Virtual Machine boot configuration.

Parameters:

vm_id (int) – virtual machine moref or uuid

Returns:

object

Configuration includes:

• enter_bios_setup

• boot_retry_delayMs

• boot_delay_ms

• secure_boot

Note

more information about required attributes available in Virtual Machine Attributes

get_vm_cd(vm_id, cd)

Get Virtual Machine CD/DVD unit information.

• backing

• connected

• controller

• description

• label

Parameters:

• vm_id (str) – virtual machine moref or uuid

• cd (int) – CD/DVD unit number

Returns:

object

get_vm_cds(vm_id)

Get Virtual Machine CD/DVD devices available.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_change_requests(vm_id: str, show_all: bool = False, **kwargs)

Get change requests associated to a virtual machine.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_vm_change_requests(vm_id='vm-123',
                           filter='attribute,eq,name',
                           per_page=100)

get_vm_console(vm_id, auth=None, client='flash')

Produce a one-time URL to Virtual Machine console.

Virtual machine has to be powered on and user must have a valid vCenter session (limitation in the vSphere SOAP API).

Example:

vss.get_vm_console(vm_id, auth=(username, password))

Parameters:

• vm_id (str) – virtual machine moref or uuid

• auth (tuple) – username and password

• client (str) – What client: choose between flash (default) html5 or vmrc.

Returns:

object

get_vm_consolidation(vm_id)

Get current Virtual Machine disks consolidation state.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_controllers(vm_id)

List Virtual machine available controllers.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_cpu(vm_id)

Get VM cpu information.

• cores_per_socket

• cpu

• hot_add

• hot_remove

• quick_stats

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

get_vm_cpu_config(vm_id)

Get VM cpu configuration.

• hot_add

• hot_remove

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

get_vm_disk(vm_id, disk)

Get Virtual Machine disk data.

• capacity_gb

• controller

• description

• label

• shares

Parameters:

• vm_id (str) – virtual machine moref or uuid

• disk (int) – Virtual Machine disk number

Returns:

object

get_vm_disk_backing(vm_id, disk)

Get Virtual Machine disk backing data mode.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• disk (int) – Virtual Machine disk number

Returns:

object

Note

For more information about disk backing modes, refer to get_supported_disk_backing_modes().

get_vm_disk_by_scsi_device(vm_id, bus)

Get Virtual Machine attached devices to given SCSI controller.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• bus (int) – SCSI bus number

Returns:

list of objects

get_vm_disk_capacity(vm_id, unit)

Get virtual machine disk capacity in GB.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – Virtual Machine disk number

Returns:

int

get_vm_disk_notes(vm_id, unit)

Get vm disk note metadata.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – Virtual Machine disk number

Returns:

int

get_vm_disk_scsi(vm_id, disk)

Get Virtual Machine disk SCSI controller data.

• bus_number

• label

• type

Parameters:

• vm_id (str) – virtual machine moref or uuid

• disk (int) – Virtual Machine disk number

Returns:

object

get_vm_disks(vm_id)

Get Virtual Machine available disks.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_domain(vm_id)

Get domain where Virtual Machine is running.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_events(vm_id, hours=1)

Query Virtual Machine events in vCenter.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• hours (int) – Time window to get events from

Returns:

list of events

get_vm_extra_cfg_option(vm_id, option)

Get VM extra configuration (guestinfo.* and allowed options).

Extra config options can be queried from the Guest Operating system using VMware Tools:

Example:

vmtoolsd --cmd "info-get guestinfo.<option>"

Parameters:

• vm_id (str) – virtual machine moref or uuid

• option (str) – Extra config option

Returns:

list of key value objects

get_vm_extra_cfg_options(vm_id)

Get VM extra configuration (guestinfo.* and allowed options).

Extra config options can be queried from the Guest Operating system using VMware Tools:

Example:

vmtoolsd --cmd "info-get guestinfo.<option>"

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of key value objects

get_vm_firmware(vm_id)

Get Virtual Machine firmware.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_floppies(vm_id)

Get Virtual Machine Floppy devices available.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_floppy(vm_id, floppy)

Get Virtual Machine floppy unit.

• backing

• connected

• controller

• description

• label

Parameters:

• vm_id (str) – virtual machine moref or uuid

• floppy (int) – floppy unit number

Returns:

object

get_vm_folder(vm_id)

Get given Virtual Machine parent folder information.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

attributes include:

• full_path

• name

• parent

• reference to folder resource

See also

get_folder() for further information about a given folder

get_vm_gpu(vm_id)

Get VM vGPU.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

get_vm_guest(vm_id)

Get Virtual Machine guest operating system info.

Including hostname, ip addresses, guest state, tools, etc.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_guest_ip(vm_id)

Get Virtual Machine IP and Mac addresses via VMware tools.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_guest_os(vm_id)

Get Virtual Machine Guest Operating System.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_guest_process_id(vm_id, user, pwd, pid)

Get process id info.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• user (str) – Guest Operating Username

• pwd (str) – Guest Operating Username password

• pid (int) – Process Id to query

Returns:

list of objects

Note

Processes running in the guest operating system can be listed using the API via VMware Tools. If VMware Tools has not been installed or is not running, this resource will not work properly.

Note

more information about required attributes available in Virtual Machine Attributes

get_vm_guest_processes(vm_id, user, pwd)

Get virtual machine processes.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• user (str) – Guest Operating Username

• pwd (str) – Guest Operating Username password

Returns:

list of objects

Note

Processes running in the guest operating system can be listed using the API via VMware Tools. If VMware Tools has not been installed or is not running, this resource will not work properly.

Note

more information about required attributes available in Virtual Machine Attributes

get_vm_host_gpu_profiles(vm_id: str)

Get vm host gpu profiles.

get_vm_memory(vm_id)

Get Virtual Machine memory information.

Attributes like: - memory_gb - hot_add - quick_stats: - ballooned - compressed - consumed_overhead, - private - shared - swapped

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_memory_config(vm_id)

Get VM memory configuration.

Attributes included: - hot_add - limit_gb

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

get_vm_name(vm_id)

Get given Virtual Machine full name.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_nic(vm_id, nic)

Get Virtual Machine NIC information.

• connected

• label

• mac_address

• network

• start_connected

• type

Parameters:

• vm_id (str) – virtual machine moref or uuid

• nic (int) – nic number

Returns:

get_vm_nics(vm_id)

Get Virtual Machine NICs information.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_notes(vm_id)

Get Virtual Machine client notes.

Metadata available for users to manage.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of key value notes

get_vm_os(vm_id)

Get Virtual Machine configured Operating System.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_performance_cpu(vm_id)

Query Virtual Machine CPU performance counters.

VM has to be powered On.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

Performance counters include:

• readyAvgPct

• readyMaxPct

• usagePct

get_vm_performance_io(vm_id)

Query Virtual Machine IO performance counters.

VM has to be powered On.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

Performance counters include:

• ioReadIops

• ioWriteIops

• latReadMs

• latWriteMs

get_vm_performance_memory(vm_id)

Query Virtual Machine Memory performance counters.

VM has to be powered On.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

Performance counters include:

• activeMb

• activePct

• balloonMb

• balloonPct

• dateTime

• name

• sharedMb

• sharedPct

• swappedMb

• swappedPct

• usagePct

get_vm_performance_net(vm_id)

Query Virtual Machine Network performance counters.

VM has to be powered On.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

Performance counters include:

• rxErrors

• rxMbps

• txErrors

• txMbps

get_vm_permission(vm_id)

Get VM permission list.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of key value objects

get_vm_restore_points(moref, show_all=False, per_page=250, **kwargs)

Get vm restore points.

Parameters:

• moref (str) – virtual machine moref

• show_all (bool) – Whether to show all ISO images or just the default count

• per_page (int) – how many results per page

Returns:

list of objects

get_vm_restore_requests(vm_id: str, show_all: bool = False, **kwargs)

Get restore requests associated to a virtual machine.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_vm_restore_requests(vm_id='vm-123',
                            filter='attribute,eq,name',
                            per_page=100)

get_vm_retirement_requests(vm_id: str, show_all: bool = False, **kwargs) → List[Dict] | None

Get retirement requests associated to a virtual machine.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_vm_retirement_requests(vm_id='vm-123',
                               per_page=100)

get_vm_scsi_device(vm_id, bus, devices=None)

Get Virtual Machine available SCSI bus.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• bus (int) – SCSI bus number

• devices (bool) – include attached devices

Returns:

object

get_vm_scsi_devices(vm_id)

Get Virtual machine available SCSI controllers.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_snapshot(vm_id, snapshot)

Get given Virtual Machine Snapshot information.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• snapshot (int) – Snapshot Id

Returns:

object

get_vm_snapshots(vm_id)

List existent Virtual Machine snapshots.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_spec(vm_id)

Get given virtual Machine specification.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

Note

useful to create a shell clone

get_vm_state(vm_id)

Get given Virtual Machine state info.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

Virtual Machine attributes include:

• boot_time

• domain

• connection_state

• power_state

get_vm_storage(vm_id)

Get Virtual Machine storage summary.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

dict with:

• uncommitted_gb

• provisioned_gb

• committed_gb

• unshared_gb

get_vm_storage_type(vm_id)

Get storage type where Virtual Machine is running.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_tools(vm_id)

Get VMware Tools status on given Virtual Machine.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

attributes include:

• running_status

• version

• version_status

get_vm_tpm(vm_id)

Get VM vTPM.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

get_vm_usb_devices(vm_id)

Get virtual machine USB devices.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_usb_xhci_devices(vm_id)

Get virtual machine USB devices.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of objects

get_vm_vbs(vm_id)

Get VM Virtualization Based Security.

Parameters:

vm_id (st) – virtual machine moref or uuid

Returns:

get_vm_version(vm_id)

Get Virtual Machine VMX version and upgrade policy status.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_vmrc_copy_paste(vm_id, options=False, **kwargs)

Get Virtual Machine Remote Console Copy Paste Settings.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• options (bool) – show enabled options

Returns:

obj

get_vm_vsphere_link(vm_id, **kwargs)

Produce an URL to the vSphere client on the given VM view.

Example:

vss.get_vm_vsphere_link('vm-123')

Parameters:

• vm_id (str) – virtual machine identifier

• kwargs –

Returns:

object

get_vm_vss_admin(vm_id)

Get Virtual Machine administrator.

This is part of the VSS metadata added to the VM annotation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

dict with phone, name and email of vm admin

get_vm_vss_changelog(vm_id)

Get Virtual Machine change log.

Maximum change log entries are 9.

This is part of the VSS metadata added to the VM annotation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of changelog entries as dict

get_vm_vss_client(vm_id)

Get Virtual Machine Client.

This is part of the VSS metadata added to the VM annotation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

dict

get_vm_vss_description(vm_id)

Get Virtual Machine description.

This is part of the VSS metadata added to the VM annotation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

dict with description

get_vm_vss_ha_group(vm_id)

Get Virtual Machine High Availability Group.

This is part of the VSS metadata added to the VM annotation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

object

get_vm_vss_inform(vm_id)

Get Virtual Machine informational contacts.

This is part of the VSS metadata added to the VM annotation

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of email addresses if any

get_vm_vss_option(vm_id, option_name)

Get virtual machine vss option by name.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• option_name (str) – Vss option name

Returns:

dict

get_vm_vss_options(vm_id)

Get virtual machine vss options.

This is part of the VSS metadata added to the VM annotation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of options

get_vm_vss_preferences(vm_id)

Get virtual machine vss preferences.

This is part of the VSS metadata added to the VM annotation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

list of options

get_vm_vss_requested(vm_id)

Get Virtual Machine requested timestamp.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

timestamp in str or none if unknown

get_vm_vss_service(vm_id)

Obtain virtual machine VSS Service.

This is part of the VSS metadata added to the VM annotation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

obj

get_vm_vss_usage(vm_id)

Get Virtual Machine Usage.

This is part of the VSS metadata added to the VM annotation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

dict

get_vmdk_sync_request(request_id, **kwargs)

Get VMDK file synchronization request data.

Parameters:

request_id (int) – image synchronization request id to get

Returns:

object

get_vmdk_sync_requests(show_all=False, **kwargs)

Get vmdk synchronization requests.

Parameters:

show_all (bool) – Whether to show all requests or just the default count

Returns:

list of objects

Note

keyword arguments implement filters such as paging, filtering and sorting. Refer to the official documentation for further details. See Request

Example:

vss.get_vmdk_sync_requests(filter='status,eq,PROCESSED',
                            per_page=100)

get_vms(show_all=False, per_page=250, **kwargs)

Get list of virtual machines available.

param show_all:

Whether to show all items

type show_all:

bool

param per_page:

how many results per page

type per_page:

int

return:

list of objects

Note

keyword arguments implement paging, filtering and sorting. Refer to the official documentation for further details. See Virtual Machine

• hostname: filter by main dns name

• ip_address: filter by main ip address

• name: filter by name

• path: filter by VM path

Returns:

list of virtual machine objects

Example:

vss.get_vms(filter='hostname,like,host%',
            sort='name,asc')

vss.get_vms(filter='name,like,1%vm%',
            sort='name,desc')

get_vms_by_domain(moref, **kwargs)

Get Virtual Machines on given Fault Domain.

Parameters:

moref (str) – Domain managed object id

Returns:

list of objects

get_vms_by_folder(moref, **kwargs)

Get Virtual Machines on given folder.

Parameters:

moref – managed object id

Returns:

list of objects

get_vms_by_hostname(hostname, **kwargs)

Get Virtual machine by Hostname.

Wildcard symbol is % and can be added at any point in the string to search.

Parameters:

• hostname – string to search

• kwargs –

Returns:

list of objects

Example:

vss.get_vms_by_hostname(hostname='%hostname%')

vss.get_vms_by_hostname(hostname='%hostname.domain%',
                        sort='name,desc')

Note

VMware Tools must be running to query by hostname

get_vms_by_ip(ip_address, **kwargs)

Get Virtual machine by IP address.

Wildcard symbol is % and can be added at any point in the string to search.

Parameters:

• ip_address – string to search

• kwargs –

Returns:

list of objects

Example:

vss.get_vms_by_ip(ip_address='128.100%')

vss.get_vms_by_ip(ip_address='128.100.31%',
                  sort='name,desc')

Note

VMware Tools must be running to query by Ip address

get_vms_by_name(name, **kwargs)

Get Virtual machines by name.

Wildcard symbol is % and can be added at any point in the string to search.

Parameters:

• name – string to search

• kwargs –

Returns:

list of objects

Example:

vss.get_vms_by_name(name='%VMname%')

vss.get_vms_by_name(name='%VMname%', sort='name,desc')

get_vms_by_network(moref, **kwargs)

Get Virtual Machines on given network.

Parameters:

moref – network managed object id

Returns:

list of objects

get_vskey_stor(user: str | None = None, password: str | None = None, access_key: str | None = None, secret_key: str | None = None, s3_endpoint: str | None = None)

Instantiate a Minio Client to interact with VSKEY-STOR.

Parameters:

• user – Username to access remote configuration.

• password – Username password to access remote configuration.

• access_key – Access key for minio service.

• secret_key – Secret key for minio service.

• s3_endpoint – S3 endpoint to interact with minio.

Warning

Min.IO module is required

Example:

# Creating an instance with username and password if
# no env var was set
vss.get_vskey_stor(user='user',
password='P455w00rD')

# Download inventory file
url = vss.vskey_stor.presigned_get_object(
 'ut-vss',
 'inventory/88c4a526-4096-4920-9c07-3d25b6347f70.json'
)
rv = requests.get(url)
Path('88c4a526-4096-4920-9c07-3d25b6347f70.json').write_bytes(rv.content)

# Upload image
vss.vskey_stor.fput_object(
 bucket_name='ut-vss',
 object_name='jammy-server-cloudimg-amd64.ova',
 file_path=os.path.expanduser('~/Downloads/jammy-server-cloudimg-amd64.ova')
 )

static get_vskey_stor_cfg() → Dict

Get vskey-stor configuration.

get_vskey_stor_status(user: str | None = None, password: str | None = None) → Dict

Get vskey-stor status.

get_vss_services(show_all=False, **kwargs)

Get VSS Services.

Filter and sort available Service definition.

Parameters:

• show_all (bool) – Whether to show all services or just the default count

• kwargs –

Returns:

static get_vss_vpn_cfg(vss_vpn_url: str | None = None) → Dict

Get VSS-VPN configuration.

get_vss_vpn_status(user: str | None = None, password: str | None = None) → Dict

Get vss_vpn status.

has_vm_snapshot(vm_id)

Validate if Virtual Machine has snapshots.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

bool

init_vskey_stor(user: str | None = None, password: str | None = None)

Initialize VSS s3 configuration.

init_vss_vpn(vss_vpn_url: str | None = None) → Dict

Initialize VSS VPN.

is_deployable_item(item_id: str) → bool

Verify if item is deployable.

Parameters:

item_id (str) – content library content id

Returns:

bool

is_enabled_vm_vmrc_copy_paste(vm_id)

Check if VM Remote Console Copy Paste Settings are enabled.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

bool

is_powered_off_vm(vm_id)

Check if given Virtual Machine is Off.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

bool

is_powered_on_vm(vm_id)

Check if given Virtual Machine is On.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

bool

is_vm_template(vm_id)

Check if Virtual Machine is marked as template.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

bool

mark_template_as_vm(vm_id, **kwargs)

Mark Template as Virtual Machine.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

mark_vm_as_template(vm_id, **kwargs)

Mark Virtual Machine as template to freeze changes.

Templates cannot be modified nor powered on unless marked as Virtual Machine.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

migrate_vm_vss_ha_group(vm_id)

Migrate VM from availability group from uuid to moref.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

obj

monitor_vss_vpn(user=None, password=None, stamp=None)

Monitor VSS-VPN.

Provided either by function argument or env var: - VSS_API_USER: username - VSS_API_USER_PASS: password

Parameters:

• user (str) – Username

• password (str) – Username password

• stamp (str) – Timestamp in format %Y%m%d%H%M%SZ

mount_vm_tools(vm_id, **kwargs)

Mount official distribution of VMware Tools in Guest OS.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

This method fails if Guest OS is running an unmanaged distribution of VMware Tools.

Note

keyword arguments include schedule to process request on a given date and time

move_folder(moref, new_moref)

Move given folder to new parent.

Parameters:

• moref – folder to move managed object reference

• new_moref – target parent managed object reference to move folder to

Returns:

folder request object

needs_consolidation(vm_id)

Check if Vm requires disk consolidation.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

boolean

static payload_deprecation_warn(payload: Dict) → Dict

Process deprecation warnings.

ping()

Perform Http “Ping” to server.

Replies with request info in form of dictionary.

Returns:

object

power_off_vm(vm_id, **kwargs)

Power Off VM.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

power_on_vm(vm_id, **kwargs)

Power On VM.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

pre_load()

Load in class many data from the API.

process_rv(response)

Process response codes.

Parameters:

response – request.response object

Returns:

dict

reboot_vm(vm_id, **kwargs)

Graceful reboot VM.

This method sends a reboot signal via VMware Tools to the Guest Operating system, thus VMware Tools is required up-to-date and running on VM.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

rename_folder(moref, name, **kwargs)

Rename given logical folder.

Parameters:

• moref – folder managed object id

• name – folder new name

Returns:

folder request object

rename_vm(vm_id, name, **kwargs)

Update Virtual Machine name.

This does not change the VSS prefix YYMM{P|Q|D|T}-VMName.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• name – New virtual machine name. Do not include VSS prefix.

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

request(url, headers=None, params=None, payload=None, method=None, auth=None, dry_run=None)

Request url.

request_totp(user: str | None = None, password: str | None = None)

Request TOTP.

reschedule_change_request(request_id, date_time)

Reschedule change request.

Parameters:

• request_id (int) – Change request id

• date_time (str) – Timestamp with the following format %Y-%m-%d %H:%M. If date is in the past, the change request will be processed right away, otherwise it will wait.

Returns:

request status

reset_vm(vm_id, **kwargs)

Power cycle VM.

Hard reset VM. This method resets a given Virtual Machine. This method is equivalent to power_off_vm and power_on_vm

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

restore_vm(moref, timestamp, **kwargs)

Submit a vm restore request.

Parameters:

• moref (str) – virtual machine moref

• timestamp (str) – restore point timestamp

Returns:

retire_vm(vm_id: str, rtype: str, value: Dict, warning: int | None = None, **kwargs) → Dict | None

Create retirement request for a given VM.

The retirement request allows to set a retirement date for a virtual machine. There are currently two types:

• timedelta: days, months and hours from now until retirement.

• datetime: specific timestamp to retire vm.

The retirement request sends notifications to confirm or cancel if a warning is set and will continue to notify until an action has been performed.

Once the retirement request is confirmed, the request is marked for execution in the retire_on date set by either the timedelta or datetime provided initially. Once executed, a new Vm Change Request will be submitted to decommission the virtual machine

If the retirement request is cancelled, no action is performed.

Parameters:

• vm_id (str) – virtual machine moref or uuid.

• rtype (str) – retirement request type: timedelta or datetime

• value (dict) – payload of the given retirement request type.

• warning (int) – set a notification to cancel or confirm in x given days

Returns:

Example:

warning = 15
time_delta_val = {'days': 4, 'months': 6, 'hours': 0}
r = vss.retire_vm(vm_id='vm-123', rtype='timedelta',
                  value=time_delta_val, warning=warning)

warning = 30
datetime_val = {'datetime': '2021-10-02 08:00'}
r = vss.retire_vm(vm_id='vm-123', rtype='timedelta',
                  value=datetime_val, warning=warning)

retry_change_request(request_id)

Retry given change request.

Only if it has an “ERROR PROCESSED” status.

Parameters:

request_id (int) – new request id to get

Returns:

object

retry_new_request(request_id)

Retry given new request.

Only if it has an “ERROR PROCESSED” status.

Parameters:

request_id (int) – new request id to get

Returns:

object

revert_vm_snapshot(vm_id, snapshot)

Revert to given Virtual Machine snapshot.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• snapshot (int) – Snapshot Id

Returns:

snapshot request object

run_cmd_guest_vm(vm_id, user, pwd, cmd, arg, **kwargs)

Execute command in Guest Operating System.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• user (str) – Guest Operating Username

• pwd (str) – Guest Operating Username password

• cmd (str) – Command to execute

• arg (str) – Command arguments

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

Note

more information about required attributes available in Virtual Machine Attributes

send_confirmation_retirement_request(request_id: int)

Send confirmation retirement request.

Parameters:

request_id (int) – retirement request id

Returns:

object

set_retirement_request_datetime(request_id: int, date_time: str) → Dict | None

Change retirement request to datetime.

Parameters:

• request_id (int) – retirement request id

• date_time (str) – Timestamp with the following format %Y-%m-%d %H:%M.

Returns:

object

set_retirement_request_timedelta(request_id: int, hours: int | None = 0, days: int | None = 0, months: int | None = 0) → Dict | None

Change retirement request to timedelta.

Parameters:

• request_id (int) – retirement request id

• hours (int) – number of hours from now until retirement.

• days (int) – number of days from now until retirement.

• months (int) – number of months from now until retirement.

Returns:

object

set_vm_cpu(vm_id, number, cores_per_socket: int | None = 1, **kwargs)

Update Virtual Machine CPU count.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• number (int) – New vCPU count

• cores_per_socket (int) –

  number of cores per socket.

  ..note: When setting this parameter

  refer to https://kb.vmware.com/s/article/1010184 for further details.

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

set_vm_memory(vm_id, sizeGB, **kwargs)

Update Virtual Machine Memory size.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• sizeGB (int) – New memory size in GB

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

set_vm_memory_reservation(vm_id, size, **kwargs)

Update Virtual Machine Memory size.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• size (int) – memory to reserve in GB

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

set_vm_vss_preference(vm_id, preference, **kwargs)

Enable virtual machine vss preference by name.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• preference (str) – Vss option name

Returns:

dict

shutdown_vm(vm_id, **kwargs)

Graceful shutdown VM.

This method sends a shutdown signal via VMware Tools to the Guest Operating system, thus VMware Tools is required up-to-date and running on VM.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

property status

Return status of the api.

Returns:

dict

suspend_vm(vm_id, **kwargs)

Suspend Virtual Machine.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

sync_user_floppies()

Submit an Floppy Image Synchronization request.

Sync between VSKEY-STOR and API. Verify status with get_image_sync_request(). :return: request object

sync_user_isos()

Submit an ISO Image Synchronization request.

Sync between VSKEY-STOR and API. Verify status with get_image_sync_request().

Returns:

request object

sync_user_vm_images()

Submit an OVA/OVF VM Image Synchronization request.

Sync between VSKEY-STOR and API. Verify status with get_image_sync_request().

Returns:

request object

sync_user_vmdks()

Submit a VMDK File Synchronization request.

Sync between VSKEY-STOR and API. Verify status with get_vmdk_sync_request().

Returns:

request object

unmount_vm_tools(vm_id, **kwargs)

Unmount official distribution of VMware Tools in Guest OS.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

This method fails if VMware Tools ISO is not mounted in guest OS

Note

keyword arguments include schedule to process request on a given date and time

update_user_notification_format(fmt)

Update notifications format.

Parameters:

fmt (str) – notification format (text, html)

Returns:

object

update_user_notification_method(method)

Update notification method.

Parameters:

method (str) – notification format mail|message

Returns:

object

update_user_request_notification_settings(attribute, value)

Update user request notification attribute and value.

Parameters:

• attribute (str) – attribute to update. could be <error|none|completion|submission>

• value (bool) – True or false

Returns:

updated email settings object

update_vm_alarm(vm_id, moref, **kwargs)

Update given Virtual Machine triggered Alarm.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• moref – Virtual Machine Alarm managed object reference

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_boot(vm_id, attribute, value, **kwargs)

Update boot configuration.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• attribute – Either boot bios or boot delay

• value – int or bool

Returns:

change request object

Note

keywords arguments include schedule to process request on a given date and time

update_vm_boot_bios(vm_id, boot_bios, **kwargs)

Update boot to bios configuration.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• boot_bios (bool) – Enable or disable

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_boot_delay(vm_id, boot_delay_ms, **kwargs)

Update boot bios delay configuration.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• boot_delay_ms (int) – boot delay in milliseconds

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_cd(vm_id, unit, iso=None, **kwargs)

Update given CD unit backing to client or ISO.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – CD/DVD unit

• iso (str) – full path to ISO

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_cpu_hot_add(vm_id, hot_add, **kwargs)

Update Virtual Machine CPU hot add configuration.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• hot_add (bool) – Enable or disable hot add

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_cpu_hot_remove(vm_id, hot_remove, **kwargs)

Update Virtual Machine CPU hot remove configuration.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• hot_remove (bool) – Enable or disable hot remove

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_disk_backing_mode(vm_id, unit, mode, **kwargs)

Update given Virtual Machine Disk backing mode.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – disk unit to update

• mode (str) – new bus type

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

Note

For more information about disk backing modes, refer to get_supported_disk_backing_modes().

update_vm_disk_backing_sharing(vm_id, unit, sharing, **kwargs)

Update given Virtual Machine Disk backing mode.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – disk unit to update

• sharing (str) – new sharing type

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

Note

For more information about disk backing modes, refer to get_supported_disk_backing_modes().

update_vm_disk_capacity(vm_id, unit, value_gb, **kwargs)

Update given Virtual Machine disk capacity.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – unit to update

• value_gb (int) – New capacity in GB

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_disk_notes(vm_id, unit, notes, append=True)

Update vm disk notes.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – unit to update

• notes (str) – text to add

• append (bool) – whether to append or replace.

Returns:

update_vm_disk_scsi(vm_id, unit, bus_number, **kwargs)

Update Virtual Machine disk SCSI controller.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• bus_number (int) – New SCSI controller bus number

• unit (int) – Virtual Machine disk number

Returns:

object

update_vm_domain(vm_id, moref, power_on=False, force=False, **kwargs)

Update fault domain of given VM.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• moref (str) – Target domain managed object id

• power_on (bool) – Whether VM will be powered of after migration

• force (bool) – If set to True, VM will be powered off prior migration

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

See also

get_domains() for domain parameter

update_vm_extra_cfg_options(vm_id, options)

Update VM extra configuration.

Extra configuration options are either guestinfo.* or allowed options.

Extra config guestinfo.* options can be queried from the Guest Operating system using VMware Tools:

Example:

vmtoolsd --cmd "info-get guestinfo.<option>"

Parameters:

• vm_id (str) – virtual machine moref or uuid

• options – list of dictionaries with key-value options to update.

Type:

list

Returns:

object

update_vm_firmware(vm_id, firmware)

Update virtual machine firmware.

Parameters:

• vm_id – virtual machine moref or uuid.

• firmware – valid firmware setting.

Returns:

update_vm_floppy(vm_id, unit, image=None, **kwargs)

Update Floppy unit backing to client or image.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• unit (int) – floppy unit

• image (str) – full path to Image

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_folder(vm_id, folder_moId, **kwargs)

Move VM into a given folder.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• folder_moId (str) – folder managed object id

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_gpu(vm_id: str, profile: str, **kwargs)

Update vm gpu profile.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• profile – vGPU profile to use. Supported profiles are available here get_supported_gpu_types() or through get_vm_host_gpu_profiles() for existing bound profiles.

Returns:

change request object

update_vm_memory_hot_add(vm_id, hot_add, **kwargs)

Update Virtual Machine Memory hot add configuration.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• hot_add (bool) – Enable or disable hot add

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_nic_network(vm_id, nic, network, **kwargs)

Update Virtual Machine network on a given nic.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• nic (int) – Network interface card number

• network (str) – new network moref

Returns:

change request object

Note

keywords arguments include schedule to process request on a given date and time

update_vm_nic_state(vm_id, nic, state, **kwargs)

Update Virtual Machine NIC state.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• nic (int) – Network interface card number

• state (str) – new nic state (connect, disconnect)

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_nic_type(vm_id, nic, type, **kwargs)

Update Virtual Machine NIC type.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• nic (int) – Network interface card number

• type (str) – new nic type get_supported_nic_types().

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_notes(vm_id, notes, **kwargs)

Update Virtual Machine client notes.

Notes are stored as key-value metadata items.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• notes (str) – New client custom notes

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_os(vm_id, os, **kwargs)

Update Virtual Machine Operating System configuration.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• os (str) – Operating system id.

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

See also

get_os() for os parameter

update_vm_scsi_device_sharing(vm_id: str, bus: str | int, sharing: str, **kwargs)

Update given Virtual Machine SCSI controller type.

• nosharing

• physicalsharing

• virtualsharing

Parameters:

• vm_id (str) – virtual machine moref or uuid

• bus (int) – bus number to update

• sharing (str) – new bus type

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_scsi_device_type(vm_id, bus, bus_type, **kwargs)

Update given Virtual Machine SCSI controller type.

• buslogic

• paravirtual

• lsilogicsas

• lsilogic

Parameters:

• vm_id (str) – virtual machine moref or uuid

• bus (int) – bus number to update

• bus_type (str) – new bus type

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_secure_boot(vm_id, value, **kwargs)

Update Virtual Machine secure boot configuration.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• value (bool) – Enable or disable hot add

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_state(vm_id, state, **kwargs)

Update given Virtual Machine power state.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• state (str) – Desired state

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_storage_type(vm_id, storage_type, **kwargs)

Update vm storage type.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• storage_type (str) – new storage type

Returns:

Note

keyword arguments include schedule to process request on a given date and time

update_vm_tools(vm_id, action, **kwargs)

Manage VMware tools on Virtual Machiene.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• action (str) – Either mount, unmount or upgrade actions

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_version(vm_id, vmx, **kwargs)

Update virtual machine version (vmx-XX).

Parameters:

• vm_id (str) – virtual machine moref or uuid

• vmx (str) – Virtual machine hardware version (vmx-XX)

Returns:

change request object

update_vm_version_policy(vm_id, policy, **kwargs)

Update virtual machine hardware version upgrade policy.

Policies are: - always: Always run scheduled upgrades. - never: No scheduled upgrades. - onSoftPowerOff: Run scheduled upgrades only on normal

guest OS shutdown.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• policy (str) – Virtual machine hardware upgrade version policy

Returns:

change request object

update_vm_vss_admin(vm_id, name, phone, email, **kwargs)

Update Virtual Machine administrator contact info.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• name (str) – Full name of VM admin

• phone (str) – Valid phone number of VM admin

• email (str) – Valid email address of VM admin

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_vss_client(vm_id, client, **kwargs)

Update virtual machine client metadata.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• client (str) – New VSS client

Returns:

change request

Note

keyword arguments include schedule to process request on a given date and time

update_vm_vss_description(vm_id, description, **kwargs)

Update Virtual Machine description.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• description (str) – New virtual machine description.

Returns:

change request object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_vss_ha_group(vm_id, vms, append=True, **kwargs)

Update High Availability Group.

This is part of the VSS metadata added to the VM annotation

Parameters:

• vm_id (str) – virtual machine moref or uuid

• vms (list) – list of virtual machine Uuids

• append (bool) – whether to replace or append

Returns:

object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_vss_inform(vm_id, emails, append=True, **kwargs)

Update informational contacts.

This is part of the VSS metadata added to the VM annotation

Parameters:

• vm_id (str) – virtual machine moref or uuid

• emails (list) – list of email(s)

• append (bool) – whether to replace or append

Returns:

object

Note

keyword arguments include schedule to process request on a given date and time

update_vm_vss_service(vm_id, service_name_or_id, **kwargs)

Update virtual machine VSS Service.

This is part of the VSS metadata added to the VM annotation.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• service_name_or_id (str or int) – VSS Service name.

Returns:

obj

update_vm_vss_usage(vm_id, usage, **kwargs)

Update virtual machine VSS usage or environment.

Parameters:

• vm_id (str) – virtual machine moref or uuid

• usage (str) – New usage (Prod, Dev, Test or QA)

Returns:

change request

Note

keyword arguments include schedule to process request on a given date and time

update_warning_retirement_request(request_id: int, days: int | None = None)

Update warning for retirement request.

Parameters:

• request_id (int) – retirement request id

• days (int) – number of days to receive a warning

Returns:

object

upgrade_vm_tools(vm_id, **kwargs)

Upgrade official VMware Tools version.

Parameters:

vm_id (str) – virtual machine moref or uuid

Returns:

change request object

Note

This method fails if Guest OS is running an unmanaged distribution of VMware Tools.

Note

keyword arguments include schedule to process request on a given date and time

validate_build_process(n_type) → str

Validate build process.

validate_disks(disks: List[int] | List[Dict]) → List[Dict]

Validate disk payloads.

Supports either a disk spec payload or a simple list of ints.

Example:

disks = [40, 100, 50]

or

disks = [
  {"capacity_gb": 40},
  {
   "capacity_gb": 100,
   "backing_mode": "independent_persistent",
   "backing_vmdk":
   "[vssUser-xfers] vskey/<user>/FOLDER/disk-0.vmdk"
   },
]

validate_network(network)

Validate single network element.

validate_networks(networks)

Validate network list of dictionaries or strings.

static validate_options(item, options)

Validate VSS Options.

validate_scsi(scsi: List[str] | List[Dict]) → List[Dict]

Validate scsi payloads.

Supports either a scsi spec payload or a simple list of str.

Example:

scsi = ["lsilogic", "paravirtual]

or

scsi = [
  {"type": "paravirtual", "bus":  1},
  {"type": "lsilogic", "bus": 0}
]

static validate_scsi_bus(bus: str | int) → int

Validate SCSI bus.

validate_scsi_controllers(devices: List[str] | List[Dict])

Validate scsi payloads.

Supports either a scsi spec payload or a simple list of ints.

Example:

devices = ['paravirtual', 'paravirtual']

or

disks = [
  {"type": "paravirtual"},
  {
   "type": "paravirtual",
   "sharing": "virtualSharing"
  },
]

static validate_usage(usage)

Validate usage.

validate_vm_disk_backing_mode(n_type)

Validate supported disk backing mode.

Parameters:

• n_type – Backing mode

• n_type – str

Returns:

str

validate_vm_disk_backing_sharing(n_type)

Validate supported disk backing sharing.

Parameters:

• n_type – Sharing type

• n_type – str

Returns:

str

validate_vm_firmware(n_type)

Validate supported firmware.

Parameters:

• n_type – firmware type

• n_type – str

Returns:

str

validate_vm_gpu_profile(g_type)

Validate supported vm gpu profiles.

validate_vm_nic_type(n_type)

Validate supported nic type.

Parameters:

n_type (str) – Network interface controller type

Returns:

str

validate_vm_scsi_controller_sharing(sharing)

Validate supported disk scsi controller sharing.

Parameters:

sharing (str) – SCSI controller sharing

Returns:

str

validate_vm_scsi_controller_type(n_type)

Validate supported disk scsi controller type.

Parameters:

n_type (str) – SCSI controller type

Returns:

str

validate_vm_storage_type(n_type)

Validate supported storage type.

validate_vm_vmx_version(n_type)

Validate supported vmx version.

Parameters:

• n_type – Backing mode

• n_type – str

Returns:

str

verify_totp(user=None, password=None, otp=None)

Verify TOTP.

Provided either by function argument or env var: - VSS_API_USER: username - VSS_API_USER_PASS: password - VSS_API_USER_OTP: one time password

Parameters:

• user (str) – Username

• password (str) – Username password

• otp (str) – one time password

wait_for_request(request_url, request_attr, required_status, max_tries=6)

Wait for request to be in any given status.

Parameters:

• request_url (str) – Request URL to check periodically

• request_attr (str) – Attribute to return upon completion

• required_status (str) – Required request status.

• max_tries (int) – Maximum tries to check. Defaults to 6 and every try waits for 10 secs

Returns:

False if failed or the type of attribute requested

whoami()

Retrieve current user summary.

Returns:

object

pyvss.manager.run_main()

Run main function wrapper.

Checks for VSS_API_TOKEN environment variable

Example:

python pyvss/manager.py get_vms 'summary=1&name=pm'

Helper

Helper module for pyvss.

This helper module contains complimentary functions to the pyvss.manager module

class pyvss.helper.HTTPBasicAuth(username, password)

Bases: HTTPBasicAuth

HTTPBasic AUth class.

static make_header(username, password)

Make header for HTTP Auth.

pyvss.helper.compress_encode_string(string_data)

Compresses and encodes in base64 a given string.

Parameters:

string_data (str) – string to compress and encode

Returns:

compressed and encoded string

pyvss.helper.decode_uncompress_string(string_gz_encoded)

Decompress and decodes a given string.

Parameters:

string_gz_encoded (str) – string to decompress and decode

Returns:

string

pyvss.helper.hash_string(string_to_hash)

Hashe string using SHA-512.

Parameters:

string_to_hash (str) – string to hash

Returns:

hashed string

pyvss.helper.is_list_of(lst, o_type=<class 'str'>)

Check what kind of list.

pyvss.helper.normalize_str(string: str | bytes) → str

Normalize string.

Exceptions

Exceptions module for the PyVSS.

exception pyvss.exceptions.VssError(message: str, http_code: int | None = 0, http_headers: Dict | None = None)

Bases: RuntimeError

Vss Error module.

property http_code

Get HTTP Code.

http_headers: Dict = {}

message: str