Specification 11/07/2017. Copyright 2017 FUJITSU LIMITED. Version 5.0

Transcription

1 Specification irmc RESTful API Version /07/2017 Copyright 2017 FUJITSU LIMITED Designations used in this document may be trademarks, the use of which by third parties for their own purposes could violate the rights of the trademark owners Contact FUJITSU LIMITED Copyright 2017 FUJITSU LIMITED

2 Contents Contents 2 1 General Change History Requirements Introduction 4 2 Foundations Asynchronous Tasks / LCM Sessions Session Limit XML and JSON Support General Limitations Repository Configuration JobList Activities Interlock 8 3 RESTful API Support Table Repository Configuration rest/v1/oem/elcm/repository/update GET rest/v1/oem/elcm/repository/deployment GET rest/v1/oem/elcm/repository/update PUT rest/v1/oem/elcm/repository/deployment PUT Online Update rest/v1/oem/elcm/onlineupdate POST rest/v1/oem/elcm/onlineupdate/updatecollection GET rest/v1/oem/elcm/onlineupdate/updatecollection DELETE rest/v1/oem/elcm/onlineupdate/updatecollection/<component>/<subcomponent> GET rest/v1/oem/elcm/onlineupdate/updatecollection/<component>/<subcomponent> PATCH rest/v1/oem/elcm/onlineupdate/updatecollection PUT Offline Update rest/v1/oem/elcm/offlineupdate/configuration POST rest/v1/oem/elcm/offlineupdate POST rest/v1/oem/elcm/offlineupdate PUT Dedicated Update rest/v1/oem/elcm/dedicatedupdate POST Custom Images rest/v1/oem/elcm/customimage POST rest/v1/oem/elcm/customimage GET rest/v1/oem/elcm/customimage/<imagename> GET rest/v1/oem/elcm/customimage/<imagename> PUT rest/v1/oem/elcm/customimage/<imagename> DELETE rest/v1/oem/elcm/customimage/download POST rest/v1/oem/elcm/customimage/proxysettings GET rest/v1/oem/elcm/customimage/proxysettings PUT Profile Management rest/v1/oem/elcm/profilemanagement/get POST rest/v1/oem/elcm/profilemanagement/set POST rest/v1/oem/elcm/profilemanagement GET rest/v1/oem/elcm/profilemanagement/<profilename> GET rest/v1/oem/elcm/profilemanagement/capabilities GET rest/v1/oem/elcm/profilemanagement/<profilename> DELETE rest/v1/oem/elcm/profilemanagement/version GET Deployment rest/v1/oem/elcm/svim/getostypesupport POST 29 Page 2 of 100

