Summary

Resource	URI	Description
CPU	/vm/<vm-id>/cpu	CPU resource. Get CPU count, quick stats and update cpu count
CPU settings	/vm/<vm-id>/cpu/config	CPU settings. Get and update CPU Hot add/remove setting
Memory	/vm/<vm-id>/memory	Memory resource. Get Memory count, quick stats and update memory size
Firmware	/vm/<vm-id>/firmware	Get or update firmware type.
Disk	/vm/<vm-id>/disk	Disk resource. List, create and delete virtual disks.
Disk Unit	/vm/<vm-id>/disk/<disk_number>	Get specific disk information such as size, controller, provisioning. List update and delete virtual Disk.
Disk Unit Backing	/vm/<vm-id>/disk/<disk_number>/backing	Get physical VMDK file backing and more information.
Disk Unit SCSI controller	/vm/<vm-id>/disk/<disk_number>/scsi	Get and update SCSI adapter of a given disk unit
Disk Unit Sharing	/vm/<vm-id>/disk/<disk_number>/sharing	Get and update Disk Sharing
Controllers	/vm/<vm-id>/controller	IO Controllers including SCSI and IDE
SCSI Controllers	/vm/<vm-id>/controller/scsi	Available SCSI controllers in the VM. Create, list and delete SCSI controllers
SCSI Controller	/vm/<vm-id>/controller/scsi/<bus>	Get a specific SCSI controller info. Update controller type or delete given controller
Floppy	/vm/<vm-id>/floppy	Floppy resource. List available floppy units.
Floppy Number	/vm/<vm-id>/floppy/<unit>	List current Floppy unit and update backend configuration.
CD/DVD	/vm/<vm-id>/cd	CD/DVD resource. List VM cd/dvd units.
CD/DVD Number	/vm/<vm-id>/cd/<unit>	CD/DVD unit resource. List current CD/DVD unit and update backend configuration.
Boot Options	/vm/<vm-id>/boot	Boot resource. Get and update boot configuration options.
Logical Folder	/vm/<vm-id>/folder	Logical Folder resource. Get and update containing folder.
Name	/vm/<vm-id>/name	Instance name. List and update assigned name without VSS prefix
Network Interface Card	/vm/<vm-id>/nic	Network interface list.
Network Interface Card Number	/vm/<vm-id>/nic/<unit>	Network interface unit. List, create, update or delete NIC.
Template	/vm/<vm_uuid/template	Template state. Mark VM as template or template as VM.
Operating System	/vm/<vm_uuid/os	Configured Operating System
Guest	/vm/<vm-id>/guest	Running Guest related configuration
Guest Operating System	/vm/<vm-id>/guest/os	Running Operating System configuration
Guest VMware Tools	/vm/<vm-id>/guest/tools	Guest VMware Tools configuration.
Guest Network	/vm/<vm-id>/guest/net	Guest network configuration.
Guest Network IP	/vm/<vm-id>/guest/net/ip	Guest network Ip address configuration.
Guest Process	/vm/<vm-id>/guest/cmd	Guest running processes or execute program
Guest Process ID	/vm/<vm-id>/guest/cmd/<pid>	Guest process management
State	/vm/<vm-id>/state	Power state.
Domain	/vm/<vm-id>/domain	Fault domain.
Triggered Alarms	/vm/<vm-id>/alarm /vm/<vm-id>/alarm/<moref>	Triggered Alarms. Shows list of triggered alarms. Specific Triggered Alarms. Lists, clears and acknowledges alarm.
Events	/vm/<vm-id>/event /vm/<vm-id>/alarm/<hour_window>	Instance related vCenter events within 1 hour by default.
Note	/vm/<vm-id>/note	Instance Annotation. List raw virtual Machine annotation.
Client Notes	/vm/<vm-id>/note/client	Metadata Client custom notes if any.
Snapshots	/vm/<vm-id>/snapshot /vm/<vm-id>/snapshot/<snapshot_id>	Virtual Machine Snapshot resource. List or create VM snapshots. List, delete and restore from <snapshot_id>
Disk Consolidation	/vm/<vm-id>/snapshot/consolidate	Disk consolidation status. List if disk consolidation is required and execute consolidation
Performance	/vm/<vm-id>/performance	Performance statistics, including datastore IO, memory, CPU and network.
Console	/vm/<vm-id>/console	HTML5 one-time console link.
Export	/vm/<vm-id>/export	OVF export action to vskey-stor.
VMX Version	/vm/<vm-id>/version	Virtual hardware version and upgrade policy.
Extra Configuration	/vm/<vm-id>/extra-config	Manage VMware guestinfo interface options, which are available to the VM guest operating system via VMware Tools.
VSS	/vm/<vm-id>/vss	VSS related metadata.
VSS Admin	/vm/<vm-id>/vss/admin	Administrator. List or update VM admin name and contact info.
VSS Inform	/vm/<vm-id>/vss/inform	Informational contacts. List or update VM informational contacts.
VSS Usage	/vm/<vm-id>/vss/usage	Instance designated usage.
VSS HA Group	/vm/<vm-id>/vss/ha-group	HA group metadata.
VSS Client	/vm/<vm-id>/vss/client	Client Department
VSS Description	/vm/<vm-id>/vss/description	Description
VSS Options	/vm/<vm-id>/vss/option	VSS Options
VSS Service	/vm/<vm-id>/vss/service	VSS Service.
Configuration specification	/vm/<vm-id>/spec	Instance spec. Will dump VM specifications (shell).
Guest OS Customization Specification	/vm/<vm-id>/custom-spec	Guest os customization specification.

<vm-id> is either Managed Object Reference Id or UUID.

TK stores the Cloud API Token generated as a result of the following POST request to the /auth/request-token resource:

curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username>

For example, extracting the token with the jq command:

TK=$(curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username> | jq '.token')

CPU

Resource	URI	Description	GET	POST	PUT	DELETE	OPTIONS*
CPU	/vm/<vm-id>/cpu	Virtual Machine CPU resource. Get CPU count, quick stats and update cpu count

Info

Requesting cpu info can be as easy as making a GET request to /vm/<vm-id>/cpu as shown below:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu"

Respose from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 385
Content-Type: application/json
Date: Wed, 27 Apr 2016 17:47:28 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7179
X-RateLimit-Reset: 1461780000

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu", 
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/"
    }, 
    "data": {
        "coresPerSocket": 1,
        "cpu": 3,
        "hotAdd": {
            "enabled": true
        },
        "hotRemove": {
            "enabled": false
        },
        "quickStats": {
            "overallCpuDemandMHz": 72,
            "overallCpuUsageMHz": 72
        }
    }, 
    "meta": {
        "count": 2, 
        "time": "0.03721s", 
        "user": "jm"
    }
}

Update

Increasing or decreasing CPU and Cores Per Socket can be done by making a PUT request to /vm/<vm-id>/cpu as shown below:

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu" value:=3 "Authorization: Bearer $TK"

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu" -d '{"value": 3}'

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cpu" -d '{"value": {"count": 4, "cores_per_socket": 2}}'

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 397
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:15:08 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/827f4a45-db84-4799-b2f8-a02c85e003be
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7197
X-RateLimit-Reset: 1461783600

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/2", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/827f4a45-db84-4799-b2f8-a02c85e003be"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.03447s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Memory

Resource	URI	Description	GET	POST	PUT	DELETE	OPTIONS*
Memory	/vm/<vm-id>/memory	Virtual Machine Memory resource. Get Memory count, quick stats and update memory size

Info

Requesting memory info can be as easy as making a GET request to /vm/<vm-id>/memory as shown below:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/memory" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/memory"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 555
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:21:25 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7193
X-RateLimit-Reset: 1461783600

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/memory", 
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/"
    }, 
    "data": {
        "hotAdd": {
            "enabled": true,
            "limitGB": 128.0
        },
        "memoryGB": 8.0,
        "quickStats": {
            "balloonedMemoryMB": 0,
            "compressedMemoryKB": 0,
            "consumedOverheadMemoryMB": 59,
            "guestMemoryUsageMB": 737,
            "privateMemoryMB": 8117,
            "sharedMemoryMB": 75,
            "swappedMemoryMB": 0
        }
    },
    "meta": {
        "count": 2, 
        "time": "0.02911s", 
        "user": "jm"
    }
}

Update

Increasing or decreasing CPU can be done by making a PUT request to /vm/<vm-id>/memory as shown below:

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/memory" value:=3 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/memory" -d '{"value": 3}'

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 397
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:15:08 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/0f39fa9f-4f35-426a-8ebb-8f1b34588fef
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7197
X-RateLimit-Reset: 1461783600

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/3", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/0f39fa9f-4f35-426a-8ebb-8f1b34588fef"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.03691s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Virtual Disk

Resource

URI

Description

GET

POST

PUT

DELETE

OPTIONS*

Disk

/vm/<vm-id>/disk

Virtual Machine disk resource. Get VM disks, and capacity.

Disk Number

/vm/<vm-id>/disk/<disk_number>

Virtual Machine disk resource. Get specific disk information such as size, controller, provisioning.

Update size or delete.

List

Virtual Disks can be listed by a GET request to /v2/<vm-id>/disk resource. You will get the list of disks and the Hypermedia reference to the every disk available in the VM:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: HEAD, OPTIONS, GET
Content-Length: 652
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:26:42 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7188
X-RateLimit-Reset: 1461783600

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/", 
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/"
    }, 
    "data": [
        {
            "_links": {
                "self": "http://localhost:5000/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/disk/1"
            },
            "capacityGB": 40.0,
            "unit": "1"
        },
        {
            "_links": {
                "self": "http://localhost:5000/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/disk/2"
            },
            "capacityGB": 100.0,
            "unit": "2"
        }
    ],
    "meta": {
        "count": 2, 
        "time": "0.04253s", 
        "user": "jm"
    }
}

Info

Displaying specific information of a disk such as controller, backing file, provisioning, capacity, etc. can be done by a GET request to /v2/vm/<vm-id>/disk/<disk_number> as shown below:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 688
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:37:30 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7186
X-RateLimit-Reset: 1461783600

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1", 
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/"
    }, 
    "data": [
        {
            "capacityGB": 40, 
            "controller": {
                "type": "LSI Logic", 
                "virtualDeviceNode": "SCSI controller 0:0"
            }, 
            "description": "41,943,040 KB", 
            "fileName": "[datastore1] 1604T-Ubuntu3/1604T-Ubuntu3.vmdk", 
            "label": "Hard disk 1", 
            "provisioning": "Thin", 
            "shares": {
                "level": "normal", 
                "shares": 1000
            }
        }
    ], 
    "meta": {
        "count": 1, 
        "time": "0.04598s", 
        "user": "jm"
    }
}

If requested disk does not exist, you'll get a 404 response status as follows:

HTTP Response

HTTP/1.0 404 NOT FOUND
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 118
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:34:19 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7187
X-RateLimit-Reset: 1461783600
{
    "error": "resource not found", 
    "message": "Hard disk 3 on 1604T-Ubuntu3 could not be found", 
    "status": 404
}

Update

PUT request to /vm/<vm-id>/disk/<disk_number> will submit a change request to update capacity. The following JSON object is expected as request body:

{"attribute": "capacity",
 "value": 200}

The value of the key value is the new size of the Disk in GB.

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" attribute=capacity value=200 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" -d '{"attribute": "capacity", "value": 200}'

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 397
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:58:10 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/2f2b7baf-3abf-48f1-8d16-9dc63641a800
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7178
X-RateLimit-Reset: 1461783600

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/8", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/2f2b7baf-3abf-48f1-8d16-9dc63641a800"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.03962s", 
        "user": "jm"
    }
}

Create

A POST request should be made to /vm/<vm-id>/disk in order to create a disk or multiple with the following JSON object as request body:

{"value": [80, 100, 100]}

The value of the key value is either the new size of the Disk in GB or for advanced setup, the following object structure:

[{"capacity_gb": 80, "backing_mode": "persistent", "backing_sharing": "sharingnone" "backing_vmdk": "<vssUsers_path>"}]

http POST "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk" value:='[80, 100, 100]' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk" -d '{"value": [80, 100, 100]}'

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 397
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:52:23 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/4ecfa88d-1d1a-44fa-bb9b-d0ab04c17691
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7180
X-RateLimit-Reset: 1461783600

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/7", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/4ecfa88d-1d1a-44fa-bb9b-d0ab04c17691"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.03387s", 
        "user": "jm"
    }
}

Delete

To delete a disk or multiple disks you must submit a DELETE request to /vm/<vm-id>/disk/<disk_number> with no request body as follows:

# Just one disk 
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1"


# Disk labels in array
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk" value:='[2,3]' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/disk/1" -d '{"value": [2,3]}'

This action cannot be undone.

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 397
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:52:23 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/4ecfa88d-1d1a-44fa-bb9b-d0ab04c17691
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7180
X-RateLimit-Reset: 1461783600

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/4", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/e1f77e2d-7323-4f6c-a454-ce2450d7b635"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.07853s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Floppy

