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 the CIFS protocol is supported.

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

This implementation supports optional OEM parameters that allow additional post-mount behavior and persistent mount control: 

    "Oem": {
        "ERMI": {
            "PostMountScript":"install.sh",
            "PostMountScriptTimeout": 180,
            "AutoMountPolicy": {
                "Enabled": false,
                "IntendedMountType": "VirtualMedia"
            }
        }
    }
- PostMountScript specifies a custom script to be executed on the edge device after the virtual media has been successfully mounted.

  • PostMountScriptTimeout specifies the maximum allowed execution time, in seconds, for the post-mount script.

  • AutoMountPolicy controls whether the virtual media should be automatically re-mounted after the edge device reboots:

  • Enabled indicates whether automatic mounting is enabled after the edge device reboot.

  • IntendedMountType specifies the mount type to be applied during automatic mounting (for example, VirtualMedia).

Once the image is mounted successfully, the system attempts to trigger the specified post-mount script on the edge device.

If the InsertMedia action includes a PostMountScript and the Task Service is enabled on the system, a task is created to monitor the execution result of the post-mount script. The task provides status and progress information until the script execution completes or fails. For more details about task behavior and properties, refer to the Task Service section.

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

Method: POST

Request Body Example (SMB URL format):

An example request body for inserting media without a post-mount script or auto-mount policy is shown below: 

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

An example request body for inserting media with a post-mount script is shown below: 

{
    "Image": "smb://192.168.1.100/share/appUpdate.iso",
    "TransferProtocolType": "CIFS",
    "Inserted": true,
    "UserName":"test",
    "Password":"1234",
    "Oem": {
        "ERMI": {
            "PostMountScript": "install.sh",
            "PostMountScriptTimeout": 180
        }
    }
}

An example request body for inserting media with auto-mount enabled is shown below: 

{
    "Image": "smb://192.168.1.100/share/appUpdate.iso",
    "TransferProtocolType": "CIFS",
    "Inserted": true,
    "UserName":"test",
    "Password":"1234",
    "Oem": {
        "ERMI": {
            "AutoMountPolicy": {
                "Enabled": true,
                "IntendedMountType": "VirtualMedia"
            }
        }
    }
}

An example request body for inserting media with both a post-mount script and auto-mount enabled is shown below: 

{
    "Image": "smb://192.168.1.100/share/appUpdate.iso",
    "TransferProtocolType": "CIFS",
    "Inserted": true,
    "UserName":"test",
    "Password":"1234",
    "Oem": {
        "ERMI": {
            "PostMountScript": "install.sh",
            "PostMountScriptTimeout": 180,
            "AutoMountPolicy": {
                "Enabled": true,
                "IntendedMountType": "VirtualMedia"
            }
        }
    }
}

Explanation

  • Image: SMB/CIFS network share URL using smb://server/share/file format.
  • TransferProtocolType: Only "CIFS" is supported.
  • The PostMountScript parameter is optional. If provided, it will be executed on the edge device after a successful mount operation.
  • The PostMountScriptTimeout parameter is optional. Specifies the maximum amount of time allowed for the post-mount script to complete after the virtual media has been successfully mounted. If the script does not finish within the specified timeout period, the operation is considered to have failed and an error is reported.
  • The AutoMountPolicy parameter is optional and controls whether the virtual media is automatically re-mounted after the edge device reboots.
    • When Enabled is set to true, the system will attempt to automatically mount the previously inserted virtual media according to the specified IntendedMountType during system startup.
    • When Enabled is set to false or the AutoMountPolicy object is not present, the virtual media will not be automatically mounted after a reboot and must be mounted manually through the InsertMedia action.

Response

HTTP Status Code: 204 No Content

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

HTTP Status Code: 202 Accepted

The service returns an HTTP 202 Accepted response when the InsertMedia action includes a PostMountScript and the Task Service is enabled. This status code indicates that the request has been accepted for asynchronous processing and that a task has been created to monitor the execution of the post-mount script. Clients can use the returned task resource to track the execution status and final result.

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."

HTTP Status Code: 404 Not Found

The specified post-mount script does not exist, a 404 Not Found status code will be returned. Please verify that the script is included in the ISO image.

HTTP Status Code: 424 Failed Dependency

The virtual media image was mounted successfully on the ERMI side, but the host system did not detect the USB storage device, a 424 Failed Dependency status code will be returned. Please check ERMI daemon version and USB cable connection.

HTTP Status Code: 503 Service Unavailable

If the ERMI successfully mounts the image but cannot verify USB enumeration on the edge device, the system returns 503 Service Unavailable with an explanatory message. Please ensure the edge device installs the required ERMI daemon.

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/Systems/{systemId}/VirtualMedia/{device}/Actions/VirtualMedia.EjectMedia

Method: POST

Response

HTTP Status Code: 204 No Content

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

HTTP Status Code: 403 Forbidden

If an EjectMedia request is issued while a post-mount script is running, the service returns an HTTP 403 Forbidden response.

13.3 Step-by-Step Workflow: Insert Media Only

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 ERMI module 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