3 3.8.2 rest/v1/oem/elcm/svim/ostypes GET rest/v1/oem/elcm/svim/download POST rest/v1/oem/elcm/svim/bootenvironment PATCH rest/v1/oem/elcm/svim GET rest/v1/oem/elcm/svim/remove DELETE LCM Session Management sessioninformation GET sessioninformation/<sessionid>/status GET sessioninformation/<sessionid>/log GET sessioninformation/<sessionid>/ws GET sessioninformation/<sessionid>/terminate DELETE sessioninformation/<sessionid>/remove DELETE LCM General rest/v1/oem/elcm/elcmstatus GET Link Status rest/v1/oem/niclink/status GET Firmware Inventory redfish/v1/ GET SSD Lifetime Monitoring rest/v1/oem/ssdconfigurationirmc GET irmc /rest/v1/oem/irmc/reset POST 42 4 Examples Profile Management Accessing any Paths of the Server Profile Profile Flow Control Using elcm Profile Management BIOS Boot Order Configuration Online Update Out-of-band RAID Configuration using Profile Management Create Logical Drive (RAID Level 1) Delete Logical Drive (Number#1) 59 5 elcm Profile Management Profile Definitions irmc Profile Specification BIOS Profile Specification Out-of-band RAID Configuration Profile Further Profile Specification Profile Dependencies 100 Page 3 of 100

4 1 General This document is the specification of the irmc S5 RESTful API in firmware version 1.0x. 1.1 Change History Date Version Changes Published version for 1.0x (S5) Published version for 8.8x (S4) Published version for 8.6x (S4) Published version for 8.4x (S4) Published version for 1.2 Requirements This document assumes that the reader is familiar with RESTful web services, JSON, XML and HTTP in general. To learn more about REST, JSON and XML, see the following: You will also need a Fujitsu PRIMERGY server with an irmc S5 with elcm license for full support. 1.3 Introduction The RESTful Server Management API is a web service API which is served by the irmc firmware. A RESTful API is an application programming interface which makes use of HTTP operations (mainly GET, DELETE, PUT, POST and PATCH). These HTTP operations submit or return resources which can be encoded in either JSON or XML, similar to a usual web application which returns HTML, JS and CSS. This API is loosely based on the Redfish standard as provided by the DMTF. 1 In modern scripting languages these interfaces are very easy to use, as there are plenty of libraries and helper tools that deal with JSON and XML structures and transport via HTTP(s). This API is available for irmc S4 and S5 systems. When referring to an irmc S4 firmware version, the version number is followed by (S4), for an irmc S5 system with (S5). When changes only show an irmc S5 version number, it means these changes are not available in an irmc S4 release yet. When changes only show an irmc S4 version number, it means these changes were already made before the initial 1.0x version for irmc S5 and are thus also included in every irmc S5 release. For general information on how to use the irmc RESTful API, please refer to [White paper irmc S5 RESTful Server Management API]. In the following resource descriptions, the prefix for all URIs is as follows http(s)://<irmc IP address>/. 1 Page 4 of 100

5 2 Foundations 2.1 Asynchronous Tasks / LCM Sessions If you are accessing resources that trigger actions/tasks and you cannot get a direct result from the API, the API will create an LCM Session. In this case, you will get an answer containing an ID, which can be used to obtain the status of the created asynchronous task. Optionally it is also possible to tag the session with a userdefined value via the tag URL parameter. This makes it easier for the user to spot/filter specific sessions. 2.2 Session Limit The LCM Session API has a limit of 64 sessions, for which status information and logs can be retrieved, so your clients should regularly delete sessions to avoid the risk of opening too many. A terminated session will automatically be deleted after 24 hours. A script-based access must try to get termination status within this timeframe. 2.3 XML and JSON Support The irmc RESTful API supports JSON and XML formats. You can specify the appropriate format in the Accept header of the HTTP protocol. - Accept: application/json - Accept: application/xml E.g. curl -u <uname>:<pwd> -H "Accept: application/json" and curl -u <uname>:<pwd> -H "Accept: application/xml" 2.4 General Limitations When applying profiles via the RESTful API, please keep in mind that it does not provide the same kind of plausibility checks like in the irmc Web interface. Thus it is sometimes possible to apply profiles with illegal configurations. Because of this limitation it is important to make sure the profile to be applied is plausible and the resulting configuration could also be set manually within the Web Interface or BIOS menu. Page 5 of 100

6 2.5 Repository Configuration For several functions, such as online / offline update, Custom Image or deployment activity, the repository download server must be specified, along with optional proxy settings. To provide this information via the RESTful API for specified resources, a RepositoryConfiguration.xml must be transmitted. The structure and contents of the RepositoryConfiguration.xml file are defined as follows: <Repository> <Server> <URL> <Catalog>DownloadManager/globalflash/GF_par_tree.exe</Catalog> <UseProxy>yes/no</UseProxy> </Server> <Proxy> <URL></URL> <Port></Port> <User></User> <Password></Password> </Proxy> </Repository> - The server s <URL> is mandatory field in this configuration file. - <Catalog> should be specified for the update repository. For deployment activity (download of the Service Platform (SP) associated with the specified operating system), the <Catalog> field is not taken into account and is not returned for the API GET command. - <UseProxy> is an optional field. <UseProxy> allows access to the repository server with or without a proxy server. If <UseProxy> is present, its value is used. If it is not present, the value depends on the global irmc proxy configuration. If a proxy is configured and enabled, the <UseProxy> yes value is assumed; if the proxy is not enabled, the <UseProxy> no value is taken. - The <Proxy> section is optional if not present, the current irmc settings are used. This means that if a proxy is configured it will be used with the same settings, and if the proxy is disabled it will remain disabled. Important: To disable the proxy server for repository access only, use the <UseProxy>no</UseProxy> setting. Sending all proxy configuration parameters empty (as in the example above) will result in disabling proxy use for the whole irmc network communication. Besides the newly introduced Repository Configuration REST resource, the RepositoryConfiguration.xml input data for online / offline update as well as for Custom Image is optional. If it is not set, predefined irmc settings from the Repository Configuration are taken in account. 2.6 JobList The dedicated offline update concept relies on the feature of providing RESTful API for starting the dedicated offline update via a JobList. In general, the JobList is a list of components which are to be installed on a server. The main difference between this feature and the standard mechanism of online and offline update is that the user can define which version of a selected component should be installed. This also means that components can be downgraded. The JobList has JSON syntax. The list is built from two main objects: Update, which contains information about the update method (Online or Offline) and the update mode (Strict or Loose), and Component, which contains an array with components which are to be installed. Each component must have the following unique index ComponentType component type (category: e.g. LanController, SystemBoard) ComponentName component name (model: e.g. OCe10102-F, D3229-RX100S8) ComponentVersion component version (e.g. V , V _R2.14.0) ValidationResult component s dependency validation result In general, three parameters ComponentType, ComponentName and ComponentVersion should create a path to the directory with versionleaf.txt / binary file on the local / remote repository. For example: /usr/lmedia/elcm_updatecatalog/globalflash/componenttype/componentname/componentversion/versionleaf.txt Page 6 of 100

7 The VersionResult parameter is used by irmc to check if a given component has passed the dependency validation test. The irmc must receive a list of already validated components. An example of a JobList: Update : Method : Online/Offline, UpdateMode : strict/loose, Component : : 1, ComponentType : SystemBoard, ComponentName : D3302-RX200S8, ComponentVersion : V _R1.11.0, ValidationResult : : 2, ComponentType : MangementController, ComponentName : irmc S5, ComponentVersion : 7.70, ValidationResult : ERR, ValidationDependency : *rekursiv* ComponentType : LanController, ComponentName : Intel-XYZ, ComponentVersion : V _R1.24.0,, ] Page 7 of 100