List

Virtual Floppy units are listed by making a GET request to /v2/<vm_uuid/floppy which will return a list of available units to display further information from:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy"

Response from the API would look something like:

Response Headers

HTTP/1.1 200 OK
Allow: HEAD, OPTIONS, GET
Connection: keep-alive
Content-Length: 521
Content-Type: application/json
Date: Mon, 27 Jun 2016 15:14:16 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2999
X-RateLimit-Reset: 1467043200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607"
    },
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy/1"
            },
            "backing": "client",
            "label": "Floppy drive 1"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.05602s",
        "user": "jm"
    }
}

In this particular case, the floppy unit has no image as backend device.

Info

Displaying specific information of a disk such as controller, backing file, etc. can be done by a GET request to /v2/vm/<vm-id>/floppy/<floppy_number> as shown below:

Response from the API would look something like:

Response Headers

HTTP/1.1 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Connection: keep-alive
Content-Length: 620
Content-Type: application/json
Date: Mon, 27 Jun 2016 15:16:38 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2998
X-RateLimit-Reset: 1467043200

Response Body

{
    "_links": {
        "floppy": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy",
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy/1"
    },
    "data": [
        {
            "backing": "client",
            "connected": "Disconnected",
            "controller": {
                "type": "SIO controller 0",
                "virtualDeviceNode": "SIO controller 0:0"
            },
            "description": "Remote",
            "key": 8000,
            "label": "Floppy drive 1",
            "unit": 0
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.05800s",
        "user": "jm"
    }
}

Update

Virtual Floppy units are not quite used as CD/DVDs, however, when the operating system is Windows and the VM has been configured with Paravirtual SCSI (PVSCSI) controllers, the installer requires to load VMwrare drivers to successfully see all virtual disks attached to PVSCSI controller. The drivers are available to mount from all ESXi hosts in [] /vmimages/floppies.

A PUT request to /vm/<vm-id>/floppy/<floppy_number> will submit a change request to update device backing, meaning client or floppy image. The following JSON object is expected as request body:

# floppy image
{"attribute": "img",
 "value": "[] /vmimages/floppies/pvscsi-Windows2008.flp"}
# client
{"attribute": "client",
 "value": ""}

Making the HTTP request would look like:

httpPUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy/1" attribute=img value='[] /vmimages/floppies/pvscsi-Windows2008.flp' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/floppy/1" -d '{"attribute": "img", "value": "[] /vmimages/floppies/pvscsi-Windows2008.flp"}'

Response from the API would look something like:

Response Headers

HTTP/1.1 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Connection: keep-alive
Content-Length: 431
Content-Type: application/json
Date: Mon, 27 Jun 2016 15:20:10 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/6e52bcc5-0abf-4f12-89ab-5f1e4f17b896
Server: nginx
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2997
X-RateLimit-Reset: 1467043200

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/52",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/6e52bcc5-0abf-4f12-89ab-5f1e4f17b896"
        },
        "message": "VM Change Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.53142s",
        "user": "jm"
    }
}

CD/DVD

List

Virtual CD/DVD units can be listed by a GET request to /v2/<vm-id>/cd resource. You will get the list of cd/dvd and the Hypermedia reference to the every unit available in the VM:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: HEAD, OPTIONS, GET
Content-Length: 652
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:26:42 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7188
X-RateLimit-Reset: 1461783600

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125944-d5e0-248d-0f3c-c499acbeb1ce/cd",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125944-d5e0-248d-0f3c-c499acbeb1ce"
    },
    "data": [
        {
            "_links": {
                "self": "http://localhost:5000/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/cd/1"
            },
            "backing": "[vss-ISOs] Windows/W10/Win10_English_x32.iso",
            "label": "CD/DVD drive 1"
    ],
    "meta": {
        "count": 1,
        "time": "0.05149s",
        "user": "jm"
    }
}

Info

Displaying specific information of a disk such as controller, backing file, etc. can be done by a GET request to /v2/vm/<vm-id>/cd/<cd_number> as shown below:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd/1" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd/1"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 688
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:37:30 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7186
X-RateLimit-Reset: 1461783600

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125944-d5e0-248d-0f3c-c499acbeb1ce/cd/1",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125944-d5e0-248d-0f3c-c499acbeb1ce"
    },
    "data": [
        {
            "backing": "client",
            "connected": "Disconnected",
            "controller": {
                "type": "IDE 1",
                "virtualDeviceNode": "IDE 1:0"
            },
            "description": "Remote device",
            "key": 3002,
            "label": "CD/DVD drive 1",
            "unit": 0
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.04461s",
        "user": "jm"
    }
}

If requested a non existent CD/DVD unit, you'll get a 404 response status as follows:

HTTP Response

HTTP/1.0 404 NOT FOUND
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 118
Content-Type: application/json
Date: Wed, 27 Apr 2016 18:34:19 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7187
X-RateLimit-Reset: 1461783600
{
    "error": "resource not found", 
    "message": "CD/DVD drive 2 on 1604T-Ubuntu3 could not be found", 
    "status": 404
}

Update

A PUT request to /vm/<vm-id>/cd/<cd_number> will submit a change request to update device backing, meaning client or iso image. The following JSON object is expected as request body:

# iso image
{"attribute": "iso",
 "value": "[vss-ISOs] Windows/W10/Win10_English_x32.iso"}
# client
{"attribute": "client",
 "value": ""}

The ISO API resource provides a list of available ISOs to mount to the VM.

Making the HTTP request would look like:

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd/1" attribute=iso value='[vss-ISOs] Windows/W10/Win10_English_x32.iso' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/cd/1" -d '{"attribute": "iso", "value": "[vss-ISOs] Windows/W10/Win10_English_x32.iso"}'

Response from the API would look something like:

Response Headers

HTTP/1.1 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Connection: keep-alive
Content-Length: 428
Content-Type: application/json
Date: Fri, 20 May 2016 18:04:41 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/9b815488-e0d9-4b60-a94f-fe9b0fe46ec7
Server: nginx
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2993
X-RateLimit-Reset: 1463770800

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/18",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/9b815488-e0d9-4b60-a94f-fe9b0fe46ec7"
        },
        "message": "VM Change Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.21971s",
        "user": "jm"
    }
}

Boot Options

The time when you power on the virtual machine, shows up the BIOS and launches the guest operating system software can be unnoticeable, because by default VMware sets up 0ms as boot delay. However, you can edit boot delay options to change that amount of time or to force the virtual machine to enter the BIOS setup screen after power on. This is done using the Boot resource in the RESTful API /vm/<vm-id>/boot.

Resource	URI	Description	GET	POST	PUT	DELETE	OPTIONS*
Boot Options	/vm/<vm-id>/boot	Virtual Machine Boot resource. Get and update boot configuration options.

Info

Showing what's currently configured as boot options is done by making a GET request to /vm/<vm-id>/boot as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/boot" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/boot"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 366
Content-Type: application/json
Date: Wed, 27 Apr 2016 19:07:54 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7199
X-RateLimit-Reset: 1461787200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/boot", 
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/"
    }, 
    "data": {
        "bootDelayMs": 5000, 
        "bootRetryDelayMs": 10000, 
        "enterBIOSSetup": false
    }, 
    "meta": {
        "count": 3, 
        "time": "0.07022s", 
        "user": "jm"
    }
}

Update

Submitting a HTTP request using PUT to /vm/<vm-id>/boot is used to update two boot options: bootdelay, to change that amount of time from powering on to boot into the main device in milliseconds and bootbios, which will force to boot directly to the BIOS setup, boolean. The request body expected is a JSON object as follows:

# boot delay data
{"attribute": "bootdelay",
 "value": 10000}
# boot to bios data
{"attribute": "bootbios",
 "value": true}

Updating VMs boot delay can be done as shown below:

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/boot" attribute=bootdelay value=10000 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/boot" -d '{"attribute": "bootdelay", "value": 10000}'

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 397
Content-Type: application/json
Date: Wed, 27 Apr 2016 19:33:47 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/f5de4b0d-6f00-44ae-870a-e2858134b6d0
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7197
X-RateLimit-Reset: 1461787200

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/9", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/f5de4b0d-6f00-44ae-870a-e2858134b6d0"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.04164s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Logical Folder

This sub resource provides access to containing logical folder object in vCenter.

Resource	URI	Description	GET	POST	PUT	DELETE	OPTIONS*
Folder	/vm/<vm-id>/folder	Virtual Machine containing Folder resource. Get and update containing folder.

Info

Querying which folder is this VM on is done by doing a GET request to /v2/vm/<vm-id>/folder.

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/folder" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/folder"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 508
Content-Type: application/json
Date: Wed, 27 Apr 2016 19:42:16 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7196
X-RateLimit-Reset: 1461787200

The result will provide basic info about the folder such as name, parent and full path. Also, it provides a Hypermedia resource to the main /v2/folder/<moref> resource.

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/folder", 
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/"
    }, 
    "data": {
        "folder": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/folder/group-v4122"
            }, 
            "moref": "group-v4122"
        }, 
        "full_path": "VSS > Sandbox > jm", 
        "name": "jm", 
        "parent": "Sandbox"
    }, 
    "meta": {
        "count": 4, 
        "time": "0.09257s", 
        "user": "jm"
    }
}

Update

Moving a VM to a specific logical folder is done by making a PUT request to /v2/vm/<vm-id>/folder with the moref (Managed object Reference) of the target folder, which can be obtained from the /v2/folder/ resource. The request body expected is a JSON object as shown below:

{"value": "group-v6736"}

Submitting a change request to update VMs logical folder can be done as follows:

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/folder" value=group-v6736 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/folder" -d '{"value": "group-v6736"}'

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 398
Content-Type: application/json
Date: Wed, 27 Apr 2016 19:57:45 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/b3a2c488-ebdb-4d27-9ceb-a5c1d3085672
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7192
X-RateLimit-Reset: 1461787200

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/10", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/b3a2c488-ebdb-4d27-9ceb-a5c1d3085672"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.05744s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Name

Resource	URI	Description	GET	POST	PUT	DELETE	OPTIONS*
Name	/vm/<vm-id>/name	Virtual Machine human readable name. List and update assigned name without VSS prefix

Info

Requesting Name info can be as easy as making a GET request to /vm/<vm-id>/name as shown below:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/name" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/name"

Respose from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 309
Content-Type: application/json
Date: Thu, 28 Apr 2016 19:34:48 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7199
X-RateLimit-Reset: 1461873600

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/name", 
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/"
    }, 
    "data": {
        "name": "1604T-Ubuntu3"
    }, 
    "meta": {
        "count": 1, 
        "time": "0.04409s", 
        "user": "jm"
    }
}

Update

Renaming a Virtual Machine can be done by making a PUT request to /vm/<vm-id>/name as shown below:

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/name" value=Ubuntu4 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/name" -d '{"value": "Ubuntu4"}'

VSS prefix must not be included, if included the API will return a 400 error:

Response

HTTP/1.0 400 BAD REQUEST
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 122
Content-Type: application/json
Date: Thu, 28 Apr 2016 19:37:16 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7198
X-RateLimit-Reset: 1461873600
{
    "message": "New Virtual Machine name must not contain VSS prefix", 
    "options": [
        "value"
    ], 
    "status": 400
}

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 398
Content-Type: application/json
Date: Thu, 28 Apr 2016 17:46:12 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/e84558b9-4d18-41d2-9f4f-3ec873d37441
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7194
X-RateLimit-Reset: 1461866400

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/13", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/e84558b9-4d18-41d2-9f4f-3ec873d37441"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.12066s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Network Interface Card

Resource	URI	Description	GET	POST	PUT	DELETE	OPTIONS*
NIC	/vm/<vm-id>/nic	Virtual Machine nic resource. Get VM nic list.
NIC Number	/vm/<vm-id>/nic/<nic_number>	Virtual Machine specific network interface. List, create, update or delete NIC.

List

Virtual machine nics can be listed making a GET request to /v2/<vm-id>/nic resource. You will get the list of nics and the Hypermedia reference to the actual nic for further actions and properties.

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/nic" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50125d11-a8d6-2af7-c01e-dc6f6be0e607/nic"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: HEAD, OPTIONS, GET
Content-Length: 820
Content-Type: application/json
Date: Thu, 28 Apr 2016 20:42:39 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7184
X-RateLimit-Reset: 1461877200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic", 
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/"
    }, 
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/nic/1"
            },
            "macAddress": "00:50:56:92:71:dc",
            "network": {
                "_links": {
                    "self": "https://vss-api.eis.utoronto.ca/v2/network/dvportgroup-95"
                },
                "moref": "dvportgroup-95"
            },
            "unit": "1"
        }
    ], 
    "meta": {
        "count": 2, 
        "time": "0.59341s", 
        "user": "jm"
    }
}

Info

