PUT /osImages/{id}

Use this method to modify a customized OS image profile, or to add or remove device drivers, boot files, and custom files (such as configuration settings, installation scripts, software, and unattend files) from the customized OS image profile.

Note: This REST API requires Lenovo XClarity Administrator v1.3.0 or later.

Authentication

Authentication with user name and password is required.

Request URL

PUT https://{management_server_IP}/osImages/{id}

where {id} is the base OS-image ID, customized OS-image profile ID, device driver ID, or boot file ID respectively. To obtain the ID, use the GET /osImages method.

Query parameters

Parameters Required / Optional Description
imageType={type} Optional Type of custom file to be modified. This can be one of the following values.
  • CONFIG. Configuration-settings file (in JSON format)
  • SCRIPT. Installation-script file.
  • SOFTWARE. Archive file (in .zip or .tar.gz format) that encapsulates the post-install software payload.
  • UNATTEND. Unattend file (in kickstart ,cfg, autoyast .xml, or Windows .xml format).
Note: The {id} that is specified in the URL must correlate to an existing file that matches the value that is specified in this attribute.
The following example modifies an OS-image profile.
PUT https://192.0.2.0/osImages/win2016|win2016-x86_64-install-Standard_core?serverId=101
&path=%2F/some%2F/path%2F/to%2F/file
The following example modifies an unattend file.
PUT https://192.0.2.0/osImages/win2016|win2016-x86_64-install-Standard_core?serverId=101
&path=%2F/some%2F/path%2F/to%2F/file?imageType=UNATTEND

Request body

Table 1. Modify a custom file.
Attributes Required / Optional Type Description
associatedFileId Optional String ID of the unattend file that was optionally associated with this configuration-settings file
customConfigFile Required if imageType is CONFIG Object Configuration-settings files to be modified
Note: Configuration settings are supported only for specific OS versions. To determine whether the OS supports configuration settings, use the customConfigReleases attribute in GET /osImages.
  description Optional String Description of the configuration-settings file
  content Optional String Contents of the configuration-settings file
  version Optional String Version of the configuration-settings file
customSoftware Required if imageType is SOFTWARE Object Software files to be modified
  description Optional String Description of the software payload
  version Optional String Version of the software payload
installScriptFile Required if imageType is SCRIPT Object Installation script files to be modified
  description Optional String Description of the installation-script
unattendFile Required if imageType is UNATTEND Object Unattend files to be modified
Note: Unattend files are supported only for specific OS versions. To determine whether the OS supports unattend files , use the customUnattendReleases attribute in GET /osImages.
  content Optional String Contents of the unattend file
  description Optional String Description of the unattend file
  version Optional String Version of the unattend file
The following example associating a custom config file with a custom unattend file.
{
   "associatedFileId":"20190424120112_SLES_InstallPackages_customUnattend.xml"
}
Table 2. Create or modify a customized OS image profile.
Attributes Required / Optional Type Description
profile Required if a customized OS-image profile ID is specified in the URL. Object Information about a customized OS image profile
Note: Preloaded OS image profiles cannot be modified.
  customizationOptions Optional Object Information about all options that can be customized in this operating system

If the base operating system for the profile does not support customization, this attribute is null.

If the base operating system for the profile supports customization but does support certain child attributes, the unsupported child attributes are returned as empty strings.

    bootOptions Optional Object Information about customizable boot options.
      bootFileIds Optional Array of strings Boot file IDs that correlate to boot file in the customized OS image profile
  • If a specified ID is not currently in the customized OS image profile, the boot file is added to the profile.

  • If an ID is currently in the customized OS image profile but is not specified, the boot file is removed from the profile.