8 2.7 Activities Interlock Some elcm activities cannot be run while others are being executed. This limitation is mostly related to performing system restarts when another activity is currently performing an action on this system. With elcm 1.2, the interlocking mechanism was updated to disable such scenarios. A significant change introduced in comparison with previous firmware releases is that interlocking is performed just before an activity should start, not during session activation. Even if a scheduled activity is rejected, scheduler settings will remain unchanged and the next attempt will be performed according to scheduled mode. An appropriate message is left in session logs, and session execution is terminated with the status terminate conflict with another running elcm activity. Moreover, the new interlock schema locks activities executed in parallel via RESTful API and in the WebUI. The following table should be read as follows: The columns show currently executing activities, while the rows show activity candidates to be executed. So for instance, when Download Custom Image is being executed, the activity Obtain Profile Parameters is allowed, but Execute Offline Update is prohibited and will be terminated. OBTAIN PROFILE PARAMETERS APPLY PROFILE PREPARE OFFLINE UPDATE EXECUTE OFFLINE UPDATE ONLINE UPDATE CHECK ONLINE UPDATE EXECUTE DOWNLOAD CUSTOM IMAGE EXECUTE CUSTOM IMAGE SET REPO CONFIG DOWNLOAD DEPLOYMENT IMAGE DEDICATED ONLINE UPDATE DEDICATED OFFLINE UPDATE OBTAIN PROFILE PARAMETERS APPLY PROFILE PREPARE OFFLINE UPDATE EXECUTE OFFLINE UPDATE ONLINE UPDATE CHECK ONLINE UPDATE EXECUTE DOWNLOAD CUSTOM IMAGE EXECUTE CUSTOM IMAGE BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED SET REPO CONFIG DOWNLOAD DEPLOYMENT IMAGE BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED not implemented not implemented not implemented BLOCKED BLOCKED BLOCKED BLOCKED not implemented not implemented not implemented not implemented not implemented not implemented not implemented BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED DEDICATED ONLINE UPDATE not implemented not implemented not implemented not implemented not implemented not implemented not implemented not implemented not implemented not implemented not implemented not implemented DEDICATED OFFLINE UPDATE BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED BLOCKED not implemented BLOCKED Page 8 of 100

9 3 RESTful API 3.1 Support Table URI Method Supported since Repository Configuration rest/v1/oem/elcm/repository/update GET rest/v1/oem/elcm/repository/deployment GET rest/v1/oem/elcm/repository/update PUT rest/v1/oem/elcm/repository/deployment PUT Online Update rest/v1/oem/elcm/onlineupdate POST rest/v1/oem/elcm/onlineupdate/updatecollection GET 8.0x (S4) rest/v1/oem/elcm/onlineupdate/updatecollection DELETE 8.0x (S4) rest/v1/oem/elcm/onlineupdate/updatecollection PUT rest/v1/oem/elcm/onlineupdate/updatecollection/<component>/<subcomponent> GET 8.0x (S4) rest/v1/oem/elcm/onlineupdate/updatecollection/<component>/<subcomponent> PATCH 8.0x (S4) Offline Update rest/v1/oem/elcm/offlineupdate/configuration deprecated by Repository Configuration in irmc FW 8.1x POST 8.0x (S4) rest/v1/oem/elcm/offlineupdate POST rest/v1/oem/elcm/offlineupdate PUT Dedicated Update rest/v1/oem/elcm/dedicatedupdate POST Custom Images rest/v1/oem/elcm/customimage GET 8.0x (S4) rest/v1/oem/elcm/customimage POST rest/v1/oem/elcm/customimage/<imagename> GET 8.0x (S4) rest/v1/oem/elcm/customimage/<imagename> PUT rest/v1/oem/elcm/customimage/<imagename> DELETE rest/v1/oem/elcm/customimage/download POST rest/v1/oem/elcm/customimage/proxysettings GET rest/v1/oem/elcm/customimage/proxysettings PUT Profile Management rest/v1/oem/elcm/profilemanagement/get POST rest/v1/oem/elcm/profilemanagement/set POST rest/v1/oem/elcm/profilemanagement GET 8.0x (S4) Page 9 of 100

10 rest/v1/oem/elcm/profilemanagement/<profilename> GET 8.0x (S4) rest/v1/oem/elcm/profilemanagement/<profilename> DELETE 8.0x (S4) rest/v1/oem/elcm/profilemanagement/capabilities GET 8.0x (S4) rest/v1/oem/elcm/profilemanagement/version GET Deployment rest/v1/oem/elcm/svim/getostypesupport POST rest/v1/oem/elcm/svim/ostypes GET rest/v1/oem/elcm/svim/download POST rest/v1/oem/elcm/svim/bootenvironment PATCH rest/v1/oem/elcm/svim/ GET rest/v1/oem/elcm/svim/remove DELETE LCM Session Management sessioninformation GET 8.0x (S4) sessioninformation/<sessionid>/status GET 8.0x (S4) sessioninformation/<sessionid>/log GET 8.0x (S4) sessioninformation/<sessionid>/ws GET 8.0x (S4) sessioninformation/<sessionid>/terminate DELETE 8.0x (S4) sessioninformation/<sessionid>/remove DELETE 8.0x (S4) LCM General rest/v1/oem/elcm/elcmstatus GET Link Status rest/v1/oem/niclink/status GET 8.6x (S4) Firmware Inventory redfish/v1/ GET 8.6x (S4) SSD Lifetime Monitoring rest/v1/oem/ssdconfigurationirmc GET 8.8x (S4) irmc /rest/v1/oem/irmc/reset POST 1.0x (S5) Page 10 of 100