Displaying NIC specific information such as connection state, network, type, etc. can be done by making a GET request to /v2/vm/<vm-id>/nic/<nic_number> as shown below:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 534
Content-Type: application/json
Date: Thu, 28 Apr 2016 20:47:35 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7181
X-RateLimit-Reset: 1461877200

Response Body

  {
    "address_type": "assigned",
    "connected": true,
    "key": 4000,
    "label": "Network adapter 1",
    "mac_address": "00:50:56:b0:2e:00",
    "network": {
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/network-vc/dvportgroup-1094"
      },
      "moref": "dvportgroup-1094",
      "name": "VL-1228-DCB-MGMT"
    },
    "start_connected": true,
    "type": "vmxnet3",
    "unit": 1
  }

If requested nic does not exist, you'll get a 404 response status as follows:

HTTP Response

HTTP/1.0 404 NOT FOUND
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 124
Content-Type: application/json
Date: Thu, 28 Apr 2016 20:48:33 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7180
X-RateLimit-Reset: 1461877200
{
    "error": "resource not found", 
    "message": "Network adapter 5 on 1604T-Ubuntu2 could not be found", 
    "status": 404
}

Update

There are two updates available to Network Interface Cards: network, state, type. Backend network updates require the Network Managed Object Reference which can be got from /v2/network/ resource, such as dvportgroup-00. NIC state on the other hand, has two options connect and disconnect given NIC. Finally, NIC type means which network adapter should be used between vmxnet3, vmxnet3, e1000, e1000e. Updates to NICs should be made by making a PUT request to /vm/<vm-id>/nic/<nic_number> with the following JSON object as request body:

# update network backend
{"attribute": "network",
 "value": "dvportgroup-00"}
# update state
{"attribute": "state",
 "value": "connect"}
# update nic adapter
{"attribute": "type",
 "value": "vmxnet2"}

For instance, updating NIC 1 type to VMXNET2 is done as follows:

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1" attribute=type value=VMXNET2 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1" -d '{"attribute": "type", "value": "vmxnet2"}'

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 398
Content-Type: application/json
Date: Thu, 28 Apr 2016 20:59:23 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/e6f4313c-5ffa-4e8c-8c52-b368cd08aa62
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7173
X-RateLimit-Reset: 1461877200

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/19", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/e6f4313c-5ffa-4e8c-8c52-b368cd08aa62"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.04027s", 
        "user": "jm"
    }
}

Create

A POST request should be submitted to /vm/<vm-id>/nic in order to create Network Interface Controllers with the Network MOREFs and Network Type in an array as value of the value key in JSON object sent as request body:

{"value": [{"network": "dvportgroup-00"}, {"network": "dvportgroup-01", "type": "vmxnet2"}]}

The value attribute is the Network MOREF.

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic" -d '{"value": [{"network": "dvportgroup-00"}, {"network": "dvportgroup-01", "type": "vmxnet2"}]}'

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 398
Content-Type: application/json
Date: Fri, 29 Apr 2016 02:07:51 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/20e01be9-b91e-4db2-9e0d-66dbe602b536
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7194
X-RateLimit-Reset: 1461898800

Response Body

 {
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/21", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/20e01be9-b91e-4db2-9e0d-66dbe602b536"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.05490s", 
        "user": "jm"
    }
}

Delete

To delete a NIC you must submit a DELETE request to /vm/<vm-id>/nic/<nic_number> with no request body as follows:

http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic/1"


# multiple nic deletion delting network adapter 2 and 3
http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic" value:='[2, 3]' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/nic" -d '{2, 3}'

This action cannot be undone.

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Length: 398
Content-Type: application/json
Date: Fri, 29 Apr 2016 02:05:36 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/372da560-bc66-4ffa-a97e-f0b160a1e26f
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7195
X-RateLimit-Reset: 1461898800

Response Body

 {
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/20", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/372da560-bc66-4ffa-a97e-f0b160a1e26f"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.13275s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Template

Virtual Machine Templates are useful If you create a virtual machine that you want to clone frequently, offering a more secure way of preserving a virtual machine configuration, since they are more difficult to alter than ordinary virtual machine. Templates are commonly referred as Master Copy of certain virtual machine, thus any virtual machine can be marked as template.

Resource	URI	Description	GET	POST	PUT	DELETE	OPTIONS*
Template	/vm/<vm_uuid/template	Virtual Machine Template state. Mark VM as template or template as VM.

Info

In order to verify whether a virtual machine has been marked as template or can be used as template, you just need to submit a GET request to /vm/<vm-id>/template endpoint, resulting in a JSON object with just one attribute: isTemplate which could be either True or False.

http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/template" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/template"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 422
Content-Type: application/json
Date: Fri, 29 Apr 2016 02:22:26 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7193
X-RateLimit-Reset: 1461898800

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/template", 
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/"
    }, 
    "data": {
        "isTemplate": false
    }, 
    "meta": {
        "count": 2, 
        "time": "0.03449s", 
        "user": "jm"
    }
}

Update

Marking a VM as Template or a Template as VM can be done using the PUT method to the template URI /vm/<vm-id>/template. In this case a boolean has to be included as value of the value key in JSON object sent as request body:

# mark vm as template
{"value": true} 
# mark template as vm
{"value": false }

The following example demonstrate how to craft the HTTP request:

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/template" value=true "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/501210c6-7d40-b31f-b326-f66325ca27a0/template" -d '{"value": true}'

Response from the API would look something like:

Response Headers

HTTP/1.0 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 398
Content-Type: application/json
Date: Fri, 29 Apr 2016 02:31:47 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/07bfff5d-d2e6-4a09-a85c-d1cc847eabfc
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7191
X-RateLimit-Reset: 1461898800

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/22", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/07bfff5d-d2e6-4a09-a85c-d1cc847eabfc"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.06570s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Operating System

The virtual machine hardware is presented to the guest operating system based on this setting. It's highly recommended to match the guest OS name or type to ensure the best compatibility and operation.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
OS	/vm/<vm-id>/os	Virtual Machine OS configuration

Info

To obtain the configured operating system, a GET request to the /vm/<vm-id>/os endpoint and the response would include the following attributes:

Attribute	Type	Description
full_name	string	Operating System full name
guest_id	string	Operating system identifier

The following example demonstrate how to query OS information of a given VM:

http GET https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os"

Response from the API would look something like:

Response Headers

HTTP/1.1 200 OK
Allow: HEAD, OPTIONS, GET, PUT
Connection: keep-alive
Content-Length: 315
Content-Type: application/json
Date: Fri, 01 May 2020 13:53:24 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4997
X-RateLimit-Reset: 1588341600
X-VssApi-AppServer: vss-api-prod
X-VssApi-Version: v3.8.1

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998"
    },
    "data": {
        "full_name": "CentOS 8 (64-bit)",
        "guest_id": "centos8_64Guest"
    },
    "meta": {
        "count": 2,
        "time": "0.03548s",
        "user": "jm"
    }
}

Update

To reconfigure the instance operating system make a PUT request to /v2/vm/<vm-id>/os wtih the following payload:

{"value": "guest_id"}

Where guest_id can be obtained from the /v2/os resource, for instance:

http GET "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name,like,Ubuntu%" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os?filter=full_name,like,Ubuntu%"

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name,like,Ubuntu%25"
    },
    "data": [
        {
            "family": "linuxGuest",
            "full_name": "Ubuntu Linux",
            "guest_id": "ubuntuGuest",
            "id": 16
        },
        {
            "family": "linuxGuest",
            "full_name": "Ubuntu Linux (64 bit)",
            "guest_id": "ubuntu64Guest",
            "id": 39
        }
    ],
    "meta": {
        "count": 2,
        "filter": "full_name,like,Ubuntu%",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name%2Clike%2CUbuntu%25&page=1&per_page=10&expand=True",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/os?filter=full_name%2Clike%2CUbuntu%25&page=1&per_page=10&expand=True",
            "next_url": null,
            "page": 1,
            "pages": 1,
            "per_page": 10,
            "prev_url": null,
            "total": 2
        },
        "time": "0.00299s",
        "user": "jm"
    }
}

Updating the instance operating system would include the guest_id provided:

Virtual Machine must be powered Off.

Updating OS to ubuntu 64 bit

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os" value=ubuntu64Guest "Authorizatio: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os" -d '{"value": "ubuntu64Guest"}'

Response from the API would look something like:

Response Headers

HTTP/1.1 202 ACCEPTED
Allow: HEAD, OPTIONS, GET, PUT
Cache-Control: private, no-cache, no-store, max-age=0
Connection: keep-alive
Content-Length: 518
Content-Type: application/json
Date: Fri, 01 May 2020 14:31:59 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/9a65b490-23cb-4192-96c2-7d5da94341c7
Server: nginx
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4993
X-RateLimit-Reset: 1588345200
X-VssApi-AppServer: vss-api-prod
X-VssApi-Version: v3.8.1

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/os",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998"
    },
    "data": {
        "full_name": "CentOS 8 (64-bit)",
        "guest_id": "centos8_64Guest"
    },
    "meta": {
        "count": 2,
        "time": "0.03548s",
        "user": "jm"
    }
}

Guest

Guest related attributes are handled by the /v2/<vm-id>/guest resource, this includes hostname, guest state, main ip address, network configuration, VMware Tools status and Operating System configured.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Guest	/vm/<vm-id>/guest	Virtual Machine Guest related configuration

Info

To display guest information, do a GET request to /vm/<vm-id>/guest endpoint, resulting in a JSON object with the following attributes:

Attribute	Type	Description
guest_pperations_ready	boolean	Guest Operations availability. If true, the virtual machine is ready to process guest operations.
guest_state	string	Operation mode of guest operating system. One of: running - Guest is running normally. shuttingdown - Guest has a pending shutdown command. resetting - Guest has a pending reset command. standby - Guest has a pending standby command. notrunning - Guest is not running. unknown - Guest information is not available.
hostname	string	Main hostname if any. Requires VMware Tools or equivalent installed and running.
ip_address	string	List of ip addresses. Requires VMware Tools or equivalent installed and running.
network	object	Reference to Guest Network configuration resource.
os	object	Reference to Operating System resource and guestId.
tools	object	Reference to VMware Tools detailed status and current running status.

The following example demonstrate how to query Guest basic information of a given VM:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest"

Response from the API would look something like:

Response Headers

HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD
Connection: keep-alive
Content-Length: 1204
Content-Type: application/json
Date: Fri, 01 May 2020 14:33:08 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4991
X-RateLimit-Reset: 1588345200
X-VssApi-AppServer: vss-api-prod
X-VssApi-Version: v3.8.1

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998"
    },
    "data": {
        "cmd": {
            "_links": {
                "pid": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest/cmd/1234",
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest/cmd"
            }
        },
        "guest_operations_ready": true,
        "guest_state": "running",
        "hostname": "localhost",
        "ip_address": [
            "192.168.2.2",
            "fe80::c88e:cad7:a4c4:4ced"
        ],
        "network": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest/net"
            }
        },
        "os": {
            "_links": {
                "os": "https://vss-api.eis.utoronto.ca/v2/os",
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest/os"
            },
            "full_name": "CentOS 8 (64-bit)",
            "guest_id": "centos8_64Guest"
        },
        "tools": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest/tools"
            },
            "running_status": "guestToolsRunning"
        }
    },
    "meta": {
        "count": 8,
        "time": "0.02256s",
        "user": "jm"
    }
}

Guest Operating System

Guest Operating System related attributes are handled by the /v2/<vm-id>/guest/os resource, this includes guest family, guest full name and guest id.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Guest Operating System	/vm/<vm-id>/guest/os	Virtual Machine Guest Operating System configuration

Info

To display guest operating system information, do a GET request to /vm/<vm-id>/guest/os endpoint, resulting in a JSON object with the following attributes:

Name	Type	Description
guest_family	string	Guest operating system family, if known.
guest_full_name	string	Guest operating system full name, if known.
guest_id	string	Guest operating system identifier (short name), if known.

The following example demonstrate how to query Guest basic information of a given VM:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/os" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/os"

Response from the API would look something like:

Response Headers

HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD
Connection: keep-alive
Content-Length: 371
Content-Type: application/json
Date: Fri, 01 May 2020 14:34:36 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4990
X-RateLimit-Reset: 1588345200
X-VssApi-AppServer: vss-api-prod
X-VssApi-Version: v3.8.1

Response Body

{
    "_links": {
        "guest": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest",
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest/os"
    },
    "data": {
        "guest_family": "linuxGuest",
        "guest_full_name": "CentOS 8 (64-bit)",
        "guest_id": "centos8_64Guest"
    },
    "meta": {
        "count": 3,
        "time": "0.03377s",
        "user": "jm"
    }
}

Guest VMware Tools

VMware Tools is a suite of utilities that enhances the performance of the virtual machines guest operating system and improves management of the virtual machine (Source: VMware). With this resource, you can display current guest operating system VMware Tools status including its running status, installation status, and version status. Also, it provides an interface to mount, unmount and even upgrade from the packaged version in vSphere.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Guest VMware Tools	/vm/<vm-id>/guest/tools	Virtual Machine Guest VMware Tools configuration.

