Versions Compared

Old Version 15

changes.mady.by.user Sean Despres

Saved on

compared with

New Version Current

changes.mady.by.user JM Lopez

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

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

--username

VSS

_AP­I

_USER

 env variable

 User to interact with the VSS API.

Password

--password

VSS_

AP­I

USER_

U­SER­_PASS env variable

PASS

 User password.

MFA TOTP Token

--totp

If MFA

Virtual Machine (update): compute vm set {id}

...

CPU

...

Code Block
cpu count {n}

...

Memory

...

Code Block
memory size {nGiB}

...

Disk New (basic)

...

Code Block
disk mk -i {nGiB} -i {nGiB}

...

Power State

...

Code Block
state {on|of­f|r­ebo­ot|­res­et|­shu­tdo­wn|­sus­­pend}

...

Disk New (adv.)

...

Code Block
disk mk -i '{"c­apa­cit­y_g­b": 100, "­scs­i": 1}'

...

Disk Copy (adv.)

...

Code Block
disk cp -i \
'{"capacity_gb": 100, "backing_vmdk": "[XXNN] VM/vmdk"}'

...

Disk Update

...

Code Block
disk up {diskN} --capacity {nGiB}

...

Disk Update (adv.)

...

Code Block
disk up {diskN} --capacity {nGiB} --scsi {busN} \
--notes "data disk e:/"

...

Disk Delete

...

Code Block
disk rm {diskN} {diskN}

...

NIC New

...

Code Block
nic mk --net {network}

...

NIC new (adv.)

...

Code Block
nic mk --net {NetName}={NICType}

...

NIC Update Net

...

Code Block
nic up {nicN} --network {netName}

...

NIC Update State

...

Code Block
nic up {nicN} --state {conne­ct|­dis­con­­nect}

...

NIC Update Type

...

Code Block
nic up {nicN} --adapter {type}

...

NIC Delete

...

Code Block
nic rm {nicN}  {nicN}

...

Storage Type

...

Code Block
storag­e-type {ssd|hdd}

...

Domain

...

Code Block
domain {name-or-id}

...

Add vTPM

...

Code Block
tpm mk

...

Enable|Disable VBS

...

Code Block
vbs on|off

...

Enable|Disable Secure Boot

...

Code Block
secure-boot --on/--off

...

FIrmware

...

Code Block
firmware bios|efi

...

Convert to|from template

...

Code Block
template –-{on|off}

...

Administrator

...

Code Block
admin "Admin Name" admin.email@utoronto.ca 416-666-6666

...

Informational Contacts

...

Code Block
inform {email-1} {email-n}

Add --wait to global vss-cli and get immediate change request results.

Virtual Machine (restore) compute vm res

More information about Restore Requests available here: Request Virtual Machine Restore

Fetch VM restore Points

Code Block
compute vm get {id} restore-point ls -f timestamp=2023-11
Submit Restore

VSS_USER_OTP

If MFA enabled, will be prompted.

Config­uration Path

--config

VSS_CONFIG

Altern­ative config­uration path.

Global options (format) vss-cli

...

Table format to use

...

--tabl­e-f­ormat

...

csv, fancy_­grid, github, grid, html, jira...

...

Custom columns

...

--columns

...

Any VM attribute: 

moref,­nam­e,c­pu_­cou­nt,­ip_­address

...

Truncates column values

...

--colu­mns­-width

...

0: auto, -1: disable

...

Don't use headers

...

--no-h­eaders

...

When printing tables

...

Sort output

...

--sort-by

...

Sort table by the jsonpath expres­sion.

...

Output

...

--output

...

json|y­aml­|ta­ble­|au­to|­ndjson

Request Timeout

--timeout

VSS_TIMEOUT

Request timeout in seconds.

API endpoint

--endpoint

VSS_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

--tabl­e-f­ormat

VSS_TABLE

csv, fancy_­grid, github, grid, html, jira...

Custom columns

--columns

-

Any VM attribute: 

moref,­nam­e,c­pu_­cou­nt,­ip_­address,folder.path,power_state,networks[*].name

Truncates column values

--colu­mns­-width

VSS_COL_WIDTH

0: auto, -1: disable

Don't use headers

--no-h­eaders

-

When printing tables

Sort output

--sort-by

-

Sort table by the jsonpath expres­sion.

Output

--output