11 3.2 Repository Configuration rest/v1/oem/elcm/repository/update GET URI: rest/v1/oem/elcm/repository/update Method: GET Result: Behavior: URL Parameter: Input Data: Return Codes: Returns the current update repository configuration. HTTP status code 200 (OK) is returned on success. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: curl example: Update repository configuration in XML or JSON format. No curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i rest/v1/oem/elcm/repository/deployment GET URI: rest/v1/oem/elcm/repositorydeployment Method: GET Result: Behavior: Returns the current deployment repository configuration. URL Parameter: Input Data: Return Codes: HTTP status code 200 (OK) is returned on success. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 occurred. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: curl example: Deployment repository configuration in XML or JSON format. No curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i Page 11 of 100

12 3.2.3 rest/v1/oem/elcm/repository/update PUT URI: rest/v1/oem/elcm/repository/update Method: PUT Result: Behavior: URL Parameter: Input Data: Return Codes: Applies new repository configuration. Tests repository connection. Only if the test is successful is the configuration applied and saved. Optional: tag RepositoryConfiguration.xml HTTP status code 200 (OK) is returned on success. HTTP status code 400 (BAD REQUEST) is returned if RepositoryConfiguration.xml was not sent. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if another repository configuration operation is currently running or there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: curl example: Session information Yes curl -u <uname>:<pwd> -H "Accept: application/json" -X PUT -i rest/v1/oem/elcm/repository/deployment PUT URI: rest/v1/oem/elcm/repository/update Method: PUT Result: Behavior: URL Parameter: Input Data: Return Codes: Applies new deployment repository configuration. Tests repository connection. Only if the test is successful is the configuration applied and saved. Optional: tag RepositoryConfiguration.xml HTTP status code 200 (OK) is returned on success. HTTP status code 400 (BAD REQUEST) is returned if RepositoryConfiguration.xml was not sent. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if another repository configuration operation is currently running or there is no valid elcm license or the SD card is not mounted. Returned Data: Creates LCM Session: curl example: Session information Yes curl -u <uname>:<pwd> -H "Accept: application/json" -X PUT -i Page 12 of 100

13 3.3 Online Update rest/v1/oem/elcm/onlineupdate POST URI: rest/v1/oem/elcm/onlineupdate Method: POST Result: Behavior: URL Parameter: Input Data: Return Codes: Start update check. Creates a new updatecollection resource under /rest/v1/oem/elcm/onlineupdate and starts an update check using the specified repository server information. The repository server information is transferred in the POST message body as an XML-formatted string. To perform the update check, the POST method handler creates an LCM session performing the necessary operations. Optional: tag Optional: \RepositoryConfiguration.xml Important: Transmitting the Repository Configuration in this way is deprecated. Only XML is possible here. No JSON support. Use rest/v1/oem/elcm/repository/update PUT instead HTTP status code 202 (ACCEPTED) is returned on success. HTTP status code 404 (NOT FOUND) is returned if any resource given in the command is not found. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 (e.g. not enough memory or task could not be created). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if e.g. the updatecollection resource already exists or a resource is required (e.g. CD-ROM drive) which is occupied by another task. This status is also returned if there is no valid elcm license or the SD card is not mounted. Returned Data: If successful, the session ID is sent in the body of the response message. The response message contains a relative location header referencing the updatecollection location. Comment: The progress of the update check can be monitored via LCM Session Management (see section 3.8). Creates LCM Session: curl example: Yes curl -u <uname>:<pwd> -H "Accept: application/json" -X POST -i rest/v1/oem/elcm/onlineupdate/updatecollection GET URI: rest/v1/oem/elcm/onlineupdate/updatecollection Method: GET Result: Behavior: URL Parameter: Input Data: Return Codes: Reads update check result. A list of links to all individual component update resources is returned in the body of the response message. HTTP status code 200 (OK) is returned on success. HTTP status code 404 (NOT FOUND) is returned if the requested component link does not exist. Page 13 of 100