Info

To display the guest operating system VMware Tools information, do a GET request to /vm/<vm-id>/guest/tools endpoint, resulting in a JSON object with the following attributes:

Attribute

Type

Description

running_status

string

Current running status of VMware Tools in the guest operating system, if known.

guestToolsExecutingScripts - VMware Tools is starting.
guestToolsNotRunning - VMware Tools is not running.
guestToolsRunning - VMware Tools is running.

Source: VMware.

version

string

Current version of VMware Tools, if known.

version_status

string

Current version status of VMware Tools in the guest operating system, if known.

guestToolsBlacklisted - VMware Tools is installed, but the installed version is known to have a grave bug and should be immediately upgraded.
guestToolsCurrent VMware Tools is installed, and the version is current.
guestToolsNeedUpgrade - VMware Tools is installed, but the version is not current.
guestToolsNotInstalled - VMware Tools has never been installed.
guestToolsSupportedNew - VMware Tools is installed, supported, and newer than the version available on the host.
guestToolsSupportedOld - VMware Tools is installed, supported, but a newer version is available.
guestToolsTooNew - VMware Tools is installed, and the version is known to be too new to work correctly with this virtual machine.
guestToolsTooOld - VMware Tools is installed, but the version is too old.
guestToolsUnmanaged - VMware Tools is installed, but it is not managed by VMWare.

Source VMware.

The following example demonstrate how to query VMware Tools information of a given VM:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/5012accf-3e3d-a5f5-32cf-8a9d4c2ddc25/guest/tools" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/5012accf-3e3d-a5f5-32cf-8a9d4c2ddc25/guest/tools"

Response from the API would look something like:

Response Headers

HTTP/1.1 200 OK
Allow: HEAD, OPTIONS, GET, PUT
Connection: keep-alive
Content-Length: 373
Content-Type: application/json
Date: Fri, 01 May 2020 14:35:28 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4989
X-RateLimit-Reset: 1588345200
X-VssApi-AppServer: vss-api-prod
X-VssApi-Version: v3.8.1

Response Body

{
    "_links": {
        "guest": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest",
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/vm-17998/guest/tools"
    },
    "data": {
        "running_status": "guestToolsRunning",
        "version": "10346",
        "version_status": "guestToolsUnmanaged"
    },
    "meta": {
        "count": 3,
        "time": "0.02015s",
        "user": "jm"
    }
}

Update

Making a PUT request to /v2/<vm-id>/guest/tools would Mount, Unmount and Upgrade only vSphere packaged versions of VMware Tools. These tasks are commonly executed on virtual machines with Windows based guest operating systems. For popular Linux based VMs, VMware recommends to use Open VM Tools (open-vm-tools) which is the open source implementation of VMware Tools, however if there is any particular Linux distribution without OVTs available, it should use vSphere packaged version.

Changes to tis resource require the VM to be powered on. Otherwise, the following error will be thrown by the API:

{
    "error": "vSphere exception", 
    "message": "Virtual Machine must be powered on to mount, unmount or upgrade VMWare Tools.", 
    "status": 500
}

In order to mount, unmount and automatically upgrade vSphere packaged VMware Tools version, the following JSON object with the attribute value should be sent via a PUT request to /v2/vm/<vm-id>/guest/tools:

{"value": 'mount'} 
{"value": 'unmount'} 
{"value": 'upgrade'}

For demonstration purposes, the following example will mount and unmount vSphere packaged VMware Tools version.

The following example demonstrate how to craft the HTTP request:

Mounting and unmounting VMware Tools with HTTPie

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/tools" value=mount "Authorization: Bearer $TK"
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/tools" value=unmount "Authorization: Bearer $TK"

Mounting and unmounting VMware Tools with CURL

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/tools" -d '{"value": "mount"}'
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/tools" -d '{"value": "unmount"}'

Response from the API would look something like:

Response Headers

HTTP/1.1 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Connection: keep-alive
Content-Length: 427
Content-Type: application/json
Date: Tue, 03 May 2016 01:59:23 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/c46bd473-376e-48ec-b804-58aa3f7b0d7d
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7194
X-RateLimit-Reset: 1462240800

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/4", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/c46bd473-376e-48ec-b804-58aa3f7b0d7d"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.35895s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Guest Network

VMware Tools provides an interface between the Hypervisor and the Guest Operating System, so there's certain information that can be pulled from the OS such as networking configuration including IP and Mac addresses, virtual network and connection state. This information can be gotten by the /v2/<vm-id>/guest/net resource:

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Guest Network	/vm/<vm-id>/guest/net	Virtual Machine Guest network configuration.

Info

To display the network information provided by the Guest OS, do a GET request to /vm/<vm-id>/guest/net endpoint, resulting in a JSON object with the following attributes:

Attribute	Type	Description
connected	boolean	Flag indicating whether or not the virtual device is connected.
ipAddress	array	IPv4 address is specified using dotted decimal notation. For example, "192.0.2.1". IPv6 addresses are 128-bit addresses represented as eight fields of up to four hexadecimal digits. A colon separates each field (:). For example, 2001:DB8:101::230:6eff:fe04:d9ff. The address can also consist of the symbol '::' to represent multiple 16-bit groups of contiguous 0's only once in an address as described in RFC 2373.
macAddress	string	MAC address of the adapter.
nic	string	Reference to nic associated

The following example demonstrate how to query Network information of a given VM:

http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net"  "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: HEAD, OPTIONS, GET
Content-Length: 2550
Content-Type: application/json
Date: Fri, 06 May 2016 13:26:29 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2991
X-RateLimit-Reset: 1462543200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net",
        "guest": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest"
    },
    "data": [
        {
            "connected": true,
            "ipAddress": [
                "1.2.3.5",
                "fe80::250:56ff:fe92:71dc"
            ],
            "macAddress": "00:50:56:92:71:dc",
            "nic": {
                "_links": {
                    "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/nic/1"
                },
                "label": "Network adapter 1"
            }
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.03571s",
        "user": "jm"
    }
}

Guest Network IP

Guest operating system network ip addresses configuration reported via VMware tools.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Guest Network IP	/vm/<vm-id>/guest/net/ip	Virtual Machine Guest network IP configuration.

Info

To list any ip address configured do a GET request to /vm/<vm-id>/guest/net/ip endpoint, resulting in a JSON object with the following attributes:

Attribute	Type	Description
origin	string	How this address was configured: dhcp: The address is configured through dhcp. linklayer: The address is obtained through stateless autoconfiguration (autoconf). manual: The address is configured manually. The term 'static' is a synonym. other: Any other type of address configuration other than the below mentioned ones will fall under this category. random: The address is chosen by the system at random.
ipAddress	array	IPv4 address is specified using dotted decimal notation. For example, "192.0.2.1". IPv6 addresses are 128-bit addresses represented as eight fields of up to four hexadecimal digits. A colon separates each field (:).
macAddress	string	MAC address of the adapter.
state	string	The state of ipAddress: deprecated: Indicates that this is a valid but deprecated address that should no longer be used as a source address. duplicate: Indicates the address has been determined to be non-unique on the link, this address will not be reachable. inaccessible: Indicates that the address is not accessible because interface is not operational. invalid: Indicates that this isn't a valid. preferred: Indicates that this is a valid address. tentative: Indicates that the uniqueness of the address on the link is presently being verified. unknown: Indicates that the status cannot be determined.

The following example demonstrate how to query IP address information of a given VM:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net/ip" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net/ip"

The following response body is expected from the API:

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net/ip",
        "net": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/guest/net"
    },
    "data": [
        {
            "ipAddress": "12.12.12.12",
            "macAddress": "00:50:56:92:71:dc",
            "origin": null,
            "state": "preferred"
        },
        {
            "ipAddress": "fe80::250:56ff:fe92:71dc",
            "macAddress": "00:50:56:92:71:dc",
            "origin": null,
            "state": "unknown"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.03571s",
        "user": "jm"
    }
}

Guest Process

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.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Guest Process	/vm/<vm-id>/guest/cmd	Virtual Machine running processes.
Guest Process ID	/vm/<vm-id>/guest/cmd/<pid>	Virtual Machine Guest OS running process ID

Info

To list running processes the following JSON object must be provided:

Attribute	Type	Description	Required
user	string	Guest OS username
pass	string	Guest OS username password

Passwords are not save when querying processes but they are when submitting a command, however they are encrypted.

The following example demonstrate how to query running processes information of a given VM:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd" user='OSUser' pass='plain-text-pass' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd" -d '{"user": "OSUser", "pass": "plain-text-pass"}'

Response from the API would look something like:

Response Headers

HTTP/1.1 200 OK
Allow: HEAD, POST, OPTIONS, GET
Connection: keep-alive
Content-Length: 13844
Content-Type: application/json
Date: Tue, 12 Jul 2016 14:39:10 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2994
X-RateLimit-Reset: 1468335600

Response Body

{
    "_links": {
        "guest": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest",
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd"
    },
    "data": [  
    {
      "cmdLine": "/usr/lib/postfix/master",
      "pid": 1292,
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1292"
      }
    },
    {
      "cmdLine": "qmgr -l -t unix -u",
      "pid": 1303,
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1303"
      }
    },
    {
      "cmdLine": "/usr/bin/redis-server 127.0.0.1:0          ",
      "pid": 1312,
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312"
      }
    },
    {
      "cmdLine": "/usr/sbin/snmpd -Lsd -Lf /dev/null -u snmp -g snmp -I -smux mteTrigger mteTriggerConf -p /var/run/snmpd.pid",
      "pid": 1340,
      "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1340"
      }
     ....
    ],
    "meta": {
        "count": 161,
        "time": "0.25291s",
        "user": "jm"
    }
}

If you wish to display more about any give process, just append the pid to the /v2/vm/<uuid>/guest/cmd/<pid> URI as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" user='OSUser' pass='plain-text-pass' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" -d '{"user": "OSUser", "pass": "plain-text-pass"}'

Response from the API will look like:

Response Headers

HTTP/1.1 200 OK
Allow: HEAD, DELETE, OPTIONS, GET
Connection: keep-alive
Content-Length: 583
Content-Type: application/json
Date: Tue, 12 Jul 2016 14:51:40 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2989
X-RateLimit-Reset: 1468335600

Response Body

{
    "_links": {
        "guest": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest",
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312"
    },
    "data": [
        {
            "cmdLine": "/usr/bin/redis-server 127.0.0.1:0          ",
            "endTime": null,
            "exitCode": null,
            "name": "redis-server 127.0.0.1:0",
            "owner": "redis",
            "pid": 1312,
            "startTime": "2016-07-05 15:22:18"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.14681s",
        "user": "jm"
    }
}

Response body's data section contains the following attributes:

Attribute	Type	Description
cmdLine	string	program executed
endTime	string	If the process was started using the API then the process completion time will be available if queried within 5 minutes after it completes.
pid	integer	Process Id
owner	string	Process owner
name	string	Process name
exitCode	integer	If the process was started using the API then the process exit code will be available if queried within 5 minutes after it completes.

Create

The API also allows to execute a command in the guest operating system. In order to do so, you

Attribute	Type	Description
user	string	Guest OS username to execute command
pass	string	Guest OS username password
cmd	string	Command to be executed
args	string	The arguments to the program.
workDir	string	The absolute path of the working directory for the program to be run.
env	string	List of environment variables, specified in the guest OS notation

The minimum JSON payload sent via the POST method would be something like the following object:

{"user": "guest-os-username",
 "pass": "guest-os-username-pass",
 "cmd": "/bin/dd",
 "args": "if=/dev/zero of=/tmp/f.out count=10000"}

Submitting the change request is shown below:

http POST "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" user='OSUser' pass='plain-text-pass' cmd='/bin/dd' args='if=/dev/zero of=/tmp/f.out count=10000' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" -d '{"user": "OSUser", "pass": "plain-text-pass" "cmd": "/bin/dd", "args": "if=/dev/zero of=/tmp/f.out count=10000"}'

The request will be processed and you will get a PID number if was successfully executed. Validating the exit code and running times can be done by making a GET request to the /vm/<uuid>/guest/cmd/<pid> as previously described.

{
    "_links": {
        "guest": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest",
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/14146"
    },
    "data": [
        {
            "cmdLine": "\"/bin/dd\" if=/dev/zero of=/tmp/f.out count=10000",
            "endTime": "2016-07-12 12:09:44",
            "exitCode": 0,
            "name": "dd",
            "owner": "osuser",
            "pid": 14146,
            "startTime": "2016-07-12 12:09:43"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.13282s",
        "user": "jm"
    }
}

Update

Killing a running process through the API is possible by making a DELETE request appending the pid to the /v2/vm/<uuid>/guest/cmd/<pid> URI as follows:

http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" user='OSUser' pass='plain-text-pass' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50120fb0-f47d-eef7-5c04-f98a801c2e6b/guest/cmd/1312" -d '{"user": "OSUser", "pass": "plain-text-pass"}'

Response from the API would look something like:

Response Body

    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/110",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/9efa6769-ba4c-42ee-8ba4-a5a01bb38973"
        },
        "message": "VM Change Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.09880s",
        "user": "jm"
    }
}

