RESTful Server Configuration with iDRAC RESTful API Dell EMC Customer Solutions Center November 2017 Authors Texas Roemer, Sr. Test Engineer (Dell EMC Server Solutions) Paul Rubin, Sr. Product Manager (Dell EMC Server Solutions) Jonas Werner, Sr.
Revisions Date Description June 2016 Initial release June 2017 Updated for 14th generation PowerEdge servers October 2017 Updated for iDRAC7/8 2.50.50.50 firmware November 2017 Corrected typos in section 2.7 The information in this publication is provided “as is.” Dell Inc. makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose.
Contents Revisions.............................................................................................................................................................................2 Executive summary.............................................................................................................................................................4 1 Introduction ...............................................................................................................................
Executive summary The growing scale of cloud- and web-based data center infrastructure is reshaping the needs of IT administration worldwide. New approaches to systems management are needed to keep up with a growing and changing market. To accommodate the needs for efficient systems management automation, Dell has developed the integrated Dell Remote Access Controller (iDRAC) with Lifecycle Controller RESTful API with support for the Distributed Management Task Force (DMTF) Redfish standard.
1 Introduction As the scale of deployment has grown for x86 servers, IT administrators have seen their scope expand from managing a handful of servers to hundreds or even thousands of servers. The deployment scale and the IT models have changed – from physical to virtual, from on-premises to cloud to hybrid cloud – leading to wholesale changes in the tools and processes of IT management.
A programmatic interface that can be easily controlled through scripts Ability to meet the Open Compute Project’s Remote Machine Management requirements Based on widely used standards for web APIs and data formats Redfish has been designed to support the full range of server architectures from monolithic servers to converged infrastructure and hyper scale architecture.
1.3 Configuring servers with Server Configuration Profiles Beginning with 12th generation PowerEdge servers, iDRAC with Lifecycle Controller has featured the use of Server Configuration Profiles (SCP) to configure BIOS, iDRAC, PERC RAID controller, and NIC/HBA settings in a single file. This greatly simplifies bare metal deployments and scale out operations by removing complexity from server configuration.
PowerEdge PowerShell cmdlets: Support WS-Man SCP operations via PowerShell scripting RACADM CLI: Provides SCP export, preview, and import operations via local SCP files in addition to network share-based SCP files For details on these features, see the Additional Information section. 1.3.1 New SCP features for iDRAC7 or iDRAC8, and iDRAC9 The introduction of 14th generation PowerEdge servers with iDRAC9 firmware 3.00.00.
2 Using iDRAC RESTful API with Server Configuration Profiles To create a Server Configuration Profile file for import to a new or to-be-reprovisioned server, create a “golden configuration” on a PowerEdge server. After the server is configured as needed, it can act as a template for other servers that need to use the same or similar server settings. To use these settings, an SCP file must be created by exporting the current server settings to a file.
2.1 Preparing to use SCP ExportSystemConfiguration method This section provides details about the creation of Python scripts for exporting a system configuration to a CIFS share by using a RESTful POST command. Before creating the Python script, two specific Python modules are needed: requests and json. If your version of Python does not have these modules installed, use “make-install” to install them. To begin the script, compile the URL for the POST command.
Script – redfish_SCP_export_cifs.v1.py: Version 1 # # Version 1 - Python iDRAC RESTful API script to export # server configuration profile # import requests, json url = 'https://192.168.0.120/redfish/v1/Managers/iDRAC.Embedded.1/Actions/Oem/EI D_674_Manager.ExportSystemConfiguration' payload = {"ExportFormat":"XML","ShareParameters":{"Target":"ALL","IPAddress":"1 92.168.0.130","ShareName":"cifs_share","ShareType":"CIFS","UserName":"user","Pas sword":"password","FileName":"R740xd_SCP.
Notice that Job ID is a value nested within a dictionary of a dictionary. We will now modify the script to access the dictionary and then parse the value using regular expressions to obtain the Job ID. The added code for this purpose is highlighted in the following script: Script – redfish_SCP_export_cifs.v2.py version 2: # # Version 2 - Python iDRAC RESTful API script to export # server configuration profile # import requests, json, re url = 'https://192.168.0.120/redfish/v1/Managers/iDRAC.Embedded.
$ $ python ./redfish_SCP_get_job_status.py JID_967983367454 Status code is: 200 Job ID = JID_967983367454 Name = Export: Server Configuration Profile Message = Successfully exported Server Configuration Profile JobStatus = Completed Now we combine and enhance the scripts to perform the SCP export and await completion of the export job: Script – redfish_SCP_export_cifs.v3.
print "\n- %s successfully created for ExportSystemConfiguration method\n" % (job_id) response_output=response.__dict__ job_id=response_output["headers"]["Location"] job_id=re.search("JID_.+",job_id).group() start_time=datetime.now() while True: req = requests.get('https://%s/redfish/v1/TaskService/Tasks/%s' % (idrac_ip, job_id), auth=(id rac_username, idrac_password), verify=False) statusCode = req.status_code data = req.json() message_string=data[u"Messages"] current_time=(datetime.
$ python ./redfish_SCP_export_cifs.v3.py 192.168.0.120 root calvin jwr_rf_exp.v3_02.xml - JID_967992694673 successfully created for ExportSystemConfiguration method - Query job ID command passed - Job not marked completed, current status is: Running - Message: Exporting Server Configuration Profile.
Script – redfish_SCP_export_http.py # Python script using Redfish API to perform iDRAC feature # Server Configuration Profile (SCP) for export to HTTP share only import requests, json, sys, re, time from datetime import datetime try: idrac_ip = sys.argv[1] idrac_username = sys.argv[2] idrac_password = sys.argv[3] file = sys.argv[4] except: print "\n- FAIL, you must pass in script name along with iDRAC IP/iDRAC username/iDRAC paasswo rd/file name" sys.exit() url = 'https://%s/redfish/v1/Managers/iDRAC.
data = req.json() message_string=data[u"Messages"] current_time=(datetime.now()-start_time) if statusCode == 202 or statusCode == 200: print "\n- Query job ID command passed" time.sleep(10) else: print "Query job ID command failed, error code is: %s" % statusCode sys.exit() if "failed" in data[u"Messages"] or "completed with errors" in data[u"Messages"]: print "Job failed, current message is: %s" % data[u"Messages"] sys.exit() elif data[u"TaskState"] == "Completed": print "\nJob ID = "+data[u"Id"] print "Na
- Query job ID command passed Job ID = JID_968007336828 Name = Export: Server Configuration Profile Message = Successfully exported Server Configuration Profile JobStatus = Completed JID_968007336828 completed in: 0:00:13 $ 2.4 Exporting SCP to a streamed local file Exporting SCP directly to a local file is supported with iDRAC7/iDRAC8 with firmware version 2.50.50.50 or later, and with iDRAC9 firmware version 3.00.00.00 or later.
response_output=response.__dict__ job_id=response_output["headers"]["Location"] try: job_id=re.search("JID_.+",job_id).group() except: print "\n- FAIL: detailed error message: {0}".format(response.__dict__['_content']) sys.exit() start_time=datetime.now() while True: current_time=(datetime.now()-start_time) req = requests.get('https://%s/redfish/v1/TaskService/Tasks/%s' % (idrac_ip, job_id), auth=(id rac_username, idrac_password), verify=False) d=req.
statusCode = req.status_code data = req.json() message_string=data[u"Messages"] current_time=(datetime.now()-start_time) if statusCode == 202 or statusCode == 200: print "\n- Execute job ID command passed, checking job status...\n" time.sleep(1) else: print "Execute job ID command failed, error code is: %s" % statusCode sys.exit() if str(current_time)[0:7] >= "0:10:00": print "\nFAIL, Timeout of 10 minutes has been reached before marking the job completed." sys.
Job ID = JID_963619479070 Name = Export: Server Configuration Profile Message = Successfully exported Server Configuration Profile JobStatus = Completed JID_963619479070 completed in: 0:00:04 Exported attributes are also saved in file: 2017-6-2_11555_export.xml 2.5 Previewing SCP imports with iDRAC RESTful API Before importing an SCP to apply configuration settings to a server, it is recommended to preview the SCP file using the ImportSystemConfigurationPreview method.
sys.exit() job_id=re.sub("[,']","",z) if response.status_code != 202: print "\n- FAIL, status code not 202\n, code is: %s" % response.status_code sys.exit() else: print "\n- PASS, %s successfully created for ImportSystemConfigurationPreview method\n" % (job _id) response_output=response.__dict__ job_id=response_output["headers"]["Location"] job_id=re.search("JID_.+",job_id).group() start_time=datetime.now() while True: req = requests.
python ./redfish_SCP_import_preview.py 192.168.0.120 root calvin jwr_rf_exp.v3_02.xml - PASS, JID_968020063229 successfully created for ImportSystemConfigurationPreview method - PASS, Query job ID command passed - Job not marked completed, current status is: Running - Message: Previewing Server Configuration Profile. - PASS, Query job ID command passed - Job not marked completed, current status is: Running - Message: Previewing Server Configuration Profile.
Note: viewconfigresults not yet available via the RESTful API. The following example shows a preview involving an SCP file that contains an error. The preview script that generates an error will be run and then we will use RACADM to obtain details on the error: python ./redfish_SCP_import_preview.py 100.65.99.196 root calvin jwr_rf_exp.v3_02.
Note that the return message accurately states that the value that was passed is “Not one of the Possible Values for Attribute” If racadm is used to get more detail of the error, we get the following output $ racadm -r 192.168.0.120 -u user -p password lclog viewconfigresult -j JID_968022511916 SeqNumber = 34743 Job Name = Preview Configuration Message ID = SYS088 Message = Estimated time for applying configuration changes is 0 seconds. SeqNumber = 34741 FQDD = LifecycleController.Embedded.
Whether the server is powered on (default) or powered off after the SCP import is completed Specify a timeout period when awaiting an OS graceful shutdown (default is 1800 seconds) Indicate the type of server shutdown to be performed after the SCP is imported - Graceful OS shutdown (default) Forced OS shutdown No reboot is to be performed, postponing application of the SCP import until a server shutdown is later commanded Note: Depending on the type of configuration object being modified by an SCP
sys.exit() job_id=re.sub("[,']","",z) if response.status_code != 202: print "\n- FAIL, status code not 202\n, code is: %s" % response.status_code sys.exit() else: print "\n- %s successfully created for ImportSystemConfiguration method\n" % (job_id) response_output=response.__dict__ job_id=response_output["headers"]["Location"] job_id=re.search("JID_.+",job_id).group() start_time=datetime.now() while True: req = requests.
data = req.json() print "Job ID = "+data[u"Id"] print "Name = "+data[u"Name"] print "Message = "+data[u"Messages"] print "JobStatus = "+data[u"TaskState"] Now we will execute the above import script. After the import job is marked complete, failed, or completed with errors, we will execute the RACADM command lclog viewconfigresult to get more information on the import job. $ python ./redfish_SCP_import_cifs.py 192.168.0.120 root calvin jwr_rf_exp.v3_02.
2.7 Importing SCP with Firmware Repository Update Beginning with iDRAC9 firmware 3.00.00.00 and iDRAC7/8 firmware 2.50.50.50, SCP import files support a new attribute RepostoryUpdate which points to a PowerEdge firmware repository created by Dell Repository Manager. The repository file must be stored in the same directory or a sub-directory of the directory holding the SCP import file. RepositoryUpdate can specify a directory, in which case iDRAC will search there for the default repository named "Catalog.
0 0 Profiles/Repositories/ If our is called “http_root” we can use “find” to display the directories and files to get an idea of the folder structure. [root@localhost http_root]# find . . ./Profiles ./Profiles/Repositories ./Profiles/Repositories/BIOS_firmware_WN64_1.0.3.EXE .
file = sys.argv[4] except: print "\n- FAIL, you must pass in script name along with iDRAC IP/iDRAC username/iDRAC paasswo rd/file name" sys.exit() url = 'https://%s/redfish/v1/Managers/iDRAC.Embedded.1/Actions/Oem/EID_674_Manager.ImportSystemCon figuration' % idrac_ip # For payload dictionary supported parameters, refer to schema # "https://'iDRAC IP'/redfish/v1/Managers/iDRAC.Embedded.1/" payload = {"ShutdownType":"Forced","ShareParameters":{"Target":"ALL","IPAddress":"192.168.0.
print "- Job ID = "+data[u"Id"] print "- Name = "+data[u"Name"] try: print "- Message = "+message_string[0][u"Message"] except: print "- Message = %s" % message_string[len(message_string)-1][u"Message"] print "\n- %s completed in: %s" % (job_id, str(current_time)[0:7]) sys.
2.9 Importing SCP from a streamed local file Configuration changes do not have to be located on a remote file share. It is fully possible to stream settings from a local file, or indeed specify specific settings directly in the code, from a local client machine. This feature requires iDRAC7/8 firmware 2.50.50.50 or later and iDRAC9 firmware 3.00.00.00 or later.
print "\n- FAIL: detailed error message: {0}".format(response.__dict__['_content']) sys.exit() job_id=re.sub("[,']","",z) if response.status_code != 202: print "\n- FAIL, status code not 202\n, code is: %s" % response.status_code sys.exit() else: print "\n- %s successfully created for ImportSystemConfiguration method\n" % (job_id) response_output=response.__dict__ job_id=response_output["headers"]["Location"] job_id=re.search("JID_.+",job_id).group() start_time=datetime.now() while True: req = requests.
data = req.json() print "Job ID = "+data[u"Id"] print "Name = "+data[u"Name"] print "Message = "+data[u"Messages"] print "JobStatus = "+data[u"TaskState"] $ python ./redfish_SCP_import_local_file.py 192.168.0.120 root calvin jwr_rf_clone.xml - JID_968285068285 successfully created for ImportSystemConfiguration method - Query job ID command passed - Job not marked completed, current status is: Running - Message: Importing Server Configuration Profile.
2.10 Cloning servers with iDRAC RESTful API Cloning servers saves considerable time and effort whether you do it for installing or re-deploying servers, or to ensure that nodes in a cluster conform to certain specified settings. Cloning helps in minimizing configuration discrepancies among cluster nodes by protecting configuration from human errors. A server source image can be created from a known-good configuration and then imported to multiple servers.
were displayed when verifying them using the browser session. Using the wrong order may cause the export to fail or the option to be ignored. Script: redfish_SCP_export_clone.py # Python script using Redfish API to perform iDRAC feature # Server Configuration Profile (SCP) for export only with clone enabled import requests, json, sys, re, time from datetime import datetime try: idrac_ip = sys.argv[1] idrac_username = sys.argv[2] idrac_password = sys.argv[3] file = sys.argv[4] except: print "\n- FAIL, you mu
req = requests.get('https://%s/redfish/v1/TaskService/Tasks/%s' % (idrac_ip, job_id), auth=(id rac_username, idrac_password), verify=False) statusCode = req.status_code data = req.json() message_string=data[u"Messages"] current_time=(datetime.now()-start_time) if statusCode == 202 or statusCode == 200: print "\n- Query job ID command passed" time.sleep(10) else: print "Query job ID command failed, error code is: %s" % statusCode sys.
Applying a source configuration image to a target server 2.12 The configuration files resulting from exporting settings using the Clone options can be imported just as easily and in the same fashion as any other configuration file using the import scripts previously shown. Utilizing the script which was modified to include the ExportUse option the source image configuration is first exported. $ python ./redfish_SCP_export_clone.py 192.168.0.120 root calvin jwr_rf_clone.
2.12.2 Importing the cloned SCP to the target server The SCP import script require no modification for the cloning process and is used below. Since all settings are applied due to the clone setting it takes about 5 minutes to complete. The output has been shortened for brevity. $ python ./redfish_SCP_import_local_file.py 192.168.0.121 root calvin jwr_rf_clone.
2.13 Using partial SCP imports Backing up, restoring and cloning entire server configurations is useful but in some cases only small changes are required. For example, you might need to clone only a few BIOS settings. In such cases, XML imports are useful because it is possible to modify multiple settings in one go. This is in contrast to using RACADM single object set commands where each setting must be modified individually.
3 Tips, tricks, and suggestions 1. Depending on the execution environment, Python scripts may generate warnings that do not affect execution. The following example shows warning messages that may occur while running a Python script although the script returns the correct status code and job ID: $ rest_SCP_export_script.py C:\Python26\lib\site-packages\requests-2.10.0py2.6.egg\requests\packages\urllib3\util\ssl_.
response_output=response.__dict__ if response.status_code == 400: print "- ExportSystemConfiguration method failed to return job ID" get_error_string=response_output["_content"] message=re.search("@Message.ExtendedInfo.+?,",get_error_string).group().strip ("@Message.ExtendedInfo\":[{") print "- Error message is: \"%s\"" % message.strip(".\",") sys.exit() else: pass job_id=response_output["headers"]["Location"] job_id=re.search("JID_.+",job_id).
}, { u 'Message': u 'For more information run command - racadm lclog viewconfigresult -j JID_xxxxxxxxxxxx' }], u '@odata.id': u '/redfish/v1/TaskService/Tasks/JID_744092584176', u '@odata.context': u '/redfish/v1/$metadata#Task.Task', u 'TaskStatus': u 'Critical', u 'Messages@odata.
4 Summary Using the iDRAC RESTful API, administrators can obtain the configuration details of 12th, 13th and 14th generation Dell PowerEdge servers, preview the application of a configuration file to a server, and apply configuration files to establish BIOS, iDRAC, PERC RAID controller, NIC, and HBA settings. Dell is a committed leader in the development and implementation of open, industry standards.
5 Additional Information For more information on iDRAC with Lifecycle Controller, visit the Dell TechCenter. Overview of the iDRAC Redfish API http://en.community.dell.com/techcenter/extras/m/white_papers/20442330 DMTF white papers, Redfish Schemas, specifications, webinars, and work-in-progress documents https://www.dmtf.org/standards/redfish The Redfish standard specification is available from the DMTF website http://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.0.1.
A.1 Verifying iDRAC RESTful API with Redfish service is enabled Before running any iDRAC RESTful API with Redfish workflows, verify that Redfish support is enabled default setting is Enabled. Redfish service enablement can be verified with WS-MAN, the RACADM CLI, or the iDRAC GUI. Verifying whether Redfish is enabled using WS-MAN C:\>winrm g http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/DCIM_iDRACCard Enumeration?InstanceID=iDRAC.Embedded.1#Redfish.1#Enable -u:username -p:password -r:https:/ /192.168.
Enabling iDRAC RESTful API with Redfish service via iDRAC7/8 GUI Enabling iDRAC RESTful API with Redfish service via iDRAC9 GUI 48 RESTful Server Configuration with iDRAC RESTful API
A.2 iDRAC RESTful API – SCP Export, Preview, and Import APIs Using any iDRAC-supported web browser, the various parameters used for RESTful SCP export, preview and import operations can be viewed. Start an iDRAC-supported web browser and enter this URL: https:///redfish/v1/Managers/iDRAC.Embedded.1 After entering the URL, input the iDRAC administrator user name and password when prompted. After you enter the credentials, JSON output similar to the one shown below is displayed.
"IncludeInExport@Redfish.AllowableValues": [ "Default", "IncludeReadOnly", "IncludePasswordHashValues", "IncludeReadOnly,IncludePasswordHashValues" ], "ShareParameters": { "IgnoreCertificateWarning@Redfish.AllowableValues": [ "Disabled", "Enabled" ], "ProxySupport@Redfish.AllowableValues": [ "Disabled", "EnabledProxyDefault", "Enabled" ], "ProxyType@Redfish.AllowableValues": [ "HTTP", "SOCKS4" ], "ShareParameters@Redfish.
"target": "/redfish/v1/Managers/iDRAC.Embedded.1/Actions/Oem/EID_674_Manager.ExportSystemC onfiguration" }, "OemManager.v1_0_0#OemManager.ImportSystemConfiguration": { "HostPowerState@Redfish.AllowableValues": [ "On", "Off" ], "ImportSystemConfiguration@Redfish.AllowableValues": [ "TimeToWait", "ImportBuffer" ], "ShareParameters": { "IgnoreCertificateWarning@Redfish.AllowableValues": [ "Disabled", "Enabled" ], "ProxySupport@Redfish.
"IDRAC", "BIOS", "NIC", "RAID" ] }, "ShutdownType@Redfish.AllowableValues": [ "Graceful", "Forced", "NoReboot" ], "target": "/redfish/v1/Managers/iDRAC.Embedded.1/Actions/Oem/EID_674_Manager.ImportSystemC onfiguration" }, "OemManager.v1_0_0#OemManager.ImportSystemConfigurationPreview": { "ImportSystemConfigurationPreview@Redfish.AllowableValues": [ "ImportBuffer" ], "ShareParameters": { "IgnoreCertificateWarning@Redfish.AllowableValues": [ "Disabled", "Enabled" ], "ProxySupport@Redfish.
"CIFS", "HTTP", "HTTPS" ], "Target@Redfish.AllowableValues": [ "ALL" ] }, "target": "/redfish/v1/Managers/iDRAC.Embedded.1/Actions/Oem/EID_674_Manager.