14 HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: If successful, a list of links to all individual component update resources is returned in the body of the response message. No curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i rest/v1/oem/elcm/onlineupdate/updatecollection DELETE URI: rest/v1/oem/elcm/onlineupdate/updatecollection Method: DELETE Result: Behavior: URL Parameter: Input Data: Return Codes: Removes update check result. The irmc update entity checks if the update process referenced by the updatecollection resource is currently running. If so, the resource is retained, otherwise the irmc update entity deletes the updatecollection resource. HTTP status code 200 (OK) is returned if deletion of the updatecollection resource was successful. HTTP status code 409 (CONFLICT) is returned if the delete failed (e.g. updatecollection resource is currently running). HTTP status code 501 (NOT IMPLEMENTED) is returned if the delete method is performed on a specific component resource (e.g. URI as in PATCH method). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: No curl example: curl -u <uname>:<pwd> -H "Accept: application/xml" -X DELETE -i rest/v1/oem/elcm/onlineupdate/updatecollection/<component>/<subcomponent> GET URI: rest/v1/oem/elcm/onlineupdate/updatecollection/<component>/<subcomponent> Method: GET Result: Behavior: URL Parameter: Input Data: Return Codes: Reads updatable component details. Detailed update information about the requested component / subcomponent is returned in the response message body. HTTP status code 200 (OK) is returned on success. HTTP status code 404 (NOT FOUND) is returned on error. Page 14 of 100

15 HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: If successful, detailed update information is returned in the response message body. Comment: Creates LCM Session: No curl example: curl -u admin:admin -H "Accept: application/json" -X GET -i rest/v1/oem/elcm/onlineupdate/updatecollection/<component>/<subcomponent> PATCH URI: rest/v1/oem/elcm/onlineupdate/updatecollection/<component>/<subcomponent> Method: PATCH Result: Behavior: URL Parameter: Input Data: Return Codes: Changes updatable component flags. Allows modification of the component selection and reset flags of a specific resource under /rest/v1/oem/elcm/onlineupdate/updatecollection, where the resource is identified by the respective link. The flag settings provided as URL parameters. HTTP status code 200 (OK) is returned on success. HTTP status code 404 (NOT FOUND) is returned if the specified component does not exist. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or is the SD card is not mounted. Returned Data: Comment: Creates LCM Session: No curl example: curl -u admin:admin -H "Accept: application/json" -X PATCH -i Win/ServerView_RAID_E?Execution=deselected rest/v1/oem/elcm/onlineupdate/updatecollection PUT URI: rest/v1/oem/elcm/onlineupdate/updatecollection Method: PUT Result: Behavior: URL Parameter: Input Data: Return Codes: Starts update process. This method starts the configured component updates by creating a corresponding LCM session. Optional: tag HTTP status code 202 (ACCEPTED) is returned on success. HTTP status code 404 (NOT FOUND) is returned if any resource given in the command is not found. Page 15 of 100

16 HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 (e.g. not enough memory or task could not be created). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if e.g. the updatecollection resource does not exist or a resource is required (e.g. CD-ROM drive) which is occupied by another task. This status is also returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: If successful, provides the session ID in the body of the response message. The update job progress and result can be monitored by performing the GET method on the /sessioninformation/<sessionid>/status resource. Yes curl example: curl -u admin:admin -H "Accept: application/json" -X PUT -i Page 16 of 100

17 3.4 Offline Update rest/v1/oem/elcm/offlineupdate/configuration POST URI: rest/v1/oem/elcm/offlineupdate/configuration Method: POST Result: Behavior: URL Parameter: Input Data: Return Codes: Applies new repository configuration. Permanently applies the repository configuration for all elcm operations. \RepositoryConfiguration.xml HTTP status code 200 (OK) is returned on success. HTTP status code 400 (BAD REQUEST) is returned if RepositoryConfiguration.xml was not sent. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if another repository configuration operation is currently running. This status is also returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Create LCM Session: Session information Deprecated retained for backward compatibility only. Behaves exactly the same as rest/v1/oem/elcm/repositoryconfiguration POST, which should be used from now on. Yes curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X POST -i rest/v1/oem/elcm/offlineupdate POST URI: rest/v1/oem/elcm/offlineupdate Method: POST Result: Behavior: URL Parameter: Input Data: Prepares offline update. This method triggers the offline update preparation using the specified repository server information. Optional: bootenvironment : uefi or legacy (default=legacy) tag Optional: \RepositoryConfiguration.xml Return Codes: HTTP status code 202 (ACCEPTED) is returned on success. HTTP status code 404 (NOT FOUND) is returned if any resource given in the command is not found. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 (e.g. not enough memory or task could not be created). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if e.g. the OfflineUpdate resource already exists or a resource is required (e.g. CD-ROM drive) which is occupied by another task. This status is also returned if there is no valid elcm license Page 17 of 100

18 or the SD card is not mounted. Returned Data: Comment: If successful, the session ID is sent in the body of the response message. The progress of the update check can be monitored by performing the GET method on the /sessioninformation/<sessionid>/status resource. Creates LCM Session: Yes curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X POST -i rest/v1/oem/elcm/offlineupdate PUT URI: rest/v1/oem/elcm/offlineupdate Method: PUT Result: Behavior: URL Parameter: Input Data: Return Codes: Executes offline update. This method starts the execution of the offline update process. Optional: tag HTTP status code 202 (ACCEPTED) is returned on success. HTTP status code 404 (NOT FOUND) is returned if any resource given in the command is not found. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 (e.g. not enough memory or task could not be created). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if e.g. the OfflineUpdate resource does not exist or a resource is required (e.g. CD-ROM drive) which is occupied by another task. This status is also returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: curl example: If successful, the session ID is sent in the body of the response message. The progress and result of the offline update can be monitored by performing the GET method on the /sessioninformation/sessionid/status and /sessioninformation/sessionid/log resources. Yes curl -u <uname>:<pwd> -H "Accept: application/json" -X PUT -i /rest/v1/oem/elcm/offlineupdate Page 18 of 100

