Page Comparison

Create an instance of VssManager passing your ITS Private Cloud API access token and your are all set to start calling any of the self-descriptive methods includedThis section describes the VSS Command Line Interface in detail.

Anchor
Help
Help
Anchor
Use-Help
Use-Help
Help

To get help when using the VSS CLI, you can add --help option to the end of a command. For example:

Code Block

language	bash
linenumbers	false

vss-cli --help

The following command lists the available sub commands for the compute command:

Code Block

language	bash
linenumbers	false

vss-cli compute --help

Help in sub commands is divided in three main sections: Usage, where the command syntax is shown as well as a brief description; Options and sub commands available with a short help column as shown below:

Code Block

language	bash
linenumbers	false

Usage: vss-cli compute [OPTIONS] COMMAND [ARGS]...

  Compute related resources such as virtual machines, networks supported
  operating systems, logical folders, OVA/OVF images, floppy images, ISO
  images and more.

Options:
  --help  Show this message and exit.

Commands:
  domain     List compute domains.
  floppy     Manage floppy images.
  folder     Manage logical folders
  image      Manage personal and list public VM images.
  inventory  Manage inventory reports
  iso        Manage ISO images.
  net        List available virtual networks
  os         Supported OS.
  template   List virtual machine templates
  vm         Manage virtual machines

For instance, the vss-cli compute vm ls command, is used to list your virtual machines hosted in the ITS Private Cloud, has the following usage:

Code Block

language	pythonbash
linenumbers	false

from pyvss.manager import VssManager
vss = VssManager(tk='api_token')

# list vms
vms = vss.get_vms()

# list folders
folders = vss.get_folders(name='dev')

# networks
networks = vss.get_networks(name='PUBLIC')

# domains
domains = vss.get_domains()

# power cycle vm
vss.power_cycle_vm(vm_id='<uuid-or-moref>')

# vss-service
service = vss.get_vss_services(filter='name,like,%Shibboleth%')

# create vm with vss-service
req = vss.create_vm(
    os='ubuntu64Guest', built='os_install',
    description='Testing python wrapper',
    folder='group-v9270', bill_dept='EIS', disks=[8, 50],
    vss_service=service[0].get('id'),
    networks=[networks[0].get('moref')]
    )

ids = vss.wait_for_request(req['_links']['request'], 'vm_moref', 'PROCESSED')

# creating multiple vms
reqs = vss.create_vms(
    count=3, name='python', os='ubuntu64Guest', bill_dept='EIS',
    description='Testing multiple deployment from python wrapper',
    folder='group-v6736', built='os_install',
    networks=[networks[0].get('moref')]
    )

ids = [vss.wait_for_request(r['_links']['request'], 'vm_moref', 'PROCESSED') for r in reqs]

# power on recently created vms
for vm_id in ids:
   vss.power_on_vm(vm_id)

# create snapshot
req = vss.create_vm_snapshot(
    vm_id='5012abcb-a9f3-e112-c1ea-de2fa9dab90a',
    desc='Snapshot description',
    date_time='2016-08-04 15:30',
    valid=1
    )

snap_id = vss.wait_for_request(req['_links']['request'], 'snap_id', 'PROCESSED')

# revert to snapshot
req = vss.revert_vm_snapshot(vm_id, snap_id)

...

Usage: vss-cli compute vm ls [OPTIONS]

  List virtual machine instances.

  Filter and sort list by any attribute. For example:

  vss-cli compute vm ls -f name=vm-name -f version=13

  Simple name filtering:

  vss-cli compute vm ls -f name=%vm-name% -s name desc

Options:
  -f, --filter-by <TEXT TEXT>...  filter list by <field_name>
                                  <operator>,<value>
  -a, --show-all                  show all results  [default: False]
  -p, --page                      page results in a less-like format
  -s, --sort <TEXT TEXT>...       sort by <field_name> <asc|desc>
  -c, --count INTEGER             size of results
  --help                          Show this message and exit.