Note: Boot files must be imported in the OS-image repository before they can be added to a customized OS image profile. Use POST /osImages to import the boot file, and then use POST /files/osImages?jobId={job_id} to import the boot file into the OS images repository.
    customConfigOptions Optional Object Information about the custom configuration settings that are associated with this customized OS-image profile
      customConfigFileIds Optional Array of strings IDs of the configuration-settings files that are associated with this customized OS-image profile
    customSoftwareOptions Optional Object Information about custom software payloads that are associated with this customized OS image profile
      customSoftwareIds Optional Array of strings List of IDs for each software payload that is associated with this customized OS image profile
    deployDataAndSoftwareLocation Optional String Path to the extracted software payload, custom files, and deployment data (such as certificates and logs) on the deployment host. The following directories are used by default.
  • Linux: /home/lxca

  • Windows: c:\lxca

    driverOptions Optional Object Information about predefined and imported device drivers that are associated with this customized OS image profile
      driverFileIds Optional Array of strings Device-driver IDs that correlate to all device-drivers in the customized OS image profile
  • If a specified ID is not currently in the customized OS image profile, the device driver is added to the profile.

  • If an ID is currently in the customized OS image profile but is not specified, the device-driver is removed from the profile.

Note: Device drivers must be imported in the OS-image repository before they can be added to a customized OS image profile. Use POST /osImages to import the device driver, and then use POST /files/osImages?jobId={job_id} to import the device driver into the OS images repository.
    scriptFileIds Optional Array of strings List of IDs for each installation-script file that is associated with this customized OS image profile
  • If a specified ID is not currently in the customized OS image profile, the installation-script file is added to the profile.

  • If an ID is currently in the customized OS image profile but is not specified, the installation-script file is removed from the profile.

Note: Installation-script files must be imported in the OS-image repository before they can be added to a customized OS image profile. Use POST /osImages to import installation-script files, and then use POST /files/osImages?jobId={job_id} to import installation-script files into the OS images repository.
    unattendOptions Optional Object Information about predefined unattended-file options
      unattendFileIds Optional Array of strings List of IDs for each unattend file that is associated with this customized OS image profile
  description Optional String Description for the customized OS image profile
  name Optional String Name of the customized OS image profile
  type Optional String Type of OS profile. This can be one of the following values.
  • custom. The profile was created when a boot file or device driver was manually uploaded and added to an operating system.

  • predefined. The profile was preloaded by Lenovo

The following example creates a new customized OS image profile for Windows 2016 and adds custom files to the profile.
{
   "profile": {
      "customizationOptions": {
         "bootOptions": {
            "bootFileIds": ["winpe-64-base"]
         },
         "customConfigOptions" : {
            "customConfigFileIds" : []
         },
         "customSoftwareOptions" : {
            "customSoftwareIds" : []
         } 
         "driverOptions": {
            "driverFileIds": [
               "nic-broadcom-bnxtnd-win2016-v1",
               "storage-broadcom-megasas35-win2016-v1",
               "hba-broadcom-itsas35-win2016-v1",
               "hba-elxcna-windows2016-v1"
            ]
         }
         "installScriptOptions": {
            "scriptFileIds": []
         },
         "unattendOptions": {
            "unattendFileId": []
         },
         "unattendOptions": {
            "unattendFileIds": []
         },
      },
      "name": "Win2016-Custom-Datacenter-2",
      "description": "My custom profile - Rename",
      "type": "custom"
   }
}

Response codes

Code Description Comments
200 OK The request completed successfully.
403 Forbidden The orchestrator server was prevented from fulfilling the request. A descriptive error message is returned in the response body. Ensure that you have privileges to perform the request.

For XClarity Administrator advanced functions, ensure that you have active licenses for each managed server that supports the advanced functions.

500 Internal Server Error An internal error occurred. A descriptive error message is returned in the response body.

Response body

Attributes Type Description
result String Results of the request. This can be one of the following values.
  • success. The request completed successfully.
  • failed. The request failed. A descriptive error message was returned.
  • warning. The request completed with a warning. A descriptive error message was returned.
messages Array of objects Information about one or more messages
  id String Message identifier of a returned message
  text String Message text associated with the message identifier
  explanation String Additional information to clarify the reason for the message
  recovery Array of objects Recovery information
    text String User actions that can be taken to recover from the event
    URL String Link to the help system for more information, if available
The following example is returned if the request is successful.
{
   "result": "success",
   "messages":[]
}
The following example is returned if the request is not successful.
{
    "result": "failed",
    "messages": [{
        "explanation": "The request resource cannot be found.", 
        "id": "FQXHMFC0XXXM ", 
        "text": "Modify your request data. If the problem persists, contact Support.", 
        "recovery": {
            "URL": "", 
            "text": "Unable to modify the specified resource ID. The ID is not found."
        }
    }]
}