19 3.5 Dedicated Update rest/v1/oem/elcm/dedicatedupdate POST URI: rest/v1/oem/elcm/dedicatedupdate Method: POST Result: Behavior: URL Parameter: Input Data: Return Codes: Executes dedicated update. This function activates the update list. Optional: bootenvironment : uefi or legacy (default=legacy) tag JobList HTTP status code 202 (ACCEPTED) is returned on success. HTTP status code 400 (BAD REQUEST) is returned if the JobList cannot be processed because it may contain errors HTTP status code 406 (Unknowm MIME Type) is returned if unknown MIME type is used in request HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 HTTP return code 501 (NOT IMPLEMENTED) is returned if update list contains unknown parameters, e.g. Method = Online HTTP status code 503 (SERVICE UNAVAILABLE) is returned if dedicated update session cannot be established Returned Data: Comment: Creates LCM Session: Session information Yes curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X POST -i Page 19 of 100

20 3.6 Custom Images rest/v1/oem/elcm/customimage POST URI: rest/v1/oem/elcm/customimage Method: POST Result: Behavior: URL Parameter: Custom image download. This method downloads the ISO image file specified by the file URL parameter and creates a new resource under /rest/v1/oem/elcm/customimage when the download is finished. Obligatory: file Optional: bootenvironment tag Input Data: RepositoryConfiguration.xml Return Codes: HTTP status code 202 (ACCEPTED) is returned on success. HTTP status code 404 (NOT FOUND) is returned if any resource given in the command is not found. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 (e.g. not enough memory or task could not be created). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if e.g. the CustomImage resource already exists or a resource is required (e.g. CD-ROM drive) which is occupied by another task. This status is also returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: The response contains a relative location header referring to the custom image resource that will be created, and the session ID is sent in the body of the response message. It is possible to specify boot mode via the bootenvironment URL parameter with values uefi or legacy. If bootenvironment is not specified, legacy boot mode is used by default. The progress of the image file download can be monitored by performing the GET method on the /sessioninformation/<sessionid>/status resource. Yes curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X POST -i " rest/v1/oem/elcm/customimage GET URI: rest/v1/oem/elcm/customimage Method: GET Result: Behavior: URL Parameter: Input Data: Lists custom images. This method returns a list of links to all locally available custom image resources. Page 20 of 100

21 Return Codes: HTTP status code 200 (OK) is returned on success. HTTP status code 404 (NOT FOUND) is returned if any resource given in the command is not found. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: curl example: A list of links to all locally available custom image resources in the response message body. No curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i " rest/v1/oem/elcm/customimage/<imagename> GET URI: rest/v1/oem/elcm/customimage/<imagename> Method: GET Result: Behavior: URL Parameter: Input Data: Return Codes: Reads custom image metadata. This method returns the metadata stored with the custom image in the response message body. HTTP status code 200 (OK) is returned on success. HTTP status code 404 (NOT FOUND) is returned if the specified link does not exist. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: Metadata stored with the custom image in the response message body. No curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i " rest/v1/oem/elcm/customimage/<imagename> PUT URI: rest/v1/oem/elcm/customimage/<imagename> Method: PUT Result: Behavior: URL Parameter: Input Data: Return Codes: Executes custom image. This method executes the boot from the ISO image referenced by the respective URI. Initiates an LCM session. Optional: tag HTTP status code 202 (ACCEPTED) is returned on success. Page 21 of 100

22 HTTP status code 404 (NOT FOUND) is returned if any resource given in the command is not found. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 (e.g. not enough memory or task could not be created). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if e.g. the <ImageName> resource does not exist or a resource is required (e.g. CD-ROM drive) which is occupied by another task. This status is also returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: The session ID is sent in the body of the response message. The image execution can be monitored by performing the GET method on the /sessioninformation/<sessionid>/status resource. Yes curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X PUT -i " rest/v1/oem/elcm/customimage/<imagename> DELETE URI: rest/v1/oem/elcm/customimage/<imagename> Method: DELETE Result: Behavior: URL Parameter: Input Data: Return Codes: Deletes custom image. This method executes the boot from the ISO image referenced by the respective URI. Initiates an LCM session. HTTP status code 200 (OK) is returned on success. HTTP status code 400 (BAD REQUEST) is returned if the image name was not defined. HTTP status code 404 (NOT FOUND) is returned if deleting the image failed. HTTP status code 409 (CONFLICT) is returned if the image is currently mounted. Returned Data: Comment: Creates LCM Session: No curl example curl -u <uname>:<pwd> -H "Accept: application/json" -X DELETE -i " rest/v1/oem/elcm/customimage/download POST URI: rest/v1/oem/elcm/customimage/download Method: POST Result: Behavior: Custom image download. This method downloads the ISO image file specified by the url URL parameter and creates a new resource with the file name under /rest/v1/oem/elcm/customimage when the download is finished. Page 22 of 100

