Bug 1145074

 (In reply to Juan Hernández from comment #0)
> The correct way to eject a CDROM (see [1], example 26.26) is to use the PUT
> method with an empty "file.id":
> 
> PUT
> /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-
> 000000000000;current=true HTTP/1.1
> Accept: application/xml
> Content-type: application/xml
> <cdrom>
>   <file id=""/>
> </cdrom>
> 
> [1]
> https://access.redhat.com/documentation/en-US/
> Red_Hat_Enterprise_Virtualization/3.5-Beta/html/Technical_Guide/
> Virtual_Machine_CD-ROMs_Sub-Collection.html

Hi Juan,
   Thanks for filing this bug. If you could provide us with a correct example, it will speed up our time to get this fix out. Could you kindly provide us with a correct example? (There should be an 'expected result' section in the template for bug creation)

Many thanks, 
Julie

Currently the example 29.26 reads as follows:

"Send a DELETE request to the cdroms sub-collection of a virtual machine to remove the CD-ROM from a virtual machine:
⁠
Example 29.26. Removing a CD-ROM file during a current session

DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml"

But isn't correct, or confusing, because what it is doing is persistently disconnecting the CD-ROM from the virtual machine, not only during the current session. The correct way to remove the CD-ROM during the current session is to use a PUT request with the current=True matrix parameter and an empty file identifier. So, in my opinion, the example should read as follows:

"To eject the CD-ROM send a PUT request to the CD-ROM sub-collection of a virtual machine, adding the current=True matrix parameter:

Example 29.26. Ejecting a CD-ROM during the current session

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
  <file id=""/>
</cdrom>

Note that this will disconnect the CD-ROM from the virtual machine only temporarely, rebooting the virtual machine will connect it again."

You may want to preserve the original example, but I'd suggest that you explicitly indicate that it disconnects the CD-ROM from the virtual machine persistently, not only during the current session. In addition I think that it is bad practice to use the DELETE request for this, so if you are keeping this example I'd suggest to rewrite it as follows:

"To eject the CD-ROM send a PUT request to the CD-ROM sub-collection of a virtual machine:

Example 29.26. Ejecting a CD-ROM permanently

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
  <file id=""/>
</cdrom>

Note that this will permanently disconnect the CD-ROM from the virtual machine."

Thanks for the info, Juan.
Once the documentation gets updated, you will be need_info for confirmation.

Cheers,
Julie

*** Bug 1089782 has been marked as a duplicate of this bug. ***

Hi Juan, 

I've updated this section to correct the existing example, and added a further example. Can you please review to confirm its correctness? 

Thanks,
Tahlia


Documentation Link 
------------------------------
https://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.5/html-single/Technical_Guide/index.html#Virtual_Machine_CD-ROMs_Sub-Collection

The updated document looks good to me. I just would suggest to use current=true in example 29.25. the "=true" part isn't required, as it is the default, but it is good practice to make it explicit.

Documentation Link 
------------------------------
https://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.5/html-single/Technical_Guide/index.html#Virtual_Machine_CD-ROMs_Sub-Collection


What Changed 
------------------------------

CD-ROMs Sub-Collection [7992-714716]

Corrected the example for ejecting a CD-ROM during the current session, to:
----
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
  <file id=""/>
</cdrom>
----

And added an example for ejecting a CD-ROM permanently.

**I've also added current=true to example 29.25, but haven't rebuilt yet since it wasn't part of the original bug request. It will be in the next build, though. [7992-715438]

Updated revision history [34616-715259]


NVR
------------------------------
Red_Hat_Enterprise_Virtualization-Technical_Guide-3.5-web-en-US-3.5-17.el6eng


Moving to ON_QA