State

The state resource provides information about the execution state and history of a virtual machine.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
State	/vm/<vm-id>/state	Virtual Machine power and running state.

Info

To display the execution state information, do a GET request to /vm/<vm-id>/state endpoint, resulting in a JSON object with the following attributes:

Attribute	Type	Description
powerState	string	The current power state of the virtual machine.
connectionState	string	The connectivity state of a virtual machine. connected - The server has access to the virtual machine. disconnected - The server is currently disconnected from the virtual machine, since its host is disconnected. See general comment for this enumerated type for more details. inaccessible - One or more of the virtual machine configuration files are inaccessible. For example, this can be due to transient disk failures. In this case, no configuration can be returned for a virtual machine. invalid - The virtual machine configuration format is invalid. Thus, it is accessible on disk, but corrupted in a way that does not allow the server to read the content. In this case, no configuration can be returned for a virtual machine. orphaned - The virtual machine is no longer registered on the host it is associated with. For example, a virtual machine that is unregistered or deleted directly on a host managed by vCenter shows up in this state. Source VMware
bootTime	string	The timestamp when the virtual machine was most recently powered on.
domain	object	Fault domain the virtual machine is running on.

The following example demonstrate how to query State information of a given VM:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state"  "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: HEAD, OPTIONS, GET
Content-Length: 2550
Content-Type: application/json
Date: Fri, 06 May 2016 13:26:29 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2991
X-RateLimit-Reset: 1462543200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050"
    },
    "data": {
        "_links": {
            "self": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state"
        },
        "bootTime": "Wed, 02 Mar 2016 13:57:07 GMT",
        "connectionState": "connected",
        "domain": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/domain/domain-c4252"
            },
            "name": "FD2"
        },
        "powerState": "poweredOn"
    },
    "meta": {
        "count": 5,
        "time": "0.21312s",
        "user": "jm"
    }
}

Update

Currently, making a PUT request to /vm/<uuid>/state can update both power state and guest OS state to either poweredOn, poweredOff, reset or shutdown, reboot respectively. The following table describes each supported option and its effect on the virtual machine.

Option	Type	Description	VMware Tools Running
poweredOn	string	Powers on this virtual machine. If the virtual machine is suspended, this method resumes execution from the suspend point.	-
poweredOff	string	Powers off this virtual machine. If this virtual machine is a fault tolerant primary virtual machine, this will result in the secondary virtual machine(s) getting powered off as well.	-
reset	string	Resets power on this virtual machine. If the current state is poweredOn, then this method first performs powerOff(hard). Once the power state is poweredOff, then this method performs powerOn(option).
shutdown	string	Issues a command to the guest operating system asking it to perform a clean shutdown of all services.
reboot	string	Issues a command to the guest operating system asking it to perform a reboot.

In order to update the state of any given VM, a request body must be sent in JSON format via a PUT request to /v2/vm/<vm-id>/state specifying a key named value and the desired state string, for instance:

{"value": "poweredOn"} 
{"value": "poweredOff"} 
{"value": "reset"} 
{"value": "shutdown"} 
{"value": "reboot"}

For demonstration purposes, the following example will power On and power Off a virtual machine.

The following example shows how to craft the HTTP request:

Powering Off and ON VM with HTTPie

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state" value=poweredOn "Authorization: Bearer $TK"
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state" value=poweredOff "Authorization: Bearer $TK"

Powering Off and ON VM with CURL

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state" -d '{"value": "poweredOn"}'
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/state" -d '{"value": "poweredOff"}'

Response from the API would look something like:

Response Headers

HTTP/1.1 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Connection: keep-alive
Content-Length: 427
Content-Type: application/json
Date: Tue, 03 May 2016 01:59:23 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/c46bd473-376e-48ec-b804-58aa3f7b0d7d
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7194
X-RateLimit-Reset: 1462240800

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/4", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/c46bd473-376e-48ec-b804-58aa3f7b0d7d"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.35895s", 
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

Domain

Virtual machine fault domain is also available through the API.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Domain	/vm/<vm-id>/domain	Virtual Machine fault domain.

Info

Obtaining the current fault domain where a virtual machine is running on, do a GET request to the /vm/<vm-id>/domain endpoint. The response contains a reference to the fault domain with the following attributes:

Attribute	Type	Description
name	string	Fault domain name.
moref	string	Managed object reference of the fault domain

The following example demonstrates how to query a given virtual machine fault domain:

http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/domain"  "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/domain"

Response from the API would look something like:

Response Headers

HTTP/1.1 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Connection: keep-alive
Content-Length: 491
Content-Type: application/json
Date: Thu, 26 Jan 2017 02:08:52 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4998
X-RateLimit-Reset: 1485399600

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/domain",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1"
    },
    "data": {
        "domain": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/domain/domain-c5877"
            },
            "moref": "domain-c5877",
            "name": "FD3"
        }
    },
    "meta": {
        "count": 1,
        "time": "0.45940s",
        "user": "jm"
    }
}

Update

Migrating a virtual machine to another fault domain is possible by making a PUT request to the /v2/vm/<vm-id>/domain resource, specifying target domain moref. In order to proceed with the virtual machine relocation, it's required to be in a powered off state, thus, there is also the option to force if the VM is powered on by including the boolean attribute in the JSON payload force. After migrating, the virtual machine can be powered on by the migration task if the boolean attribute poweron is included. Refer to the following table to summarize what attributes should be included in the domain migration request:

Attribute	Type	Description
value	string	Target fault domain managed object reference (moref)
poweron	boolean	Power on after migrating.
force	boolean	Will shutdown guest or power off VM if not able to migrate.

The following example payload will send a GuestOS shutdown signal, if the OS does not shut down, it will power off the VM, start the migration and power on the virtual machine when complete.

{"value": "domain-c5877",
 "poweron": true,
 "force": true}

The following example shows how to craft the HTTP PUT request with the required JSON payload:

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/domain" value=domain-c5877 poweron:=true force:=true "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/domain" -d '{"value": "domain-c5877", "poweron": true, "force": true} '

Response from the API would look something like:

Response Headers

HTTP/1.1 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Connection: keep-alive
Content-Length: 427
Content-Type: application/json
Date: Tue, 03 May 2016 01:59:23 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/c46bd473-376e-48ec-b804-58aa3f7b0d7d
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7194
X-RateLimit-Reset: 1462240800

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/4", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/c46bd473-376e-48ec-b804-58aa3f7b0d7d"
        }, 
        "message": "VM Change Request has been accepted for processing", 
        "name": "Accepted", 
        "state": "Submitted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.35895s", 
        "user": "jm"
    }
}

Triggered Alarms

The Virtual Machine alarm resource provides information about any triggered alarms, as well methods to acknowledge and clear them.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Triggered alarm	/vm/<vm-id>/alarm	Virtual Machine specific Triggered Alarms.
Specific triggered alarm	/vm/<vm-id>/alarm/<moref>	Lists, clears and acknowledges alarm.

Info

To show any triggered alarms related to a given virtual machine, do a GET request to /vm/<vm-id>/alarm endpoint, resulting in a JSON object with the following attributes:

Attribute	Type	Description
dateTime	string	Timestamp the alarm triggered.
moref	string	Managed object reference of the alarm
name	string	Alarm name.
overallStatus	string	Overall status of the alarm object. gray - The status is unknown. green - The entity is OK. red - The entity definitely has a problem. yellow - The entity might have a problem. Source VMware

The following example demonstrate how to query Triggered Alarms of a given VM:

http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm"  "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: HEAD, OPTIONS, GET
Content-Length: 2550
Content-Type: application/json
Date: Fri, 06 May 2016 13:26:29 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2991
X-RateLimit-Reset: 1462543200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050"
    },
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6"
            },
            "dateTime": "2016-05-06 09:35:30",
            "moref": "alarm-6",
            "name": "Virtual machine CPU usage",
            "overallStatus": "yellow"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.03050s",
        "user": "jm"
    }
}

Now, to get further information about the alarm, follow the self attribute value within the _links attribute, which appends the Managed Object Reference (moref) of the alarm to the URI, as follows:

http $TK GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6"

In the response object, you will find even more alarm related attributes described in the following table:

Attribute	Type	Description
acknowledged	boolean	Flag to indicate if the alarm's actions have been acknowledged for the associated
acknowledgedByUser	string	The user who acknowledged this triggering. If the triggering has not been acknowledged, then the value is not valid.
acknowledgedDateTime	string	The time this triggering was acknowledged. If the triggering has not been acknowledged, then the value is not valid.

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 2550
Content-Type: application/json
Date: Fri, 06 May 2016 13:26:29 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2991
X-RateLimit-Reset: 1462543200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm"
    },
    "data": [
        {
            "acknowledged": false,
            "acknowledgedByUser": null,
            "acknowledgedDateTime": null,
            "dateTime": "2016-05-06 09:35:30",
            "name": "Virtual machine CPU usage",
            "overallStatus": "yellow"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.03930s",
        "user": "josem"
    }
}

Update

Currently, making a PUT request to /vm/<uuid>/alarm/<moref> can acknowledge or clear given alarm.

Acknowledging the alarm can be done by specifying either ack or clear value for the attribute value as shown below:

{"value": 'ack'} 
{"value": 'clear'}

For demonstration purposes, the following example will Acknowledge and then Clear a virtual machine triggered alarm.

Acknowledge and clear alarm with HTTPie

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6" value=ack "Authorization: Bearer $TK"
http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6" value=clear "Authorization: Bearer $TK"

Acknowledge and clear alarm with CURL

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6"" -d '{"value": "ack"}'
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6"" -d '{"value": "clear"}'

ACK alarm via PUT request - Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/2",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/c510469d-b045-4221-bdb0-41ce65507cea"
        },
        "message": "VM Change Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.17118s",
        "user": "jm"
    }
}

After Acknowledging Alarm - Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm/alarm-6",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/alarm"
    },
    "data": [
        {
            "acknowledged": true,
            "acknowledgedByUser": "VSKEY5\\vssvmauto",
            "acknowledgedDateTime": "2016-05-06 10:40:08",
            "dateTime": "2016-05-06 09:35:30",
            "name": "Virtual machine CPU usage",
            "overallStatus": "yellow"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.02807s",
        "user": "jm"
    }
}

When displaying the alarm information you can see two attributes have been populated: acknowledgedByUser and acknowledgedDateTime. This means the alarm has been successfully Acknowledged, besides of checking the status

After Clearing Alarm - Response Body

{
    "error": "resource not found",
    "message": "No alarms were found for VM-NAME",
    "status": 404
}

Events

This resource provides information about vCenter events related to a specific virtual machine within a time frame.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
vCenter events	/vm/<vm-id>/event	Virtual Machine related vCenter events within 1 hour by default.

Info

To list any vCenter events related to a given virtual machine, do a GET request to /vm/<vm-id>/event endpoint, this will query all events within 1 hour by default, resulting in a JSON object with the following attributes:

Attribute	Type	Description
createdTime	string	Timestamp of event
message	string	What kind of activity is this message related to.
userName	string	Username executing this task. If not specified, it has been created by vCenter.

Querying events of a given virtual machine can be done as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/event" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/event"

If no timeframe was specified, 1 hour is used as default value and sometimes it does not return any event. In such case you will get a 404 error as follows:

Response Headers

HTTP/1.0 404 NOT FOUND
Allow: HEAD, OPTIONS, GET
Content-Length: 2550
Content-Type: application/json
Date: Fri, 06 May 2016 13:26:29 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2991
X-RateLimit-Reset: 1462543200

Response Body

{
    "error": "resource not found",
    "message": "No events were found for 1605T-furious_brown",
    "status": 404
}