23 Creates an LCM session. URL Parameter: Obligatory: url e.g. including file name with.iso at the end! Optional: bootenvironment tag Input Data: Return Codes: HTTP status code 202 (ACCEPTED) is returned on success. HTTP status code 400 (BAD REQUEST) is returned if there is no url parameter or the image has no.iso extension. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 (e.g. not enough memory or task could not be created). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if e.g. the maximum number of images (currently 7) is reached or another elcm operation, which cannot be performed simultaneously, is already in progress. This status is also returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: curl example The response contains a relative location header referring to the custom image resource that will be created, and the session ID is sent in the body of the response message. It is possible to specify boot mode via the bootenvironment URL parameter with values uefi or legacy. If bootenvironment is not specified, legacy boot mode is used by default. The progress of the image file download can be monitored by performing the GET method on the /sessioninformation/<sessionid>/status resource. Yes curl -u <uname>:<pwd> -H "Accept: application/json" -X POST -i tag=customtag" rest/v1/oem/elcm/customimage/proxysettings GET URI: rest/v1/oem/elcm/customimage/proxysettings Method: GET Result: Behavior: URL Parameter: Input Data: Return Codes: Returns the current proxy settings for the custom image download. HTTP status code 200 (OK) is returned on success. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Proxy settings in XML or JSON format. <ProxySettings> <UseProxy>yes/no</UseProxy> Page 23 of 100

24 <Proxy> <URL></URL> <Port></Port> <User></User> <Password></Password> </Proxy> </ProxySettings > <Proxy> settings returned are the global irmc proxy settings. <UseProxy> setting is a dedicated setting for Custom Image. Comment: Creates LCM Session: curl example: No curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i CustomImage/ProxySettings rest/v1/oem/elcm/customimage/proxysettings PUT URI: rest/v1/oem/elcm/customimage/proxysettings Method: PUT Result: Behavior: URL Parameter: Input Data: Return Codes: Applies new proxy settings. ProxySettings HTTP status code 200 (OK) is returned on success. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5. HTTP status code 400 (BAD REQUEST) is returned if ProxySettings was not sent or the configuration file could not be parsed correctly. TTP status code 503 (SERVICE UNAVAILABLE) is returned if another repository configuration operation is currently running or there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: <ProxySettings> <UseProxy>yes/no</UseProxy> <Proxy> <URL></URL> <Port></Port> <User></User> <Password></Password> </Proxy> </ProxySettings > <Proxy> settings sent overwrite global irmc proxy settings. <UseProxy> setting sets the dedicated setting for Custom Image. Creates LCM Session curl example No curl -u <uname>:<pwd> -H "Accept: application/xml" -X PUT -i Page 24 of 100

25 3.7 Profile Management rest/v1/oem/elcm/profilemanagement/get POST URI: rest/v1/oem/elcm/profilemanagement/get Method: POST Result: Behavior: URL Parameter: Obtains current parameter values. This method instantiates a new LCM session, retrieving the parameter values addressed by the URL parameter PARAM_PATH. The resulting profile is written to the Profile Store, where the resource name is defined by the root of the JSON or XML tree contained in it. Obligatory: PARAM_PATH Optional: tag Input Data: Return Codes: HTTP status code 202 (ACCEPTED) is returned on success. HTTP status code 404 (NOT FOUND) is returned if any resource given in the command is not found. HTTP return code 409 (CONFLICT) is returned if a profile with that name already exists. HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 (e.g. not enough memory or task could not be created). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if another obtain or apply operation is currently running. Returned Data: Comment: Creates LCM Session: The session ID is sent in the body of the response message. The name of the newly created profile resource is returned as a relative location header in the response message. The progress of the current operation can be monitored by performing the GET method on the /sessioninformation/<sessionid>/status. Yes curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X POST -i rest/v1/oem/elcm/profilemanagement/set POST URI: rest/v1/oem/elcm/profilemanagement/set Method: POST Result: Behavior: URL Parameter: Input Data: Return Codes: Applies parameter values. This method creates an LCM session that applies the parameter values contained in the profile transferred in the request message body. Optional: tag \server.xml or \server.json or \<filename>.json xml HTTP status code 202 (ACCEPTED) is returned on success. HTTP status code 404 (NOT FOUND) is returned if any resource given in the command is not found. HTTP return code 409 (CONFLICT) is returned if a profile with that name already exists. Page 25 of 100

26 HTTP status code 500 (SERVER ERROR) is returned if an error occurred in the irmc S5 (e.g. not enough memory or task could not be created). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if another obtain or apply operation is currently running. Returned Data: Comment: Creates LCM Session: The session ID is sent in the body of the response message. The name of the newly created profile resource is returned as a relative location header in the response message. The progress of the current operation can be monitored by performing the GET method on the /sessioninformation/<sessionid>/status. Yes curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X POST -i rest/v1/oem/elcm/profilemanagement GET URI: rest/v1/oem/elcm/profilemanagement Method: GET Result: Behavior: URL Parameter: Input Data: Return Codes: Lists existing profiles. A list of links to all existing profiles in the store is returned in the body of the response message. HTTP status code 200 (OK) is returned on success. HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: curl example: A list of links to all existing profiles in the store is returned in the body of the response message. No curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i rest/v1/oem/elcm/profilemanagement/<profilename> GET URI: rest/v1/oem/elcm/profilemanagement/<profilename> Method: GET Result: Behavior: URL Parameter: Input Data: Return Codes: Reads profile. Returns the contents of the requested profile in the response message body. HTTP status code 200 (OK) is returned on success. HTTP status code 404 (NOT FOUND) is returned if the requested profile does not exist. Returned Data: Returns the contents of the requested profile in the response message body. Page 26 of 100

