- Global options
- Global options (format)
- Virtual Machine (update)
- Virtual Machine (deployment)
- Virtual Machine Snapshot
- Virtual Machine Domains
- Virtual Machine Folders
- Virtual Machine Inventory
- Virtual Machine (restore)
- Virtual Machine query
- Virtual Machine query (advanced): The power of --columns with vss-cli
- Decommission Virtual Machine
- Initialize and Configure the vss-cli
- Account MFA management
- Account Notifications
- Account Group Membership
- OVF/OVA parsing
- Raw requests
Global options
The following table includes global vss-cli options related to account username and password, API endpoint and MFA TOTP token.
Name | Option | Environment Variable | Description |
|---|---|---|---|
Username |
|
| User to interact with the VSS API. |
Password |
|
| User password. |
MFA TOTP Token |
|
| If MFA enabled, will be prompted. |
Configuration Path |
|
| Alternative configuration path. |
Request Timeout |
|
| Request timeout in seconds. |
API endpoint |
|
| ITS Private Cloud endpoint instance. |
Global options (format)
The following table includes the global vss-cli options to customize output format.
Name | Option | Environment Variable | Description |
|---|---|---|---|
Table format to use |
|
|
|
Custom columns |
| - | Any VM attribute:
|
Truncates column values |
|
| 0: auto, -1: disable |
Don't use headers |
| - | When printing tables |
Sort output |
| - | Sort table by the jsonpath expression. |
Output |
|
|
|
Example 1. List virtual machines in yaml format:
vss-cli --output yaml compute vm ls
Example 2. List virtual machines with only moref, name, cpu_count, ip_address with fancy_grid in the table format.
vss-cli --columns moref,name,cpu_count,ip_address --table-format fancy_grid compute vm ls
Virtual Machine (update)
Manage virtual machine attributes with the vss-cli.
Add --wait to global vss-cli and get immediate change request results.
Action | Description | Command |
|---|---|---|
CPU | Update VM CPU count. | vss-cli compute vm set {id} cpu count {n}
|
CPU hot-add | Update VM cpu hot-add settings. | vss-cli compute vm set {id} cpu hot-add {on|off}
|
Memory | Update VM memory size. | vss-cli compute vm set {id} memory size {nGiB}
|
Memory hot-add | Update VM memory hot-add settings. | vss-cli compute vm set {id} memory hot-add {on|off}
|
Disk New (basic) | Create single or multiple disks. | vss-cli compute vm set {id} disk mk \
-i {nGiB} -i {nGiB}
|
Power State: | Turn off, on, reset. Shutdown and reboot (VMware Tools required) | vss-cli compute vm set {id} state \
{on|off|reboot|reset|shutdown|suspend}
|
Disk New (adv.) | Create single or multiple disks using specific SCSI controller | vss-cli compute vm set {id} disk mk \
-i '{"capacity_gb": 100, "scsi": 1}'
|
Disk Copy (adv.) | Copy and attach disks to VM from | vss-cli compute vm set {id} disk cp -i \
'{"capacity_gb": 100, "backing_vmdk": "[XXNN] VM/vmdk"}'
|
Disk Update | Update VM disk | vss-cli compute vm set {id} disk up \
{diskN} --capacity {nGiB}
|
Disk Update (adv.) | Update VM disk | vss-cli compute vm set {id} disk up \
{diskN} --capacity {nGiB} --scsi {busN} \
--notes "data disk e:/"
|
Disk Delete | Delete VM disk(s). Confirmation will be prompted. | vss-cli compute vm set {id} disk rm {diskN} {diskN}
|
NIC New | Create new network interface specifying Network name. | vss-cli compute vm set {id} nic mk --net {network}
|
NIC new (adv.) | Create new network interface specifying Network name and Type. | vss-cli compute vm set {id} nic mk --net {NetName}={NICType}
|
NIC Update Network: | Update network interface network. | vss-cli compute vm set {id} nic up {nicN} --network {netName}
|
NIC Update State | Update network interface state to either | vss-cli compute vm set {id} nic up {nicN} --state {connect|disconnect}
|
NIC Update Type | Update network interface adapter type. defaults to | vss-cli compute vm set {id} nic up {nicN} --adapter {type}
|
NIC Delete | Delete network interface adapter(s) | vss-cli compute vm set {id} nic rm {nicN} {nicN}
|
CD/ISO Create | Create CD drive with attached ISO image from Content Library or client. | vss-cli compute vm set {id} cd mk --backing {iso}
vss-cli compute vm set {id} cd mk cd mk --backing client
|
CD/ISO Update | Update CD drive to connect to a different ISO or disconnect. | vss-cli compute vm set {id} cd up {cdN} --backing {iso}
vss-cli compute vm set {id} cd up {cdN} --backing client
|
Floppy Drive Create | Create virtual floppy drive with given image or client. | vss-cli compute vm set {id} floppy mk --backing {image}
vss-cli compute vm set {id} floppy mk --backing client
|
Floppy Drive Update | Update virtual floppy backing with a different image or client. | vss-cli compute vm set {id} floppy up {flpN} --backing {image}
vss-cli compute vm set {id} floppy up {flpN} --backing client
|
Floppy Drive Remove | Remove virtual floppy | vss-cli compute vm set {id} floppy rm {flpN}
|
Storage Type | Update VM storage type to either | vss-cli compute vm set {id} storage-type {ssd|hdd}
|
Domain | Update VM compute domain. This action will perform vMotion and storage vMotion. | vss-cli compute vm set {id} domain {name-or-id}
|
Operating System | Update VM operating system settings. This setting is responsible to present the right virtual hardware to the guest OS. | vss-cli compute vm set {id} os {name-or-id}
|
Add vTPM | Add virtual Trusted Platform Module to VM. Virtualization Based Security, EFI and secure boot will be also en | vss-cli compute vm set {id} tpm mk
|
Add vGPU | Add GPU to VM based on given profile. | vss-cli compute vm set {id} gpu mk --profile {gpu-profile}
|
Enable|Disable VBS | Enable or disable Virtualization Based Security. | vss-cli compute vm set {id} vbs on|off
|
Enable|Disable Secure Boot | Enable or Disable secure boot. | vss-cli compute vm set {id} secure-boot --on/--off
|
FIrmware | Update VM firmware to bios or EFI. | vss-cli compute vm set {id} firmware bios|efi
|
Convert to template | Mark VM as template | vss-cli compute vm set {id} template
|
Convert from template | Mark Template as VM | vss-cli compute template set {id} vm
|
Administrator | Update VM admin metadata. | vss-cli compute vm set {id} admin "Admin Name" admin.email@utoronto.ca 416-666-6666
|
Informational Contacts | Add Informational Contacts in VM metadata. | vss-cli compute vm set {id} inform {email-1} {email-n}
|
Virtual Machine (deployment)
Deploy virtual machines from content library, clone, template, shell, file specification and more.
Type | Description | Command |
|---|---|---|
Content Library | Deploy a virtual machine from an OVA image with pre-installed operating system from our Content Library. | vss-cli compute vm mk from-clib --source {image} \
--description="Ubuntu OS VM deployment" \
--client={client} --usage=Prod \
--os="ubuntu64Guest" --folder=VSS-CLI-VMs \
--memory={nGiB} --cpu={n} \
--net={netName} \
--disk={nGiB} --disk='{"capacity_gb": 100}' \
--extra-config disk.EnableUUID=TRUE \
--power-on \
--user-data {cloud-init.yaml} --network-config {network-config.yaml} \
ubuntu-2004-vm
Note. |
Shell VM | Deploy an empty virtual machine to be manually installed by the mounted iso. | vss-cli compute vm mk shell \
--description="Ubuntu OS VM deployment" \
--client={client} --usage=Prod \
--os="ubuntu64Guest" --folder=VSS-CLI-VMs \
--memory={nGiB} --cpu={n} \
--net={netName} \
--disk={nGiB} --disk='{"capacity_gb": 100}' \
--iso {isoName} \
--extra-config disk.EnableUUID=TRUE \
--power-on \
--firmware efi \
ubuntu-2004-vm
|
Clone Virtual Machine or Deploy from Template | Clone virtual machine from another VM, template. | vss-cli compute vm mk {from-clone|from-template} \
--description={description} \
--source {sourceVM} \
--custom-spec '{"hostname": "ubuntu-clone", "domain": "local", "interfaces": [{"dhcp": true}]}' \
--power-on
|
Deploy multiple Virtual Machine in batch | Deploy multiple virtual machines in a single command. | vss-cli compute vm mk from-template \
--description={description} \
--source {sourceVM} \
--power-on \
--instances {numberOfInstances}
|
Clone Virtual machine from snapshot | Clone virtual machine from another VM snapshot id. | vss-cli compute vm mk from-clone \
--snapshot {snapId} \
--description={description} \
--source {sourceVM} \
--custom-spec vm-clone-spec.yaml \
--power-on
|
CLI Spec (existing) | Deploy a virtual machine from existing | vss-cli compute vm mk from-file {cli-spec}.{json|yaml}
|
CLI Spec (new) | Deploy a virtual machine from new | vss-cli compute vm mk from-file \
--edit --save --spec-template {shell|clib|template|clone}
|
From Image | Note: Upload vss-cli compute vm mk from-image \
--source {image-name} --client={client} --usage=Prod \
--os="ubuntu64Guest" --folder=VSS-CLI-VMs \
--memory={nGiB} --cpu={n} \
--net={netName} \
--disk={nGiB} \
ubuntu-2004-vm
|
Retirement requests can be added to shell, from-clone, from-template, from-clib as follows: --retire-type {timedelta|datetime} : Retirement request type. --retire-warning {n} : Days before retirement date to notify. --retire-value {hours},{days},{months}: Value for given retirement type.
Virtual Machine Snapshot
Virtual Machine Snapshot management:
Create virtual machine snapshot now |
vss-cli compute vm set {id-or-name} snapshot mk \
--description {description} --lifetime {n<72} --memory
|
Create virtual machine snapshot later |
vss-cli compute vm set {id-or-name} snapshot mk \
--description {description} --lifetime {n<72} --memory \
--timestamp={YYYY-MM-DD HH:MM}
|
List existing virtual machine snapshots |
vss-cli compute vm get {id-or-name} snapshot
|
Revert to existing virtual machine snapshots |
vss-cli compute vm set {id-or-name} snapshot re {snapId}
|
Remove existing virtual machine snapshot |
vss-cli compute vm set {id-or-name} snapshot rm {snapId}
|
Extend virtual machine snapshot lifetime |
vss-cli request snapshot set {requestId} duration --lifetime 72
|
Remember that every change, new vm submission and snapshot request create a unique ID.
Virtual Machine Domains
List all available domains |
vss-cli compute domain ls |
Virtual Machine Folders
Manage virtual machine vSphere folders.
List all available Folders |
vss-cli compute folder ls |
Create Folder |
vss-cli compute folder mk --parent={folder} {folder}
|
Rename Folder |
vss-cli compute folder set {folder} name {new-name}
|
Move Folder with its contents |
vss-cli compute folder set {folder} parent {nparent}
|
Virtual Machine Inventory
Generate virtual machine inventory files.
Create Inventory File | vss-cli compute inventory mk --fmt {json|csv} --all
|
Download Inventory File | vss-cli compute inventory dl {id}
|
You can download with the"Create" command by adding --wait to the global vss-cli i.e. vss-cli --wait compute inventory mk --fmt csv --all
Virtual Machine (restore)
Restore virtual machine from ZFS snapshots. More information about Restore Requests available here: How-to Request Virtual Machine Restore
Action | Description | Command |
|---|---|---|
Get Restore Points | List available restore points filtered by timestamp. | vss-cli compute vm get {id} restore-point ls -f timestamp=2023-11
|
Submit Restore | Submit a restore request. | vss-cli compute vm res {id} --timestamp=2023-11-11 \
--reason 'OS corrupted'
|
Virtual Machine query
Action | Description | Command |
|---|---|---|
List | List all virtual machines | vss-cli compute vm ls |
Search | Search for vm by attribute | vss-cli compute vm ls -f name={vm-name}
vss-cli compute vm ls -f ip_address={ipAddress}
vss-cli compute vm ls -f folder.path='Public > Path'
|
Attributes | Get additional info for specific attribute | vss-cli compute vm get {id} \
{cpu|memory|disk|state|nic|storage-type...}
vss-cli compute vm get --help
|
Virtual Machine query (advanced): The power of --columns with vss-cli
Look for a VM by IP address |
vss-cli --columns moref,name,folder.path,'disks[*].capacity_gib',cpu_count,memory_gb,ip_address,power_state \
compute vm ls -f ip_address={ip}
|
List including storage type and preferences |
vss-cli --columns moref,name,folder.path,storage_type,preferences compute vm ls |
To show all vm attributes that can be used in the --columns option, use:
vss-cli --output yaml compute vm ls -c 1
Decommission Virtual Machine
Show VM info before decommissioning |
vss-cli compute vm rm --show-info {id} ... {idN}
|
Initialize and Configure the vss-cli
Initialize | vss-cli configure mk |
List | vss-cli configure ls |
Set | vss-cli configure set {attr} {name}
|
Default configuration file is available at
~/.vss-cli/config.yaml
Account MFA management
Enable MFA | vss-cli account set mfa mk {EMAIL|AUTHENTICATOR|SMS}
|
Disable MFA | vss-cli account set mfa rm |
Verify | vss-cli account set mfa verify |
Account Notifications
Format | vss-cli account set notification format {html|text}
|
Filter | vss-cli account set notification request {all|none|error|completion|submission}
|
Method | vss-cli account set notification method {mail|message}
|
Account Group Membership
Get Group membership | vss-cli account get groups |
Get group details | vss-cli account get group {group-name}
|
Get group members | vss-cli account get group {group-name} member
|
OVF/OVA parsing
Get Deployment Option parameters | vss-cli ovf get {filePath} deployment-params
|
Generate additional-params spec | vss-cli ovf get {filePath} params-spec
|
Get Property parameters | vss-cli ovf get {filePath} property-params
|
Raw requests
vss-cli raw {GET|POST|PUT|DELETE|PATCH} {resource}
|
For example:
vss-cli raw GET /status