Appending the number of hours to the URI, you will query the events within N hours. In the following example uses 2 as a time window:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/event/2" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/event/2"

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/event",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952"
    },
    "data": {
        events": [
            {
                "createdTime": "2016-05-06 09:49:17",
                "message": "Task: Power Off virtual machine",
                "userName": "VSKEY5\\vssvmauto"
            },
            {
                "createdTime": "2016-05-06 09:49:17",
                "message": "1605T-furious_brown on  esxi-3-1.dcb.eis.utoronto.ca in EIS-DCB is stopping",
                "userName": "VSKEY5\\vssvmauto"
            },
            {
                "createdTime": "2016-05-06 09:49:18",
                "message": "Changed resource allocation for 1605T-furious_brown",
                "userName": ""
            },
            {
                "createdTime": "2016-05-06 09:49:19",
                "message": "1605T-furious_brown on  esxi-3-1.dcb.eis.utoronto.ca in EIS-DCB is powered off",
                "userName": "VSKEY5\\vssvmauto"
            },
            {
                "createdTime": "2016-05-06 09:49:19",
                "message": "Alarm 'Virtual machine CPU usage' on 1605T-furious_brown changed from Green to Gray",
                "userName": ""
            },
            {
                "createdTime": "2016-05-06 09:49:19",
                "message": "Task: Reconfigure virtual machine",
                "userName": "VSKEY5\\vssvmauto"
            },
            {
                "createdTime": "2016-05-06 09:49:19",
                "message": "Alarm 'Virtual machine memory usage' on 1605T-furious_brown changed from Green to Gray",
                "userName": ""
            },
            {
                "createdTime": "2016-05-06 09:49:20",
                "message": "Reconfigured 1605T-furious_brown on esxi-3-1.dcb.eis.utoronto.ca in EIS-DCB",
                "userName": "VSKEY5\\vssvmauto"
            },
            {
                "createdTime": "2016-05-06 09:49:26",
                "message": "Virtual machine 1605T-furious_brown in cluster FD3 in EIS-DCB is not vSphere HA Protected.",
                "userName": ""
            },
            "hours": 2
        ],
    },
    "meta": {
        "count": 9,
        "time": "0.23674s",
        "user": "jm"
    }
}

Client Notes

This resource provides information about the virtual machine Client Custom Notes, which is used to store any string provided by the user.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Client Notes	/vm/<vm-id>/note/client	Virtual Machine Client custom notes if any.

Update

A PUT request to /vm/<uuid>/note/client with attribute value will update, delete existing client notes. A JSON object is the value expected which could be either in pure JSON format or sent as a string. Examples of JSON objects are show below:

{"value": "BillingCode: 12345"}

The following example shows how to craft the HTTP request to add the BillingCode custom note with value 12345:

Creating Custom client tag with HTTPie

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note/client" value='BillingCode: 12345'  "Authorization: Bearer $TK"

Creating Custom client tag with CURL

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note/client" -d '{"value": "BillingCode: 12345"}'

ACK alarm via PUT request - Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/2",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/c510469d-b045-4221-bdb0-41ce65507cea"
        },
        "message": "VM Change Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.07118s",
        "user": "jm"
    }
}

Remember you can check task and request status by making a GET request to /v2/request/task/<task_id> and /v2/request/change/<change_id> respectively.

List

Listing existent Custom Client notes can be done by making a GET request to the /vm/<vm-id>/client/note as shown below:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note/client"  "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note/client"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 2550
Content-Type: application/json
Date: Fri, 06 May 2016 13:26:29 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2991
X-RateLimit-Reset: 1462543200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note/client",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/note"
    },
    "data": {
        "value": "Backup: True \nBillingCode: 312341"
    },
    "meta": {
        "count": 2,
        "time": "0.04391s",
        "user": "jm"
    }
}

Performance

Basic performance counters can be gotten from /vm/<vm-id>/performance resource. The only restriction is that the virtual machine has to be powered On, otherwise an error will be thrown.

Resource	URI	Description
Performance	/vm/<vm-id>/performance	Virtual Machine performance statistics, including datastore IO, memory, CPU and network.
CPU	/vm/<vm-id>/performance/cpu	CPU relevant performance counters
Memory	/vm/<vm-id>/performance/memory	Memory relevant performance counters
Datastore	/vm/<vm-id>/performance/io	Datastore relevant performance counters
Network	/vm/<vm-id>/performance/net	Network relevant performance counters

Recommended reading: vSphere Memory Management.

Making a HTTP GET request to /vm/<vm-id>/performance will result in a JSON object with the following attributes:

Attribute	Type	Description
cpu	object	Virtual Machine CPU statistics readyAvgPct - Average percentage of time the virtual machine was ready but could not be scheduled to run on a physical CPU. readyMaxPct - Percentage of time that the virtual machine was ready but could not be scheduled to run on a physical CPU usagePct - Percentage of CPU usage
datastore	object	Virtual Machine IO stats from datastore. readIops - VM IOPs read on datastore. writeIops - VM IOPs write on datastore. latReadMs - VM read latency in milliseconds on datastore latWriteMs - VM write latency in milliseconds on datastore
dateTime	string	Timestamp of performance stats.
memory	object	Virtual Machine memory statistics. activeMb - Megabytes active. activePct - Percentage of memory in active state. balloonMb - Megabytes ballooned. balloonPct - Percentage of memory in balloon state. sharedMb - Megabytes shared. sharedPct - Percentage of memory shared. swappedMb - Megabytes swapped. swappedPct - Percentage of memory in swapped. usagePct - Percentage of memory in use.
name	string	Virtual machine name.
network	object	Network Errors and traffic rxErrors - Errors received txErrors - Errors transferred. rxMbps - Megabits per second received. txMbps - Megabits per second transferred.

Getting performance stats using the API can be obtained by structuring a GET request to the performance endpoint as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/performance" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/performance"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 2550
Content-Type: application/json
Date: Fri, 06 May 2016 13:26:29 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2991
X-RateLimit-Reset: 1462543200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/performance",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050"
    },
    "data": {
        "cpu": {
            "readyAvgPct": 0.1674,
            "readyMaxPct": 0.65,
            "usagePct": 6.9649
        },
        "datastore": {
            "ioReadIops": 6.1778,
            "ioWriteIops": 4.5556,
            "latReadMs": 5.5778,
            "latWriteMs": 6.2889
        },
        "dateTime": "2016-05-07T01:51:19.400079+00:00",
        "memory": {
            "activeMb": 731.8,
            "activePct": 11.9108,
            "balloonMb": 0.0,
            "balloonPct": 0.0,
            "sharedMb": 0.2667,
            "sharedPct": 0.0043,
            "swappedMb": 0.0,
            "swappedPct": 0.0,
            "usagePct": 11.0
        },
        "name": "1409P-hoth",
        "network": {
            "rxErrors": 0.0,
            "rxMbps": 0.0667,
            "txErrors": 0.0,
            "txMbps": 0.0
        }
    },
    "meta": {
        "count": 6,
        "time": "1.35133s",
        "user": "jm"
    }
}

Console

This resource will generate a Virtual Machine HTML5 one-time valid URL to copy and paste it in your preferred browser, so you avoid going through the vSphere web client.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Console	/vm/<vm-id>/console	Virtual Machine HTML5 one-time console link.

To generate a console link you just need to have a valid vSphere session (unfortunately), and this is due to the nature of vSphere API.

A link will be generated by making a GET request to /vm/<vm-id>/console as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/console" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50127974-aa4a-c215-f9f0-e1ab8a4ef050/console"

Response from the API would look something like:

HTTP/1.0 200 OK
Allow: HEAD, OPTIONS, GET
Content-Length: 594
Content-Type: application/json
Date: Fri, 06 May 2016 18:00:19 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2999
X-RateLimit-Reset: 1462561200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952/console",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50122608-711e-f0ae-028d-2973b6648952"
    },
    "data": {
        "value": "<really_long_link>"
    },
    "meta": {
        "count": 1,
        "time": "1.23062s",
        "user": "jm"
    }
}

Version

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Hardware Version	/vm/<vm-id>/version	Upgrade hardware version or upgrade policy

List

Listing current virtual hardware version (VMX) can be done by making a GET request to the /vm/<vm-id>/version as shown below:

curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/version"

Response from the API would look something like:

Response Headers

HTTP/1.0 200 OK
Allow: PUT, HEAD, OPTIONS, GET
Content-Length: 2550
Content-Type: application/json
Date: Fri, 06 May 2016 13:26:29 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2991
X-RateLimit-Reset: 1462543200

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/version",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd"
    },
    "data": {
        "status": "ok",
        "upgrade_policy": {
            "fault": null,
            "scheduledHardwareUpgradeStatus": "none",
            "upgradePolicy": "never"
        },
        "value": "vmx-10"
    },
    "meta": {
        "count": 3,
        "time": "0.06124s",
        "user": "jm"
    }
}

Update

Currently two attributes are supported by the resource /vm/<vm-id>/version:

Attribute	Description
version	Virtual machine hardware version
upgrade_policy	Virtual machine upgrade policy. Specifies whether to upgrade the virtual machine hardware to the lates versiont on always, never, onSoftPowerOff

Before performing a virtual machine hardware upgrade, it is highly recommended to take a snapshot in case of any eventuality.

To submit a change request and update the version to the latest virtual hardware, do a PUT request to /vm/<vm-id>/version resource:

curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/version" -d '{"attribute": "version", "value": "vmx-13"}'

After submitting the request, a task will be created as any other change request.

To update the upgrade_policy, just use the proper attribute-value setting as follows:

curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/version" -d '{"attribute": "upgrade_policy", "value": "onSoftPowerOff"}'

When the onSoftPowerOff policy has been se to the virtual machine upgrade_policy, the virtual machine hardware upgrade will happen on next shut down.

ExtraConfig

This resource provides all methods to create VMware **guestinfo** interface options, which are available to the VM guest operating system via VMware Tools with the following command:

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

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Extra Config	/vm/<vm-id>/extra-config	Manage VMware guestinfo interface options.

List

To obtain current available options, perform a GET request to /vm/<vm-id>/extra-config:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config"

Response from the API would look something like:

HTTP/1.1 200 OK
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Content-Encoding: gzip
Content-Length: 314
Content-Type: application/json
Date: Fri, 12 Jul 2019 16:31:14 GMT
Server: gunicorn/19.7.1
Vary: Accept-Encoding
X-Ratelimit-Limit: 5000
X-Ratelimit-Remaining: 4993
X-Ratelimit-Reset: 1562950800
X-Vssapi-Appserver: e207c7a693bf
X-Vssapi-Version: v2.3.37

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8"
    },
    "data": [
        {
            "key": "guestinfo.vmtools.buildNumber",
            "value": "7253323"
        },
        {
            "key": "guestinfo.vmtools.description",
            "value": "open-vm-tools 10.2.0 build 7253323"
        },
        {
            "key": "guestinfo.vmtools.versionNumber",
            "value": "10304"
        },
        {
            "key": "guestinfo.vmtools.versionString",
            "value": "10.2.0"
        }
    ],
    "meta": {
        "count": 4,
        "time": "0.05335s",
        "user": "jm"
    }
}

Create

Extra config entries are based in key-value objects, thus a json object is expected in the payload in order to create valid keys, for instance:

{"key1": "value1"}

The request to the API would be via POST to /vm/<vm-id>/extra-config with the json object in the value attribute:

http POST https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" value:='{"key": "value"}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" -d '{"value": {"key": "value"}}'

Response from the API would look something like:

HTTP/1.1 202 Accepted
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Cache-Control: private, no-cache, no-store, max-age=0
Content-Encoding: gzip
Content-Length: 282
Content-Type: application/json
Date: Fri, 12 Jul 2019 16:29:51 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/344dccce-8d7e-4cb2-a17d-942b743284c3
Server: gunicorn/19.7.1
Vary: Accept-Encoding
X-Ratelimit-Limit: 5000
X-Ratelimit-Remaining: 4994
X-Ratelimit-Reset: 1562950800
X-Vssapi-Appserver: c143fbd7e313
X-Vssapi-Version: v2.3.37

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/16931",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/344dccce-8d7e-4cb2-a17d-942b743284c3"
        },
        "message": "Request has been accepted for processing",
        "name": "Accepted",
        "request": {
            "id": 16931,
            "status": "IN_PROGRESS",
            "task_id": "344dccce-8d7e-4cb2-a17d-942b743284c3"
        },
        "status": 202
    },
    "meta": {
        "time": "0.14286s",
        "user": "jm"
    }
}

Update

Just like creating, the required payload to update an existing entry is a JSON object (dictionary). The request to the API would be via PUT to /vm/<vm-id>/extra-config with the json object in the value attribute:

http PUT https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" value:='{"key": "value"}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" -d '{"value": {"key": "value"}}'

Response from the API would look something like:

HTTP/1.1 202 Accepted
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Cache-Control: private, no-cache, no-store, max-age=0
Content-Encoding: gzip
Content-Length: 283
Content-Type: application/json
Date: Fri, 12 Jul 2019 16:31:23 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/30bdd085-01d8-42b5-81b7-3fcfec3b9329
Server: gunicorn/19.7.1
Vary: Accept-Encoding
X-Ratelimit-Limit: 5000
X-Ratelimit-Remaining: 4992
X-Ratelimit-Reset: 1562950800
X-Vssapi-Appserver: c143fbd7e313
X-Vssapi-Version: v2.3.37

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/16932",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/30bdd085-01d8-42b5-81b7-3fcfec3b9329"
        },
        "message": "Request has been accepted for processing",
        "name": "Accepted",
        "request": {
            "id": 16932,
            "status": "IN_PROGRESS",
            "task_id": "30bdd085-01d8-42b5-81b7-3fcfec3b9329"
        },
        "status": 202
    },
    "meta": {
        "time": "0.16964s",
        "user": "jm"
    }
}

