Skip to content

13. Virtual Media

13.1 Overview

The Virtual Media feature in Redfish allows a client to attach remote ISO or IMG images as if they were physically inserted into the system. This enables operations like remote OS installation, diagnostics, and recovery without physical media interaction.

This implementation uses the USB gadget interface to emulate virtual storage at the BMC (Baseboard Management Controller) side, and supports mounting remote images over network protocols such as CIFS.

Key Features:

  • Attach remote ISO/IMG files
  • Stream-based or URI-based mounting
  • Redfish standard-compatible actions: InsertMedia, EjectMedia
  • Real-time mount status tracking

13.2 API Endpoints

Virtual Media Collection

Returns a list of virtual media devices available (e.g., USB).

URI: /redfish/v1/Systems/{systemId}/VirtualMedia

Method: GET

Response:

{
    "@odata.context": "/redfish/v1/$metadata#VirtualMediaCollection.VirtualMediaCollection",
    "@odata.id": "/redfish/v1/Systems/1/VirtualMedia",
    "@odata.type": "#VirtualMediaCollection.VirtualMediaCollection",
    "Name": "Virtual Media Collection",
    "Description": "Collection of Virtual Media devices",
    "Members@odata.count": 1,
    "Members": [
        {
            "@odata.id": "/redfish/v1/Systems/1/VirtualMedia/USB"
        }
    ]
}

Virtual Media Instance

Returns the status and configuration of a virtual media device.

URI: /redfish/v1/Systems/{systemId}/VirtualMedia/{device}

Method: GET

Response:

{
    "@odata.context":"/redfish/v1/$metadata#VirtualMedia.VirtualMedia",
    "@odata.id":"/redfish/v1/Systems/1/VirtualMedia/USB",
    "@odata.type":"#VirtualMedia.v1_2_1.VirtualMedia",
    "Id":"USB",
    "Name":"USB Virtual Media",
    "Description":"Virtual Media device using USB gadget interface",
    "MediaTypes":[
        "USBStick"
    ],
    "Image":"",
    "Inserted":false,
    "WriteProtected":true,
    "ConnectedVia":"URI",
    "TransferMethod":"Stream",
    "TransferProtocolType":[
        "CIFS"
    ],
    "Actions":{
        "#VirtualMedia.InsertMedia":{
            "target":"/redfish/v1/Systems/1/VirtualMedia/USB/Actions/VirtualMedia.InsertMedia"
        },
        "#VirtualMedia.EjectMedia":{
            "target":"/redfish/v1/Systems/1/VirtualMedia/USB/Actions/VirtualMedia.EjectMedia"
        }
    },
    "Status": {
        "State": "Enabled",
        "Health": "OK"
    }
}

Status.State Values:

Type Meaning
Enabled Virtual Media is operational. USB is in Device Mode.
Disabled Virtual Media is not available, for example, USB is in Host Mode.

Insert Media

This action instructs the system to mount the specified virtual media image (ISO or IMG file) over the given transfer protocol. Currently, only CIFS protocol is supported.

Before attempting to mount, the system validates the input parameters and the current USB mode.

URI: /redfish/v1/Systems/{systemId}/VirtualMedia/{device}/Actions/VirtualMedia.InsertMedia

Method: POST

Request Body Example (SMB URL format):

{
    "Image": "smb://192.168.1.100/share/ubuntu.iso",
    "TransferProtocolType": "CIFS",
    "Inserted": true,
    "UserName":"test",
    "Password":"1234"
}

Explanation

  • Image: SMB/CIFS network share URL using smb://server/share/file format.
  • TransferProtocolType: Only "CIFS" is supported.

Response

HTTP Status Code: 204 No Content

If the operation is successful, a status code 204 No Content will be returned.

HTTP Status Code: 400 Bad Request

If the provided parameters are incorrect, a 400 Bad Request status code will be returned.

Error Condition Error Message
Missing or empty Image parameter "The InsertMedia action requires the Image parameter."
Unsupported file format in Image URL "The value of property 'Image' is not in the list of acceptable formats."
Invalid TransferProtocolType value "The value specified for property 'TransferProtocolType' is not valid."
Mount failure (any cause during CIFS mounting) "The system failed to mount the specified image using CIFS."
USB not in Device Mode "The system is not in USB Device Mode. Virtual media functions require the USB controller to be configured as a device."
HTTP Status Code: 409 Conflict

Another image already mounted with different file, a 409 Conflict status code will be returned. The error message will be "Another virtual media image is already inserted."

Eject Media

This action instructs the system to unmount and eject the currently inserted virtual media image from the specified virtual media device.

If no media is currently inserted, the action should succeed silently or return an appropriate error indicating no media is present.

Upon successful ejection, the virtual media device’s status will update to reflect that no media is inserted.

URI: /redfish/v1/Managers/BMC/SerialInterfaces/{id}/Actions/SerialInterface.Connect

Method: POST

Response

HTTP Status Code: 204 No Content

If the operation is successful, a status code 204 No Content will be returned.

13.3 Virtual Media Workflow (Step-by-Step)

The Virtual Media feature enables remote mounting and unmounting of virtual ISO or IMG files over network protocols via a USB virtual device interface. This allows a system to access installation or recovery media as if it were physically inserted via USB.

The workflow involves checking device status, inserting media through network share URLs, and later ejecting the media once operations complete.

Step 1: Check Virtual Media Status

  • Client sends a GET request to /redfish/v1/Systems/{systemId}/VirtualMedia/{device}
  • Verify that USB is in Device Mode (Status.State = Enabled)
  • If not, please check the OOB USB controller mode.

Step 2: Insert Media

  • Client sends a POST to /redfish/v1/Systems/{systemId}/VirtualMedia/{device}/Actions/VirtualMedia.InsertMedia
  • Include "Image": "smb://...", "TransferProtocolType": "CIFS", and "Inserted": true
  • Server validates and attempts to mount the media

Step 3: Handle InsertMedia Response

  • On success, the server returns 204 No Content, indicating the media is now mounted.
  • If parameters are invalid or mounting fails due to server or network issues, a 400 Bad Request is returned with detailed error messages.
  • If another image is already mounted, the server responds with 409 Conflict.

Step 4: Use Virtual Media

  • Once mounted, the virtual media behaves as a local device, enabling OS/Application installations or recovery tasks.

Step 5: Eject Media

  • Client sends a POST request to the EjectMedia action endpoint to unmount and eject the currently mounted virtual media.
  • The server performs the unmount operation and updates device status.

Next section