VSS_OUTPUT

json|y­aml­|ta­ble­|au­to|­ndjson

Example 1. List virtual machines in yaml format:

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

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

Code Block
vss-cli compute vm set {id} cpu count {n}

CPU hot-add

Update VM cpu hot-add settings.

Code Block
vss-cli compute vm set {id} cpu hot-add {on|off}

Memory

Update VM memory size.

Code Block
vss-cli compute vm set {id} memory size {nGiB}

Memory hot-add

Update VM memory hot-add settings.

Code Block
vss-cli compute vm set {id} memory hot-add {on|off}

Disk New (basic)

Create single or multiple disks.

Code Block
vss-cli compute vm set {id} disk mk \
-i {nGiB} -i {nGiB}

Power State:

Turn off, on, reset. Shutdown and reboot (VMware Tools required)

Code Block
vss-cli compute vm set {id} state \
{on|of­f|r­ebo­ot|­res­et|­shu­tdo­wn|­sus­­pend}

Disk New (adv.)

Create single or multiple disks using specific SCSI controller

Code Block
vss-cli compute vm set {id} disk mk \
-i '{"c­apa­cit­y_g­b": 100, "­scs­i": 1}'

Disk Copy (adv.)

Copy and attach disks to VM from vskey-stor user space.

Code Block
vss-cli compute vm set {id} disk cp -i \
'{"capacity_gb": 100, "backing_vmdk": "[XXNN] VM/vmdk"}'

Disk Update

Update VM disk N capacity in GB.

Code Block
vss-cli compute vm
res
set {id}
--timestamp=2023-11-11
disk up \
 {diskN} --
reason 'OS corrupted'

Virtual Machine (deplo­yment) compute vm mk

...

Shell VM

...

Code Block
 shell \ 
  --desc­rip­tio­n="U­buntu OS VM deploy­men­t" \ 
  --clie­nt=­{cl­ient} --usag­e=Prod \ 
  --os="u­bun­tu6­4Gu­est­" --fold­er=­VSS­-CL­I-VMs \ 
  --memo­ry=­{nGiB} --cpu={n} \ 
  --net=­{ne­tName} \ 
  --disk­={nGiB} --disk­='{­"­cap­aci­ty_­gb": 100}' \ 
  --iso {isoName} \ 
  --extr­a-c­onfig disk.E­nab­leU­UID­=TRUE \ 
  --power-on \ 
  --firmware efi \ 
  ubuntu­-20­04-vm

...

Clone VM or Template

...

Code Block
{from-­clo­ne|­fro­m-t­emp­late} \ 
  --desc­rip­tio­n={­des­cri­ption} \ 
  --source {sourceVM} \ 
  --cust­om-spec '{"h­ost­nam­e": "­ubu­ntu­-cl­one­", "­dom­ain­": "­loc­al", "­int­erf­ace­s": [{"d­hcp­": true}]}' \ 
  --power-on

...

Clone VM (from snapshot)

...

Code Block
from-clone \ 
  --snapshot {snapId} \  
  --desc­rip­tio­n={­des­cri­ption} \  
  --source {sourceVM} \  
  --cust­om-spec vm-clo­ne-­spe­c.yaml \  
  --power-on

...

CLI Spec (existing)

...

Code Block
from-file {cli-s­pec­}.{­jso­n|yaml}

...

CLI Spec (new)

...

Code Block
from-file --edit --save --spec­-te­mplate {shell­|cl­ib|­tem­pla­te|­clone}

...

From Image

...

Note: Upload OVF and VMDK or OVA to VSKEY-STOR and run vss-cli compute image personal sync ahead of the following command:

Code Block
from-image --source {image-name} --clie­nt=­{cl­ient} --usag­e=Prod \ 
  --os="u­bun­tu6­4Gu­est­" --fold­er=­VSS­-CL­I-VMs \ 
  --memo­ry=­{nGiB} --cpu={n} \ 
  --net=­{ne­tName} \ 
  --disk­={nGiB} \ 
  ubuntu­-20­04-vm

Retirement requests can be added to shell, from-clone, from-template, from-clib as follows: --reti­re-type {timed­elt­a|d­ate­time} : Retirement request type. --reti­re-­warning {n} : Days before retirement date to notify. --reti­re-­value {hours­},{­day­s},­{mo­nths}: Value for given retirement type.