An example of how to use filters and display virtual machine summary is shown below:

Code Block

language	bash
linenumbers	false

vss-cli compute vm ls -f name=%VM% -s name=desc

moref    name                  folder.path                                         cpu_count    memory_gb  power_state    ip_address
-------  --------------------  ------------------------------------------------  -----------  -----------  -------------  ------------
vm-1274  1910T-TestVM1         VSS > Development                                           1            2  poweredOff
vm-1270  1910T-TestVM2         VSS > Development                                           1            2  poweredOff
vm-1258  1910T-TestVM3         VSS > Development                                           1            1  poweredOff

Command Structure

The VSS CLI command structure is compose by the base vss-cli command followed by options, subgroups, sub-commands, options and arguments.

Code Block

language	bash
linenumbers	false

vss-cli [OPTIONS] COMMAND [ARGS]...

Parameters take different types of input values such as numbers, strings, lists, tuples, and JSON data structures as strings.

Parameter Values

VSS CLI options vary from simple string, boolean or numeric values to JSON data structures as input parameters on the command line.

Anchor
Common
Common
Anchor
Use-Common
Use-Common
Common

String parameters can contain alphanumeric characters and spaces surrounded by quotes. The following example renames a virtual machine:

Code Block

language	bash
linenumbers	false

vss-cli compute vm set vm-123 name 'VM-New'

Or this can be done by using the VM name instead as follows:

Code Block

language	bash
linenumbers	false

vss-cli compute vm set TEST name VM-New

If there’s more than one virtual machine with “TEST” in their name, you will be prompted to select which one you want to change:

Code Block

language	bash
linenumbers	false

Found 5 matches. Please select one:

=> (vm-1270) VSS > Development > 1910T-TestVM1
   (vm-1258) VSS > Development > 1910T-TestVM2
   (vm-1274) VSS > Development > 1910T-TestVM3

Once, selected the change will be processed.

Timestamp is widely used in any vm set command to schedule --schedule a change or in vm mk snapshot to define the start date --from of the snapshot. Timestamps are formatted YYYY-MM-DD HH:MM. In the next example, a virtual machine consolidation task has been submitted to run at 2017-03-10 21:00:

Code Block

language	bash
linenumbers	false

vss-cli compute vm set --schedule '2017-03-10 21:00' vm-123 consolidate

Lists are implemented in arguments and options. In arguments list are generally series of strings separated by spaces. The below command shows how to delete two virtual machines in a single line:

Code Block

language	bash
linenumbers	false

vss-cli compute vm rm vm-123 vm-234

Multiple options are taken as lists. For instance, in order to specify multiple disks when deploying a virtual machine, multiple occurrences of --disk should be specified as follows:

Code Block

language	bash
linenumbers	false

vss-cli compute vm mk from-template --power-on --source TestVM1 \
 --description 'New virtual machine' --disk 40 --disk 20 --disk 30 VM2

Boolean is a binary flag that turns an option on or off, such is the case of a virtual machine marked as template by using the --on flag or template marked as virtual machine by not specifying the flag.

Code Block

language	bash
linenumbers	false

vss-cli compute vm set TestVM3 template --on

Integers

Code Block

language	bash
linenumbers	false

vss-cli compute vm set TestVM2 memory size 1

Binary objects are handled by passing a relative or full path to the object to process. When uploading a file to VSKEY-STOR, a path should be passed as argument as follows:

Code Block

language	bash
linenumbers	false

vss stor ul ~/Downloads/50123e0d-6c74-0c6f-a65a-3704dd1ec619-ud.iso -d isos

JSON

Some VSS CLI options and arguments require data to be formatted as JSON, such as reconfiguring a virtual machine guest operating system specification (hostname, domain, dns, ip, subnet and gateway) upon deployment. The option --custom-spec expects the following JSON data structure:

Code Block

language	json
linenumbers	false

