A few days ago I was asked by a customer on how to attach an ISO file to a VM using RestAPI calls in the vCenter. Having never done this before I had a look at the problem today and want to share the steps with you.

High-level overview#

Assuming you uploaded the ISO file to the content library prior to reading this, you need to obtain three information before you can attach an ISO file:

  1. Obtain the VM id
  2. Obtain the full ISO file name (the hardest part)
  3. Get the CD-ROM information from VM

After that you can attach the ISO using a PATCH call to the VMs CD-ROM.

Disclaimer : I used the Code Capture-feature from the Developer Center to do a dry-run and looked at the code output to obtain the VM id and the ISO file path. I recommend you do the same if you want to save some time, especially the library item calls require a lot of effort:
If you decide to obtain the content library information manually, you need to do a set of GET calls to https://{api_host}/api/content/* to identify the content library ID, the item ID and the storage information of the item.


In my case I am working with these values:

  • My API endpoint (vCenter) with the name cube-vcsa-01.lab.why-did-it.fail
  • A virtual machine named cube-vracvm-011155 with the VM id “vm-2287”
  • An ISO file name 5886dee04857cfe8f928b4f450b3613057a4b3ac.iso with the item ID “93666c85-5ba7-4e4f-8170-e5ca74534c58” in the content library TCE with content library ID “ab299121-09c3-4e76-9681-a624b2d497dd”
    • The resulting storage URI is ds:///vmfs/volumes/vsan:52ffd26f9403bcb0-de69e00ac35259d5//contentlib-ab299121-09c3-4e76-9681-a624b2d497dd/93666c85-5ba7-4e4f-8170-e5ca74534c58/5886dee04857cfe8f928b4f450b3613057a4b3ac_e13a0bfb-4229-415b-9ac2-ff30c65fc15a.iso

Obtain CD-ROM information#

Use curl to get the CD-ROM id of the VM:

curl -X GET 'https://cube-vcsa-01.lab.why-did-it.fail/api/vcenter/vm/vm-2287/hardware/cdrom' -H 'vmware-api-session-id: XXX'

On success, you will see a similar Response body:

    "cdrom": "3000"

Take note of the ID, you will need it later. Seeing multiple values here means your VM has more than one CD-ROM, pick the one you prefer.

Attach CD-ROM#

You need to prepare a Request Body PATCH operation. In my example this will be:

    "start_connected": false,
    "backing": {
        "iso_file": "ds:///vmfs/volumes/vsan:52ffd26f9403bcb0-de69e00ac35259d5//contentlib-ab299121-09c3-4e76-9681-a624b2d497dd/93666c85-5ba7-4e4f-8170-e5ca74534c58/5886dee04857cfe8f928b4f450b3613057a4b3ac_e13a0bfb-4229-415b-9ac2-ff30c65fc15a.iso",
        "type": "ISO_FILE"
    "allow_guest_control": true

The iso_file parameter accepts different ways of passing the file name, you can also try to use "[<datastore>] contentlib-<id>/<item>/<file id>.iso". The example here is consistent with the response in storage_uris from /api/content/library/item/<library_item_id>/storage

Using curl, you can execute the attach operation by passing on the request body in a PATCHcall:

curl -X PATCH 'https://cube-vcsa-01.lab.why-did-it.fail/api/vcenter/vm/vm-2287/hardware/cdrom/3000' -H 'vmware-api-session-id: XXX' -H 'Content-type: application/json' -d '{ "start_connected": false, "backing": { "iso_file": "ds:///vmfs/volumes/vsan:52ffd26f9403bcb0-de69e00ac35259d5//contentlib-ab299121-09c3-4e76-9681-a624b2d497dd/93666c85-5ba7-4e4f-8170-e5ca74534c58/5886dee04857cfe8f928b4f450b3613057a4b3ac_e13a0bfb-4229-415b-9ac2-ff30c65fc15a.iso", "type": "ISO_FILE" }, "allow_guest_control": true }'

The response will be a HTTP status 204, OK.

As a verification step you can see use the vSphere Client to check the CD-ROM connection of the VM:

Image Caption
Successfully attached CD-ROM via API call