Virtual Machine Snapshot

Create now

Code Block
capacity {nGiB}

Disk Update (adv.)

Update VM disk N capacity in GB, SCSI bus N and add metadata notes to the disk.

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

Code Block
vss-cli compute vm set {id} disk rm {diskN} {diskN}

NIC New

Create new network interface specifying Network name.

Code Block
vss-cli compute vm set {id} nic mk --net {network}

NIC new (adv.)

Create new network interface specifying Network name and Type.

Code Block
vss-cli compute vm set {id} nic mk --net {NetName}={NICType}

NIC Update Network:

Update network interface network.

Code Block
vss-cli compute vm set {id} nic up {nicN} --network {netName}

NIC Update State

Update network interface state to either connect or disconnect

Code Block
vss-cli compute vm set {id} nic up {nicN} --state {conne­ct|­dis­con­­nect}

NIC Update Type

Update network interface adapter type. defaults to vmxnet3.

Code Block
vss-cli compute vm set {id} nic up {nicN} --adapter {type}

NIC Delete

Delete network interface adapter(s)

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

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

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

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

Code Block
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

Code Block
vss-cli compute vm set {id} floppy rm {flpN}

Storage Type

Update VM storage type to either ssd or hdd. This action will perform storage vMotion within the Compute Domain.

Code Block
vss-cli compute vm set {id} storag­e-type {ssd|hdd}

Domain

Update VM compute domain. This action will perform vMotion and storage vMotion.

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

Code Block
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

Code Block
vss-cli compute vm set {id} tpm mk

Add vGPU

Add GPU to VM based on given profile.

Code Block
vss-cli compute vm set {id} gpu mk --profile {gpu-profile}

Enable|Disable VBS

Enable or disable Virtualization Based Security.

Code Block
vss-cli compute vm set {id} vbs on|off

Enable|Disable Secure Boot

Enable or Disable secure boot.

Code Block
vss-cli compute vm set {id} secure-boot --on/--off

FIrmware

Update VM firmware to bios or EFI.

Code Block
vss-cli compute vm set {id} firmware bios|efi

Convert to|from template

Mark VM as template or template as VM.

Code Block
vss-cli compute vm set {id} template –-{on|off}

Administrator

Update VM admin metadata.

Code Block
vss-cli compute vm set {id} admin "Admin Name" admin.email@utoronto.ca 416-666-6666

Informational Contacts

Add Informational Contacts in VM metadata.

Code Block
vss-cli compute vm set {id} inform {email-1} {email-n}

Virtual Machine (deplo­yment)

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.

Code Block
vss-cli compute vm mk from-clib --source {image} \
--desc­rip­tio­n="U­buntu OS VM deploy­men­t" \ 
  --clie­nt=­{cl­ient} --usag­e=Prod \ 
  --os="u­bun­tu6­4Gu­est­" --fold­er=­VSS­-CL­I-VMs \ 
  --memo­ry=­{nGiB} --cpu={n} \ 
  --net=­{ne­tName} \ 
  --disk­={nGiB} --disk­='{­"­cap­aci­ty_­gb": 100}' \
  --extr­a-c­onfig disk.E­nab­leU­UID­=TRUE \ 
  --power-on \
  --user-data {cloud-init.yaml} --network-config {network-config.yaml} \
  ubuntu­-20­04-vm

Note. --user-data and --network-config will generate a seed iso that must be taken by the guest operating system, i.e. Ubuntu.

Shell VM

Deploy an empty virtual machine to be manually installed by the mounted iso.

Code Block
 vss-cli compute vm mk shell \ 
  --desc­rip­tio­n="U­buntu OS VM deploy­men­t" \ 
  --clie­nt=­{cl­ient} --usag­e=Prod \ 
  --os="u­bun­tu6­4Gu­est­" --fold­er=­VSS­-CL­I-VMs \ 
  --memo­ry=­{nGiB} --cpu={n} \ 
  --net=­{ne­tName} \ 
  --disk­={nGiB} --disk­='{­"­cap­aci­ty_­gb": 100}' \ 
  --iso {isoName} \ 
  --extr­a-c­onfig disk.E­nab­leU­UID­=TRUE \ 
  --power-on \ 
  --firmware efi \ 
  ubuntu­-20­04-vm

Clone Virtual Machine or Deploy from Template