27 Comment: Creates LCM Session: No curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i rest/v1/oem/elcm/profilemanagement/capabilities GET URI: rest/v1/oem/elcm/profilemanagement/capabilities Method: GET Result: Behavior: URL Parameter: Input Data: Return Codes: Reads capabilities. Returns the list of supported parameters and actions directly underneath the parameter path specified by the URL parameter PARAM_PATH. The capabilities list is transferred in the response message body. Obligatory: PARAM_PATH HTTP status code 200 (OK) is returned on success. HTTP status code 404 (NOT FOUND) is returned if the requested profile does not exist. Returned Data: Comment: Creates LCM Session: The capabilities list is transferred in the response message body. No curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i rest/v1/oem/elcm/profilemanagement/<profilename> DELETE URI: rest/v1/oem/elcm/profilemanagement/<profilename> Method: DELETE Result: Behavior: URL Parameter: Input Data: Return Codes: Removes profile. Removes the specified profile resource from the Profile Store. HTTP status code 200 (OK) is returned on success. HTTP return code 404 (NOT FOUND) is returned if the profile does not exist. Returned Data: Comment: Creates LCM Session: Clearing the complete store with the DELETE method is not allowed; hence, performing the DELETE method on the /rest/v1/oem/elcm/profilemanagement resource causes the HTTP return code 501 (NOT IMPLEMENTED) to be sent. No Page 27 of 100

28 curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X DELETE -i rest/v1/oem/elcm/profilemanagement/version GET URI: rest/v1/oem/elcm/profilemanagement/version Method: GET Result: Behavior: Returns versioning of current implementation for elcm PMS profiles. Retrieves version of implemented support of server profile and for the following subprofiles supported by irmc: - AdapterConfig - IrmcConfig - BiosConfig The following subprofiles are only conditionally available if Service Platform is uploaded and available on irmc: - OsInstallation - HWConfiguration URL Parameter: Input Data: Return Codes: HTTP status code 200 (OK) is returned on success. HTTP return code 404 (NOT FOUND) is returned if the profile does not exist. Returned Data: Comment: Creates LCM Session: Example: <Server Version = "$a"> <AdapterConfigIrmc Version = "$b" /> <HWConfiguration Version = "$c" /> <! if available--> <OSInstallation Version = "$d" /> <! if available--> <SystemConfig> <IrmcConfig Version = "$e" /> <BiosConfig Version = "$f" /> </SystemConfig> </Server> No curl example: curl -u <uname>:<pwd> -H "Accept: application/json" -X GET -i Page 28 of 100

29 3.8 Deployment rest/v1/oem/elcm/svim/getostypesupport POST URI: rest/v1/oem/elcm/svim/getostypesupport Method: POST Result: Behavior: Input Data: Return Codes: Allocates internal resources for supported OS types for the Service Platform Image available in the repository. This request triggers the download and parsing of SVIMCatalogue.XML for the current system type. HTTP status code 200 (OK) is returned if the internal structures are allocated successfully and filled with supported OS types. HTTP status code 404 (NOT FOUND) is returned if the requested file cannot be found in the repository, cannot be parsed or the repository is not accessible. HTTP status code 501 (NOT IMPLEMENTED) is returned if the requested URI is not supported (e.g. wrongly formatted, URI with OSTypes badly specified, e.g. OSTyp or similar). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: Comment: Creates LCM Session: curl example: N/A URI is not case-sensitive! No curl -u <uname>:<pwd> -H "Accept: application/json" -X POST -i ipaddress/rest/v1/oem/elcm/svim/getostypesupport rest/v1/oem/elcm/svim/ostypes GET URI: rest/v1/oem/elcm/svim/ostypes Method: GET Result: Behavior: Returns supported OS types for the Service Platform Image available in the repository. This request returns a list of supported OS types for the current system type. Important: Please be aware that resources must be allocated via the command /GetOsTypeSupport POST. Otherwise the return code NOT_FOUND (404) is issued. Input Data: Return Codes: HTTP status code 200 (OK) is returned if the supported OS types are successfully returned. HTTP status code 400 (BAD REQUEST) is returned if the requested URI is wrongly defined (without OS types specified) or there are no resources allocated with the GetOsTypeSupport POST command. HTTP status code 404 (NOT FOUND) is returned if the requested file cannot be found in the repository, cannot be parsed or the repository is not accessible. This code is also returned if resources are not allocated. HTTP status code 501 (NOT IMPLEMENTED) is returned if the requested URI is not supported (e.g. wrongly formatted, URI with OSTypes badly specified, e.g. OSTyp or similar). HTTP status code 503 (SERVICE UNAVAILABLE) is returned if there is no valid elcm license or the SD card is not mounted. Returned Data: // [JSON format] // [XML format] Page 29 of 100