{
 "dhcp": false,
 "ip": "192.168.1.23",
 "gateway": ["192.168.1.1"],
 "dns": ["192.168.1.1"],
 "hostname": "vm1",
 "domain": "utoronto.ca"
}

Passing above JSON data structure to --custom-spec in Linux, macOS, or Unix and Windows PowerShell use the single quote ' to enclose it.

Code Block

language	bash
linenumbers	false

vss-cli compute vm mk from-template --source TestVM3 --power-on \
  --description 'New virtual machine' \
  --custom-spec '{"dhcp": false, "ip": "192.168.1.23", "gateway": ["192.168.1.1"],
   "dns": ["192.168.1.1"], "hostname": "vm1", "domain": "utoronto.ca"}' VM1

On the Windows command prompt, use the double quote " to enclose the data structure and escape the double quotes from the data structure using the backslash \:

Code Block

language	bash
linenumbers	false

vss-cli compute vm mk from-template --source FrontEnd-1 \
  --description 'New virtual machine' \
  --custom-spec "{\"dhcp\": false, \"ip\": \"192.168.1.23\", \"gateway\": [\"192.168.1.1\"],
   \"dns\": [\"192.168.1.1\"], \"hostname\": \"vm1\", \"domain\": \"utoronto.ca\"}" VM1

Command Output

The VSS CLI supports the following formats:

Table (table)
JSON (json)
YAML (yaml)
NDJSON (ndjson)
auto (table)

By default VSS CLI output is table, and this can be configured either by the output option:

Code Block

language	bash
linenumbers	false

vss-cli --output json

Or the VSS_OUTPUT environment variable:

Code Block

language	bash
linenumbers	false

export VSS_OUTPUT=json

Info
Environment variable `VSS_OUTPUT` always overrides any value set in the `-o/--output` option.

Anchor
Table
Table
Anchor
Use-Table
Use-Table
Table

The table format presents the VSS CLI output into tab-delimited lines, helpful when using grep, sed, and awk on Unix or Windows PowerShell.

Code Block

language	bash
linenumbers	false

vss-cli --table-format=rst compute vm ls -f name=%VM% -s name=desc

=======  ====================  ================================================  ===========  ===========  =============  ============
moref    name                  folder.path                                         cpu_count    memory_gb  power_state    ip_address
=======  ====================  ================================================  ===========  ===========  =============  ============
vm-1274  1910T-TestVM1         VSS > Development                                           1            2  poweredOff
vm-1270  1910T-TestVM2         VSS > Development                                           1            2  poweredOff
vm-1258  1910T-TestVM3         VSS > Development                                           1            1  poweredOff
=======  ====================  ================================================  ===========  ===========  =============  ============

You can also control the data shown with --columns providing a name and a jsonpath.

If you for example just wanted the UUID, NAME and PROVISIONED GB per virtual machines, you could do:

Code Block

language	bash
linenumbers	false

vss-cli --columns=moref,name,gb=provisioned_gb compute vm ls -f name=VM

moref    name                     gb
-------  --------------------  -----
vm-1270  1910T-TestVM1         22.19
vm-1258  1910T-TestVM2         21.19
vm-1274  1910T-TestVM3          2.19

The option --columns-width allows you to set a maximum column width for a given output:

Code Block

language	bash
linenumbers	false

vss-cli --columns-width 0 compute vm ls -f name=VM

moref    name            folder.path       cpu_count    memory_gb  power_state    ip_address
-------  --------------  --------------  -----------  -----------  -------------  ------------
vm-1270  1910T-TestVM-…  VSS > Develop…            1            2  poweredOff
vm-1258  1910T-TestVM-…  VSS > Develop…            1            1  poweredOff
vm-1274  1910T-TestVM-…  VSS > Develop…            1            2  poweredOff

--columns-width can be set to 0 in order to let the vss-cli to calculate the proper column size based on your terminal:

Code Block

language	bash
linenumbers	false

vss-cli --columns-width 18 compute vm ls -f name=VM