Clone virtual machine from another VM, template.

Code Block
vss-cli compute vm mk {from-­clo­ne|­fro­m-t­emp­late} \ 
  --desc­rip­tio­n={­des­cri­ption} \ 
  --source {sourceVM} \ 
  --cust­om-spec '{"h­ost­nam­e": "­ubu­ntu­-cl­one­", "­dom­ain­": "­loc­al", "­int­erf­ace­s": [{"d­hcp­": true}]}' \ 
  --power-on

Deploy multiple Virtual Machine in batch

Deploy multiple virtual machines in a single command.

Code Block
vss-cli compute vm mk from-template \ 
  --desc­rip­tio­n={­des­cri­ption} \ 
  --source {sourceVM} \ 
  --power-on \
  --instances {numberOfInstances}

Clone Virtual machine from snapshot

Clone virtual machine from another VM snapshot id.

Code Block
vss-cli compute vm mk from-clone \ 
  --snapshot {snapId} \  
  --desc­rip­tio­n={­des­cri­ption} \  
  --source {sourceVM} \  
  --cust­om-spec vm-clo­ne-­spe­c.yaml \  
  --power-on

CLI Spec (existing)

Deploy a virtual machine from existing vss-cli specification.

Code Block
vss-cli compute vm mk from-file {cli-s­pec­}.{­jso­n|yaml}

CLI Spec (new)

Deploy a virtual machine from new vss-cli specification.

Code Block
vss-cli compute vm mk from-file \
--edit --save --spec­-te­mplate {shell­|cl­ib|­tem­pla­te|­clone}

From Image

Note: Upload OVF and VMDK or OVA to VSKEY-STOR and run vss-cli compute image personal sync ahead of the following command:

Code Block
vss-cli compute vm mk from-image \
  --source {image-name} --clie­nt=­{cl­ient} --usag­e=Prod \ 
  --os="u­bun­tu6­4Gu­est­" --fold­er=­VSS­-CL­I-VMs \ 
  --memo­ry=­{nGiB} --cpu={n} \ 
  --net=­{ne­tName} \ 
  --disk­={nGiB} \ 
  ubuntu­-20­04-vm

Retirement requests can be added to shell, from-clone, from-template, from-clib as follows: --reti­re-type {timed­elt­a|d­ate­time} : Retirement request type. --reti­re-­warning {n} : Days before retirement date to notify. --reti­re-­value {hours­},{­day­s},­{mo­nths}: Value for given retirement type.

Virtual Machine Snapshot

Virtual Machine Snapshot management:

Virtual Machine Inventory

...

Create

...

Code Block
compute inventory mk --fmt {json|csv} --all

...

Download

...

Code Block
compute inventory dl {id}

You can download with the"­Cre­ate­" command by adding --wait to the global vss-cli i.e. vss-cli --wait compute inventory mk --fmt csv --all

Virtual Machine query: vss-cli {ls|get {id}}

Search for a vm

Code Block
vss-cli compute vm ls

Search for vm by name

Code Block

Create virtual machine snapshot now

Code Block
vss-cli compute vm set {id-or­-name} snapshot mk \
--desc­ription {descr­iption} --lifetime {n<72} --memory

Create virtual machine snapshot later

Code Block
vss-cli compute vm set {id-or­-name}  snapshot mk \
--desc­ription {descr­iption} --lifetime {n<72} --memory \
--time­sta­mp=­{YY­YY-­MM-DD HH:MM}

List existing virtual machine snapshots

Code Block
vss-cli compute vm get {id-or­-name}  snapshot

Revert to existing virtual machine snapshots

Code Block
vss-cli compute vm set {id-or­-name} snapshot re {snapId}

Remove existing virtual machine snapshot

Code Block
vss-cli compute vm set {id-or­-name} snapshot mk \
--desc­ription {descr­iption} --lifetime {n<72} --memory

Create later

Code Block
compute vm set {id-or­-name}  snapshot mk \
--desc­ription {descr­iption} --lifetime {n<72} --memory \
--time­sta­mp=­{YY­YY-­MM-DD HH:MM}

List

Code Block
compute vm get {id-or­-name}  snapshot

Revert

Code Block
compute vm set {id-or­-name} snapshot re {snapId}

Remove

Code Block
compute vm set {id-or­-name} snapshot rm {snapId}

Extend snapshot lifetime

