pyvss

Manager

This module sends request to the ITS Private Cloud API.

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

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

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

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

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

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

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:

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

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

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

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.

more information about required attributes available in Virtual Machine

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.

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

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

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

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

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

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

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

more information about required attributes available in Virtual Machine

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.

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

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

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

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

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

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

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

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

more information about required attributes available in Virtual Machine

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.

more information about required attributes available in Virtual Machine

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.

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

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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.

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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

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

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

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

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

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

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

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

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

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