moref    name                folder.path           cpu_count    memory_gb  power_state    ip_address
-------  ------------------  ------------------  -----------  -----------  -------------  ------------
vm-1017  1908Q-VM-2          ITS > EIS > Data …            1            1  poweredOff
vm-1270  1910T-TestVM1       VSS > Development             1            2  poweredOff
vm-1258  1910T-TestVM2       VSS > Development             1            1  poweredOff
vm-1274  1910T-TestVM3       VSS > Development             1            2  poweredOff

JSON

Many languages can easily decode JSON structures using built-in modules or open source libraries. The VSS CLI can provide the output in json so it can be easily processed by other scripts or JSON processors such as jq.

Code Block

language	bash
linenumbers	false

vss --output=json compute vm ls
[
    {
    "moref": "vm-1270",
    "name": "1910T-TestVM1",
    "provisioned_gb": 2.18,
    "tools_running_status": "guestToolsNotRunning",
    "tools_version": "0",
    "tools_version_status": "guestToolsNotInstalled",
    "uncommitted_bytes": 2338168320,
    "unshared_bytes": 996,
    "updated_on": "2020-04-21 Tue 02:10:03 EDT",
    "uuid": "5030f8d5-fa01-8eff-bb21-8d1ee7e6c230",
    "version": "vmx-15"
    ...
    }
]

Anchor
YAML
YAML
Anchor
Use-YAML
Use-YAML
YAML

As with JSON, YAML can be easily decoded by many programming languages. The VSS CLI can provide the yaml output as follows:

Code Block

language	bash
linenumbers	false

 vss-cli --output=yaml compute vm ls -f name=%TEST% -s name desc

- moref: vm-2173
   name: 2004P-test-vm-centos
   provisioned_gb: 2.18
   tools_running_status: guestToolsNotRunning
   tools_version: '0'
   tools_version_status: guestToolsNotInstalled
   uncommitted_bytes: 2338168320
   unshared_bytes: 996
   updated_on: 2020-04-21 Tue 02:10:03 EDT
   uuid: 5030f8d5-fa01-8eff-bb21-8d1ee7e6c230
   version: vmx-15

Anchor
Auto-completion
Auto-completion
Anchor
Use-Auto-completion
Use-Auto-completion
Auto-completion

Bash completion support is provided by [Click][Click] and will complete sub commands and parameters. Sub commands are always listed whereas parameters only if at least a dash has been provided. Example:

Code Block

language	bash
linenumbers	false

vss-cli compute <TAB><TAB>
account    compute    configure  request    stor       token

vss-cli -<TAB><TAB>
--config      --no-verbose  --output      --verbose     --version     -c            -o

Source File

To activate completion in bash or zsh or fish is recommended to use a generated script and source it to ensure responsiveness:

For bash:

Save the script somewhere.

Code Block

language	bash
linenumbers	false

_VSS_CLI_COMPLETE=bash_source vss-cli > ~/.vss-cli-complete.bash

Source the file in ~/.bashrc.

Code Block

language	bash
linenumbers	false

. ~/.vss-cli-complete.bash

After modifying the shell config, you need to start a new shell in order for the changes to be loaded or source the file . ~/.vss-cli-complete.bash.

For zsh:

Save the script somewhere.

Code Block

language	bash
linenumbers	false

export _VSS_APICLI_USER='username'
export VSS_API_USER_PASS='username_password'

...

COMPLETE=zsh_source vss-cli > ~/.vss-cli-complete.zsh

Source the file in ~/.zshrc.

Code Block

language	bash
linenumbers	false

. ~/.vss-cli-complete.zsh

After modifying the shell config, you need to start a new shell in order for the changes to be loaded or source the file . ~/.vss-cli-complete.zsh.

For fish:

Save the script to ~/.config/fish/completions/vss-cli.fish:.

Code Block

language	none
linenumbers	false