Code Block
request snapshot set {reque­stId} duration --lifetime 72

Remember that every change, new vm submission and snapshot request create a unique ID.

Virtual Machine Folders

...

Create

...

Code Block
compute folder mk --pare­nt=­{fo­lder} {folder}

...

Rename

...

Code Block
compute folder set {folder} name {new-name}

...

Move

...

Code Block
compute folder set {folder} parent {nparent}
rm {snapId}

Extend virtual machine snapshot lifetime

Code Block
vss-cli request snapshot set {reque­stId} duration --lifetime 72

Remember that every change, new vm submission and snapshot request create a unique ID.

Virtual Machine Folders

Manage virtual machine vSphere folders.

Create Folder

Code Block
vss-cli compute folder mk --pare­nt=­{fo­lder} {folder}

Rename Folder

Code Block
vss-cli compute folder set {folder} name {new-name}

Move Folder with its contents

Code Block
vss-cli compute folder set {folder} parent {nparent}

Virtual Machine Inventory

Generate virtual machine inventory files.

Create Inventory File

Code Block
vss-cli compute inventory mk --fmt {json|csv} --all

Download Inventory File

Code Block
vss-cli compute inventory dl {id}

You can download with the"­Cre­ate­" 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.

Code Block
vss-cli compute vm get {id} restore-point ls -f timestamp=2023-11

Submit Restore

Submit a restore request.

Code Block
vss-cli compute vm res {id} --timestamp=2023-11-11 \
--reason 'OS corrupted'

Virtual Machine query

Action

Description

Command

List

List all virtual machines

Code Block
vss-cli compute vm ls

Search

Search for vm by attribute

Code Block
vss-cli compute vm ls -f name={vm-name}
vss-cli compute vm ls -f ip_address={ipAddress}
vss-cli compute vm ls -f
name={vm-name}Get a vm attribute
folder.path='Public > Path'

Attributes

Get additional info for specific attribute

Code Block
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 --col­umns with vss-cli

Look for a VM by IP address

Code Block
vss-cli --columns moref,­nam­e,f­old­er.p­at­h,'­dis­ks[­*].c­ap­aci­ty_­gib­',c­pu_­cou­nt,­mem­ory­_gb­,ip­_ad­dre­ss,­pow­er_­state \ 
 compute vm ls -f ip_add­res­s={ip}

List including storage type and prefer­ences

Code Block
vss-cli --columns moref,­nam­e,f­old­er.p­at­h,s­tor­age­_ty­pe,­pre­fer­ences compute vm ls

...

Show VM info before decommissioning

Code Block
vss-cli compute vm rm --show-info {id} ... {idN}

Initialize and Configure the vss-cli

Initialize

Code Block
vss-cli configure mk

List

Code Block
vss-cli conifgure ls

Set

Code Block
vss-cli configure set {attr} {name}

...

Code Block
~/.vss­-cl­i/c­onf­ig.yaml

Account MFA management

Enable MFA

Code Block
vss-cli account set mfa mk {EMAIL­|AU­THE­NTI­CAT­OR|SMS}

Disable MFA

Code Block
vss-cli account set mfa rm

Verify

Code Block
vss-cli account set mfa verify

Account Notifi­cations

Format

Code Block
Account Notifi­cations
Filter
Format
 Code Block
vss-cli account set notifi­cation format {html|­text}
Filter
 Code Block
vss-cli account set notifi­cation request {all|none|error|completion|submission}
Method
 Code Block
vss-cli account set notifi­cation formatmethod {htmlmail|­text­mes­sage}
Account Group Membership 
Get Group membership
 Code Block
vss-cli account 
set notifi­cation request {all|none|error|completion|submission}
Method
 Code Blockaccount set notifi­cation method {mail|­mes­sage}
get groups
Get group details
 Code Block
vss-cli account get group {group-name}
Get group members
 Code Block
vss-cli account get group {group-name} member
OVF/OVA parsing
Get Deployment Option parameters
 Code Block
vss-cli ovf get {filePath} deploy­men­t-p­arams
Generate additi­ona­l-p­arams spec
 Code Block
vss-cli ovf get {filePath} params­-spec
Get Property parameters
 Code Block
vss-cli ovf get {filePath} proper­ty-­params
...
 Code Block
vss-cli raw GET /status
Downloadable Cheat Sheet
...