Delete

Deleting entries is simpler, just add a list of keys to the JSON payload in the value attribute:

["key1", "key2"]

The request to the API would be via DELETE to /vm/<vm-id>/extra-config with the json object in the value attribute:

http PUT https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" value:='["key"]' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/5012c92a-3dac-cd2f-ce56-bda704ca51b8/extra-config" -d '{"value": ["key"]}'

Response from the API would look something like:

HTTP/1.1 202 Accepted
Allow: HEAD, GET, PUT, POST, OPTIONS, DELETE
Cache-Control: private, no-cache, no-store, max-age=0
Content-Encoding: gzip
Content-Length: 283
Content-Type: application/json
Date: Fri, 12 Jul 2019 16:31:23 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/30bdd085-01d8-42b5-81b7-3fcfec3b9329
Server: gunicorn/19.7.1
Vary: Accept-Encoding
X-Ratelimit-Limit: 5000
X-Ratelimit-Remaining: 4992
X-Ratelimit-Reset: 1562950800
X-Vssapi-Appserver: c143fbd7e313
X-Vssapi-Version: v2.3.37

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/16932",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/30bdd085-01d8-42b5-81b7-3fcfec3b9329"
        },
        "message": "Request has been accepted for processing",
        "name": "Accepted",
        "request": {
            "id": 16932,
            "status": "IN_PROGRESS",
            "task_id": "30bdd085-01d8-42b5-81b7-3fcfec3b9329"
        },
        "status": 202
    },
    "meta": {
        "time": "0.16964s",
        "user": "jm"
    }
}

Export

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Export OVF	/vm/<vm-id>/export	Virtual Machine OVF export action to vskey-stor.

VMware vSphere provides the ability to export virtual machines for use in other software through the Export feature. The export virtual machine resource will automate the Export process generating an Open Virtualization Format (OVF) and will transfer it to your account space in https://vskey-stor.eis.utoronto.ca. A virtual machine qualifies to be exported if used storage is less than 200G and power state is Off.

OVF is a platform-independent, efficient, extensible, and open packaging and distribution format for virtual machines. OVF format provides a complete specification of the virtual machine, including the full list of required virtual disks and the required virtual hardware configuration, including CPU, memory, networking, and storage. Source VMware

To request an export make a POST request to /vm/<vm-id>/export as follows:

http POST "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/export" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/export"

Response from the API would look something like:

HTTP/1.0 202 ACCEPTED
Allow: POST, OPTIONS
Content-Length: 397
Content-Type: application/json
Date: Fri, 06 May 2016 18:42:29 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/1b5b82b3-30f8-4be2-8302-e6d458a92d6f
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2989
X-RateLimit-Reset: 1462561200

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/export/1",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/1b5b82b3-30f8-4be2-8302-e6d458a92d6f"
        },
        "message": "VM Export Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.06711s",
        "user": "jm"
    }
}

When the Export Request completes, go to https://vskey-stor.eis.utoronto.ca, login with your VSKEY credentials and you will find a directory named after the exported virtual machine Uuid which will contain OVF and VMDK files. OVF contains all the VM configuration and VMDK files are the exported disks.

Snapshots

The /v2/vm/<vm_uuid/snapshot resource allows you to manage in a simplified manner virtual machine snapshots, including basic activities such as list, create, delete and revert to a particular snapshot.

Recommended reading Virtual Machine - Attributes

As described in the following table, there are two URIs to deal with /vm/<vm-id>/snapshot which lists virtual machine snapshots, if any, and creates snapshots in a particular point in time. On the other hand /vm/<vm-id>/snapshot/<snapshot_id> provides information about the requested snapshot_id, allows you to manually delete it or even restore the virtual machine state to that particular snapshot.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Snapshots	/vm/<vm-id>/snapshot	Virtual Machine Snapshot resource. List or create VM snapshots.
Snapshot	/vm/<vm-id>/snapshot/<snapshot_id>	List, delete and restore from <snapshot_id>

List

Listing existent snapshots can be done by making a GET request to /vm/<vm-id>/snapshot:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot"

The API response would contain a list of JSON objects with two attributes _links and name:

Response Body

{
    "_links": {
        "self": "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot",
        "vm": "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd"
    },
    "data": [
        {
            "_links": {
                "self": "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/20"
            },
            "name": "SR-24"
        },
        {
            "_links": {
                "self": "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19"
            },
            "name": "SR-23"
        }
    ],
    "meta": {
        "count": 2,
        "time": "0.04350s",
        "user": "jm"
    }
}

Following the URI included in the JSON list, shows further attributes of a particular snapshot:

Attribute	Type	Description
age	string	Timedelta from the time taken to now.
createTime	string	Timestamp when the snapshot was taken.
description	string	Snapshot description
fileKeys	array	Disks keys involved in the snapshot.
id	integer	Snapshot id.
name	string	Snapshot name.
quiesced	boolean	Whether the file system was quiesced in the virtual machine
sizeGB	integer	Snapshot size in GB.
powerState	string	Virtual machine power state.

A GET request to /vm/<vm-id>/snapshot/<snapshot_id> would get previously described attributes in the response.

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19"

API response would look like:

Response Body

{
    "_links": {
        "self": "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19",
        "vm": "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot"
    },
    "data": [
        {
            "age": "0:53:48.061533",
            "createTime": "2016-05-11 10:13:14",
            "description": "Testing snapshot once again from 2016-05-11 10:10:00-04:00 valid for 1",
            "fileKeys": [
                3,
                4,
                9
            ],
            "id": 19,
            "name": "SR-23",
            "quiesced": false,
            "sizeGB": 0,
            "powerState": "poweredOff"
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.04783s",
        "user": "jm"
    }
}

Create

To submit a snapshot request, you should create a POST request to /vm/<vm-id>/snapshot with the following attributes in form of a JSON object:

Attribute	Type	Description
from_date	string	Timestamp with the following format %Y-%m-%d %H:%M. If date is in the past, the snapshot will be taken right away, otherwise it will wait.
valid_for	integer	Number of hours (max 72) the snapshot will live
description	string	A brief description of the snapshot.

An example of a JSON object is show below:

{"from_date": "2016-05-11 10:20",
 "valid_for": 72,
 "description": "before upgrading very important module"}

Crafting the POST request should look something like:

http POST "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot" valid_for=73 from_date='2016-05-11 10:20' description='before upgrading very important module' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X POST "https://vss-ws.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot" -d '{"from_date": "2016-05-11 10:20", "valid_for": 72, "description": "before upgrading very important module"}'

In this case, the snapshot will be deleted 72 hours after from_date, this is 2016-05-14 10:20.

If an invalid date or parameter value is submitted, HTTP 400 errors would be returned:

{
    "message": "According to VSS best practices, the maximum lifetime should be 72 hours.",
    "status": 400
}

After submitting the request, a confirmation will be returned and this time, it will not contain a task ID, just a request_id:

HTTP/1.0 202 ACCEPTED
Allow: HEAD, POST, OPTIONS, GET
Content-Length: 318
Content-Type: application/json
Date: Wed, 11 May 2016 14:07:00 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2998
X-RateLimit-Reset: 1462978800

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/snapshot/23"
        },
        "message": "VM Snapshot Create Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.40076s",
        "user": "jm"
    }
}

To monitor your snapshot creation/deletion, you can get further information by making a GET request to /v2/request/snapshot/<request_id>

Delete

Snapshot deletion is scheduled and it will be executed as soon as the validity time has expired, however, if there's the need to manually delete it, you can make a DELETE request to /vm/<vm-id>/snapshot/<snapshot_id> with no data.

http DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X DELETE "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19"

After submitting the request, a confirmation will be returned and this time, it will not contain a task ID, just a request_id:

HTTP/1.0 202 ACCEPTED
Allow: HEAD, GET, PATCH, OPTIONS, DELETE
Content-Length: 318
Content-Type: application/json
Date: Wed, 11 May 2016 14:07:00 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2998
X-RateLimit-Reset: 1462978800

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/snapshot/24"
        },
        "message": "VM Snapshot Delete Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.30076s",
        "user": "jm"
    }
}

To monitor your snapshot creation/deletion, you can get further information by making a GET request to /v2/request/snapshot/<request_id>

Revert

Reverting to a given snapshot is done by making a PATCH request to /vm/<vm-id>/snapshot/<snapshot_id> with no data.

http PATCH "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X PATCH "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/19"

After submitting the request, a confirmation will be returned and this time, it will not contain a task ID, just a request_id:

HTTP/1.0 202 ACCEPTED
Allow: HEAD, GET, PATCH, OPTIONS, DELETE
Content-Length: 318
Content-Type: application/json
Date: Wed, 11 May 2016 14:07:00 GMT
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2998
X-RateLimit-Reset: 1462978800

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/snapshot/25"
        },
        "message": "VM Snapshot Revert Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.30076s",
        "user": "jm"
    }
}

To monitor your snapshot request, you can get further information by making a GET request to /v2/request/snapshot/<request_id>

Disk Consolidation

When you initiate a Delete or DeleteAll operation on snapshots, the snapshot is immediately deleted, then the backing virtual machine disk .vmdk files are consolidated on-disk. If the consolidation fails [during snapshot deletion], some Virtual Disk files may remain on disk and/or be actively used on the Datastore, consuming storage capacity. (Source: VMware).

Recommended reading Consolidating snapshots in vSphere 5.x/6.0

The /v2/vm/<vm_uuid/snapshot/consolidate resource provides a simple interface to know whether virtual machine disks require consolidation via GET method and also, executes disk consolidation on demand via PUT method as shown in the following table:

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Disk consolidation	/vm/<vm-id>/snapshot/consolidate	Virtual Machine Disk consolidation resource

Virtual machine disk consolidation is based on finding hierarchies of redo logs that can be combined without violating data dependency. The redundant redo logs after merging are then deleted. Consolidation improves I/O performance since less number of virtual disk files need to be traversed; it also reduces the storage usage.

List

To validate whether a virtual machine requires disk consolidation, a GET request to the URI /vm/<vm-id>/snapshot/consolidate can be done as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/consolidate" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/consolidate"

In this case, only one attribute is returned in the JSON object data, called requireDiskConsolidation, which is a flag to indicate whether or not disk must be consolidated

Response Body

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/consolidate",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot"
    },
    "data": {
        "requireDiskConsolidation": true
    },
    "meta": {
        "count": 1,
        "time": "0.02662s",
        "user": "jm"
    }
}

Update

If disk consolidation is required, a simple PUT request to the /vm/<vm-id>/snapshot/consolidate URI should be submitted.

Additional space is temporarily required to perform the operation. Consolidation can be I/O intensive, it is advisable to invoke this operation when guest is not under heavy I/O usage.

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/consolidate" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/snapshot/consolidate"

After submitting the request, a task will be created as any other change and the Response from the API should look something like:

HTTP/1.1 202 ACCEPTED
Allow: PUT, HEAD, OPTIONS, GET
Connection: keep-alive
Content-Length: 427
Content-Type: application/json
Date: Tue, 10 May 2016 14:01:15 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/d603ca15-2b40-4c82-b3f2-8965bb2903aa
Server: nginx
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2999
X-RateLimit-Reset: 1462892400

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/change/3",
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/d603ca15-2b40-4c82-b3f2-8965bb2903aa"
        },
        "message": "VM Change Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.20812s",
        "user": "jm"
    }
}

After disk consolidation is complete, requireDiskConsolidation flag has changed to false.

VSS Client/Billing Department

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Usage	/vm/<vm-id>/vss/client	Virtual Machine Client/Billing Department.

List

Getting the current VSS Client or Billing department is done by making a HTTP request to /v2/vm/<vm-id>/vss/client as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client"

The API response would contain a list of JSON objects with two attributes _links and data:

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss"
    },
    "data": {
        "value": "EIS"
    },
    "meta": {
        "count": 1,
        "time": "0.14646s",
        "user": "jm"
    }
}

Update

Updating a given virtual machine Billing Department/Client is easily accomplished by submitting a PUT request to the /v2/vm/<vm-id>/vss/client resource and providing the new usage in the payload as follows:

Updating VSS usage

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client" value:='{"value": "VSS"}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client" -d '{"value": "VSS"}'

VSS VM Description

The virtual machine description is part of the VSS Metadata that helps to provide context about the software or service of the virtual machine.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Description	/vm/<vm-id>/vss/description	Virtual Machine Description.

List

Getting the current VSS Description is done by making a HTTP request to /v2/vm/<vm-id>/vss/description as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/description" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/description"

The API response would contain a list of JSON objects with two attributes _links and data:

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/description",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss"
    },
    "data": {
         "value": "Graylog2 server for log analysis"
    },
    "meta": {
        "count": 1,
        "time": "0.14646s",
        "user": "jm"
    }
}

Update

Updating a given virtual machine Description is easily accomplished by submitting a PUT request to the /v2/vm/<vm-id>/vss/description resource and providing the new usage in the payload as follows:

Updating VSS usage

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/description" value:='{"value": "Logstash server to collect logs, parse them, and store them for later use."}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/client" -d '{"value": "Logstash server to collect logs, parse them, and store them for later use."}'

The description has a minimum of 50 and maximum of 200 characters of length.

VSS Usage

Part of the VSS metadata and the name prefix (YYMMP-) is composed by the virtual machine usage, which is intended to specify whether it will be hosting a Production, Development, QA, or Testing system.

Resource	URI	Description	GET	POST	PUT	DELETE	PATCH	OPTIONS*
Usage	/vm/<vm-id>/vss/usage	Virtual Machine usage.

List

Getting the current VSS usage is done by making a HTTP request to /v2/vm/<vm-id>/vss/usage as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage"

The API response would contain a list of JSON objects with two attributes _links and data:

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss"
    },
    "data": {
        "value": "Prod"
    },
    "meta": {
        "count": 1,
        "time": "0.14646s",
        "user": "jm"
    }
}

Update

Updating a given virtual machine usage is easily accomplished by submitting a PUT request to the /v2/vm/<vm-id>/vss/usage resource and providing the new usage in the payload as follows:

Updating VSS usage

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage" value:='{"value": "Prod"}' "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage" -d '{"value": "Prod"}'

Options used in the value parameter are:

Prod, prd, Prd, prod
Test, testing, Testing
Dev, dev
QA, qa

Previos action will trigger a change in the VSS prefix used in the name of the virtual machine, as well as in the VSS metadata.

VSS Admin

Getting the current VSS admin is done by making a HTTP request to /v2/vm/<vm-id>/admin as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/admin" "Authorization: Bearer $TK"

curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/admin"

The API response would contain a list of JSON objects with two attributes _links and data:

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/usage",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss"
    },
    "data": {
        "email": "jm@eis.utoronto.ca",
        "name": "JM Lopez",
        "phone": "416-123-1234"
    },
    "meta": {
        "count": 1,
        "time": "0.14646s",
        "user": "jm"
    }
}

Update

Updating a given virtual machine VSS VM admin is easily accomplished by submitting a PUT request to the /v2/vm/<vm-id>/vss/admin resource and providing the new VM admin in the payload as follows:

Updating VSS usage

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/admin" value:='{"value": "JM Lopez:416-123-2123:jm@eis.utoronto.ca"}' "Authorization: Bearer $TK"

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/admin" -d '{"value": "JM Lopez:416-123-2123:jm@eis.utoronto.ca"}'

The VM admin is in the following format "<full_name>:<phone_number>:<email_address>"

VSS Inform

Part of the VSS Metadata in the virtual machine is composed by the informational contacts, which can be obtained by a request to /v2/vm/<vm-id>/vss/inform:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/inform" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/inform"

The response contains a list of JSON objects with two attributes _links and data:

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/inform",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss"
    },
    "data": [
        "jm@eis.utoronto.ca"
    ],
    "meta": {
        "count": 1,
        "time": "0.06006s",
        "user": "jm"
    }
}

Update

Updating a given virtual machine VSS Informational contacts is done by submitting a PUT request to the /v2/vm/<vm-id>/vss/inform resource and providing the new VM informational email list, followed by whether this list will be appended or replaced in the payload as follows:

Updating VSS usage

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/inform" value="jm.lopez@utoronto.ca,jm@eis.utoronto.ca" append:=false "Authorization: Bearer $TK"

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/inform" -d '{"value": "jm.lopez@utoronto.ca,jm@eis.utoronto.ca", "append": False}'

VSS Service

Part of the VSS Metadata in the virtual machine is composed by VSS Service, which can be obtained by a request to /v2/vm/<vm-id>/vss/service:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/service" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/service"

The response contains a list of JSON objects with two attributes _links and data:

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/service",
        "vss": "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss"
    },
    "data": {
        "_links": {
            "self": "https://vss-api.eis.utoronto.ca/v2/vss/service/57"
        },
        "description": "VMware virtual server & storage hosting",
        "id": 57,
        "name": "Virtual Server Service",
        "service_group_id": 7
    },
    "meta": {
        "count": 5,
        "time": "0.07775s",
        "user": "jm"
    }
}

Update

Updating a given virtual machine VSS Service is done by submitting a PUT request to the /v2/vm/<vm-id>/vss/service resource and providing the new VSS Service ID or Label. Then, the first step is to look up the VSS Service as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,%Cloud%&expand=1" $TK

The response includes the following objects:

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,%25Cloud%25&expand=1"
    },
    "data": [
        {
            "created_on": "2019-03-11T19:27:31.921275Z",
            "description": "Central Backup Service",
            "group": {
                "description": "Infrastructure as a Service (IaaS)",
                "id": 7,
                "name": "ITS Private Cloud Infrastructure"
            },
            "id": 56,
            "label": "ITS Private Cloud Infrastructure/UTORbackup",
            "name": "UTORbackup",
            "updated_on": "2019-04-15T16:28:24.371791Z"
        },
        {
            "created_on": "2019-03-11T19:27:32.246834Z",
            "description": "VMware virtual server & storage hosting",
            "group": {
                "description": "Infrastructure as a Service (IaaS)",
                "id": 7,
                "name": "ITS Private Cloud Infrastructure"
            },
            "id": 57,
            "label": "ITS Private Cloud Infrastructure/Virtual Server Service",
            "name": "Virtual Server Service",
            "updated_on": "2019-04-15T16:28:24.396338Z"
        }
    ],
    "meta": {
        "count": 2,
        "filter": "label,like,%Cloud%",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label%2Clike%2C%25Cloud%25&per_page=10&page=1&expand=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label%2Clike%2C%25Cloud%25&per_page=10&page=1&expand=1",
            "next_url": null,
            "page": 1,
            "pages": 1,
            "per_page": 10,
            "prev_url": null,
            "total": 2
        },
        "time": "0.00535s",
        "user": "jm"
    }
}

Once we get the proper label "ITS Private Cloud Infrastructure/Virtual Server Service" or ID 57, we can proceed to submit the change request to update the attributre in the virtual machine:

Updating VSS usage

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/service" value:=57 "Authorization: Bearer $TK"

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/service" -d '{"value": 57}'

VSS HA Group

VSS metadata includes the HA Group tag, which helps to identify which virtual machine instances should be separated into different fault domains with the end goal being that if there's an unforeseen outage in one fault domain which takes out one VM, then the associated redundant virtual machines in other resource zones would not be affected. For example, if you have three front-end HA proxy setup in a load-balance situation, the HA group feature would indicate which VMs should be migrated to other resource zones so that neither of the VMs have any resources in common. Having that, virtual machine migration from fault domains require the instance to be powered off, this feature does not cause automatic VM migration, but only identifies which VMs should be separated and in case of any missing association, then associated.

Obtaining the current state of a given ha_group can be done through the /v2/vm/<vm-id>/vss/ha_group resource.

http GET "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/ha_group" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/ha_group"

The response contains a list of JSON objects with two attributes _links and data:

{
    "_links": {
        "self": "http://vss-api.eis.utoronto.ca/v2/vm/501220a5-a091-1866-9741-664236067142/vss/ha_group",
        "vss": "http://vss-api.eis.utoronto.ca/v2/vm/501220a5-a091-1866-9741-664236067142/vss"
    },
    "data": {
        "count": 1,
        "valid": true,
        "vms": [
            {
                "_links": {
                    "self": "http://vss-api.eis.utoronto.ca/v2/vm/50128577-2026-908a-7bb7-df5a34fea7bf"
                },
                "name": "1610T-cranky_sinoussi",
                "uuid": "50128577-2026-908a-7bb7-df5a34fea7bf",
                "valid": true
            }
        ]
    },
    "meta": {
        "count": 3,
        "time": "0.12620s",
        "user": "jm"
    }
}

The following table describes each of the "data" attributes:

Attribute	Description
count	Count of virtual machines related to the current vm
valid	Overall status of ha group vm association.
vms	Virtual machines associated
vms[*].name	Related virtual machine name. Null if by any reason it does not exist.
vms[*].uuid	Related virtual Machine uuid.
vms[*].valid	Related virtual machine valid status. True if association is mutual.

A background task kicks in every hour for full vm association status and domain separation. If HA group is not valid, by domain separation or association you will receive an email as follows:

Update

Updating a virtual machine HA Group is done by submitting a PUT request to the /v2/vm/<vm-id>/vss/ha_group resource and providing the related virtual machine UUID list, followed by whether this list will be appended or replaced in the payload as follows:

Updating HA group

http PUT "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/vss/ha_group" value:='["be693fa9-af28-4849-b3e1-dc4fa629d128", "79c8325d-5696-45d0-bcde-2c1f6d6cffed"]' append:=false "Authorization: Bearer $TK"

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/vss/ha_group" -d '{"value": ["be693fa9-af28-4849-b3e1-dc4fa629d128", "79c8325d-5696-45d0-bcde-2c1f6d6cffed"], "append": False}'

Configuration Specification

The sole purpose of the configuration specification resource /v2/vm/<vm-id>/spec is to provide the given virtual machine relevant attributes to carbon-copy a virtual machine without its data. Therefore, the resource is available only through the GET method. The following lines exemplify how to obtain a virtual machine configuration spec:

http GET "https://vss-api.eis.utoronto.ca/v2/vm/50128d83-0fcc-05e3-be71-d972ffdf3284/spec" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vm/50128d83-0fcc-05e3-be71-d972ffdf3284/spec"

Response would be something similar as shown below:

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/50128d83-0fcc-05e3-be71-d972ffdf3284/spec",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/50128d83-0fcc-05e3-be71-d972ffdf3284"
    },
    "data": {
        "admin_email": "jm@sub.utoronto.ca",
        "admin_name": "JM Lopez Lujan",
        "admin_phone": "123-123-132",
        "client": "EIS",
        "built_from": "os_install",
        "cpu": 1,
        "description": "Testing Goes OS identifier integrity",
        "disks": [
            40,
            1
        ],
        "domain": "domain-c000",
        "folder": "group-v000",
        "inform": "emails@sub.utoronto.ca",
        "memory": 1,
        "name": "vm-name",
        "networks": [
            "dvportgroup-000"
        ],
        "os": "ubuntu64Guest",
        "usage": "Testing"
    },
    "meta": {
        "count": 16,
        "time": "0.55575s",
        "user": "jm"
    }
}

An example on how to use the configuration spec is detailed in this KB article Virtual Machine - Attributes.

Guest OS Customization Specification

One of the most recent features is allowing to reconfigure a virtual machine (change Hostname, and NIC IP address configuration automatically by processing these changes through VMware Tools) from first boot after being deployed by the Guest Operating System Customization Specification. However, this feature can be also executed on a given virtual machine instance if the VM power state is OFF. One common use case is repurposing a virtual machine instance or moving a virtual machine from one network to another without accessing the guest operating system.

The customization specification consists of the following key value items:

Attribute	Value type	Description	Required
hostname	string	Valid hostname.
domain	string	Valid domain.
dns	list	List of dns servers in string. Priority is set by order	only if dhcp is false
interfaces	list	List of interface objects
poweron	boolean	Power on instance after submitting customization spec	-

Attribute	Value type	Description	Required
ip	string	Network interface ip address	only if dhcp is false
mask	string	Network interface ip address subnet mask	only if dhcp is false
gateway	list	List of ip address gateway	only if dhcp is false
dhcp	boolean	Whether to use dhcp or not

To reconfigure a server with static IP address, the JSON payload would look as follows:

{"hostname": "web1",
 "dns": ["192.168.1.1", "8.8.8.8"], 
 "domain": "eis.utoronto.ca",
 "interfaces": [{"ip": "192.161.11",
                 "dhcp": false,
                 "mask": "255.255.255.0",
                 "gateway": ["192.168.1.1"]
                 }
               ],
 "poweron": true}

Above payload can be submitted using the POST method to /v2/vm/<vm-id>/custom_spec as shown below:

Updating HA group

http POST "https://vss-api.eis.utoronto.ca/v2/vm/501272f9-9c3c-e058-087b-d68db75064d1/custom_spec" hostname=web1 domain=eis.utoronto.ca dns:='["192.168.1.1", "8.8.8.8"]' interfaces:='[{"ip": "192.161.11", "dhcp": false, "mask": "255.255.255.0", "gateway": ["192.168.1.1"] }]' poweron:=true "Authorization: Bearer $TK"

curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X PUT "https://vss-api.eis.utoronto.ca/v2/vm/50124dc2-aba4-5c57-130c-da207557e5bd/custom_spec" -d '{"hostname": "web1", "dns": ["192.168.1.1", "8.8.8.8"], "domain": "eis.utoronto.ca", "interfaces": [{"ip": "192.161.11", "dhcp": false, "mask": "255.255.255.0", "gateway": ["192.168.1.1"] } ], "poweron": true}'