_VSS_CLI_COMPLETE=fish_source vss-cli >  ~/.config/fish/completions/vss-cli.fish

After modifying the shell config, you need to start a new shell in order for the changes to be loaded.

Anchor
Source
Source
Anchor
Use-Source
Use-Source
Source

However, there’s also a non-persistent method:

For bash:

Code Block

language	bash
linenumbers	false

source <(vss-cli completion bash)

For zsh:

Code Block

language	bash
linenumbers	false

source <(vss-cli completion zsh)

Anchor
Shell
Shell
Anchor
Use-Shell
Use-Shell
Shell

The VSS CLI provides a REPL interactive shell with tab-completion, suggestions and command history.

Code Block

language	bash
linenumbers	false

Usage: vss-cli shell [OPTIONS]

  REPL interactive shell

Options:
  -i, --history TEXT  File path to save history
  --help              Show this message and exit.

To enter the shell just execute vss-cli shell and you will get the following welcome message:

Code Block

language	pythonbash
linenumbers	false

from pyvss.manager import VssManager
vss = VssManager()
vss.get_token()    __   _____ ___
    \ \ / / __/ __|      API Endpoint: https://vss-api.eis.utoronto.ca/v2
     \ V /\__ \__ \      Tab-completion & suggestions
      \_/ |___/___/      Prefix external commands with "!"
      CLI v2021.5.2      History is saved: /Users/vss/.vss-cli/history

    Exit shell with :exit, :q, :quit, ctrl+d

vss (vss-api) >

Every VSS CLI command, option and argument is available in the shell context. Just exclude the vss-cli command, for instance:

Code Block

language	bash
linenumbers	false

vss (vss-api) > --columns=moref,name compute vm ls -f name=VM

moref    name
-------  ---------------
vm-1270  1910T-TestVM1
vm-1258  1910T-TestVM2
vm-1274  1910T-TestVM3

Versions Compared

Old Version 8

New Version Current

Key

Anchor
Help
Help
Anchor
Use-Help
Use-Help
Help

Command Structure

Parameter Values

Anchor
Common
Common
Anchor
Use-Common
Use-Common
Common

JSON

Command Output

Anchor
Table
Table
Anchor
Use-Table
Use-Table
Table

JSON

Anchor
YAML
YAML
Anchor
Use-YAML
Use-YAML
YAML

Anchor
Auto-completion
Auto-completion
Anchor
Use-Auto-completion
Use-Auto-completion
Auto-completion

Source File

Anchor
Source
Source
Anchor
Use-Source
Use-Source
Source

Anchor
Shell
Shell
Anchor
Use-Shell
Use-Shell
Shell

Page Comparison

Versions Compared

Old Version 8

New Version Current

Key

AnchorHelpHelp AnchorUse-HelpUse-HelpHelp

Command Structure

Parameter Values

AnchorCommonCommon AnchorUse-CommonUse-CommonCommon

JSON

Command Output

AnchorTableTable AnchorUse-TableUse-TableTable

JSON

AnchorYAMLYAML AnchorUse-YAMLUse-YAMLYAML

AnchorAuto-completionAuto-completion AnchorUse-Auto-completionUse-Auto-completionAuto-completion

Source File

AnchorSourceSource AnchorUse-SourceUse-SourceSource

AnchorShellShell AnchorUse-ShellUse-ShellShell

Anchor
Help
Help
Anchor
Use-Help
Use-Help
Help

Anchor
Common
Common
Anchor
Use-Common
Use-Common
Common

Anchor
Table
Table
Anchor
Use-Table
Use-Table
Table

Anchor
YAML
YAML
Anchor
Use-YAML
Use-YAML
YAML

Anchor
Auto-completion
Auto-completion
Anchor
Use-Auto-completion
Use-Auto-completion
Auto-completion

Anchor
Source
Source
Anchor
Use-Source
Use-Source
Source

Anchor
Shell
Shell
Anchor
Use-Shell
Use-Shell
Shell