Purpose
The goal of Recite is to provide a simple and fast interface for the Dell Lifecycle Controller API. It has an interactive mode that is useful to run one off commands against a server as well as batch mode to allow automating a sequence of operations.
Getting Recite
Recite is provided as a standalone Python script. A Windows executable that bundles the required Python environment is also available.
The Recite source code can be checked out of GIT as follows:
> git clonehttps://github.com/dell/recite.git
Contact
To get help or to provide feedback, recommendations or even patches, send a note to the linux-poweredge@dell.com mailing list.
Sign up for the mailing list here.
Requirements
Client:
Python version 2.4, 2.5 or 2.6
Windows XP or greater with Windows Remote Management (winrm)
Linux with Web Services for Management client (wsmancli)
Builds available here
Server:
Dell 11G servers
iDRAC Enterprise 1.70 (racks and towers), 3.21 (blades) or greater
Dell Lifecycle Controller 1.5 or greater
Dell 12G servers
Dell 13G servers
Documentation
This wiki page goes over many of the features and capabilities of Recite. This information is also included in the README document shipped with Recite. An introductory presentation that describes Recite is also available.
Also check out this video to become more familiar with using Recite.
(Please visit the site to view this video)
Getting Started
Following are some typical commands to get started using Recite and the LC remote API.
Basic Inventory
Set target machine IP
> set $IP 10.0.0.1
> set $IP idrac.dell.com
Get system information
> GetSystemViews
Get firmware levels
> GetSoftwareIdentities
Get all BIOS attributes
> GetBIOSEnumerations
> GetBIOSStrings
> GetBIOSIntegers
Get NIC details
> GetNICViews
> GetNICEnumerations
> GetNICStrings
> GetNICIntegers
Get RAID details
> GetControllerViews
> GetVirtualDiskViews
> GetPhysicalDiskViews
> GetRAIDEnumerations
> GetRAIDStrings
> GetRAIDIntegers
Job Queue
> GetLifecycleJobs
Executing a job
Get value NumLock
> GetBIOSEnumeration InstanceID=BIOS.Setup.1-1:NumLock
Set to new value (if On, set to Off and vice versa)
> SetBIOSAttribute Target=BIOS.Setup.1-1 AttributeName=NumLock AttributeValue=Off
Create a job to execute
> CreateBIOSConfigJob Target=BIOS.Setup.1-1 RebootJobType=1
Save job ID just returned
> Find InstanceID $jid
Poll job ID for completion
> Until JobStatus=Completed GetLifecycleJob InstanceID=$jid
Show new value of NumLock
> GetBIOSEnumeration InstanceID=BIOS.Setup.1-1:NumLock
Command line
python recite.py [NAME1=VALUE1 NAME2=VALUE2] ["CMD1" "CMD2" ...] [batch1.win batch2.win] [FLAGS]
Set variable $NAME1 to VALUE1, $NAME2 to VALUE2 ...
Execute CMD1, CMD2 in order ...
Execute batch scripts in order and exit ...
Enter interactive mode if no scripts specified
Flags:
-q = exit after executing all commands
When multiple IPs specified:-
-c = close instance foreground windows on exit
-pX = maximum parallel instances at a time (default: 10)
-s = run instances silently, output appended to $IP.log
python recite.py IP=10.0.0.1,10.0.0.2,idrac.dell.com
Spawn three instances of Recite in separate windows, each with IP specified
python recite.py IP=username:password@10.0.0.1
Set $IP, $LOGIN and $PASS with a single assignment
python recite.py IP=username@10.0.0.1
Set $IP and $LOGIN and prompt for password on commandline for security purposes
python recite.py IP=username:password@10.0.0.1,username@idrac.dell.com
Spawn two intances with specfied $IP, $LOGIN and $PASS, prompt for password in latter
python recite.py IP=10.0.0.1-10.0.0.5,username@10.0.0.6-10.0.0.11
Specify IP ranges on commandline
python recite.py IP=IP.ini
Load IPs from file, one per line
10.0.0.1, user:pass@10.0.0.1 or user@10.0.0.1
10.0.0.1-10.0.0.5, user:pass@10.0.0.1-10.0.0.5, user@10.0.0.1-10.0.0.5
idrac.dell.com, user:pass@idrac.dell.com or user@idrac.dell.com
# comments a line
python recite.py IP=10.0.0.1 GetRSStatus GetLifecycleJobs
Execute GetRSStatus and GetLifecycleJobs on specified IP
Commands
Most of the API methods exposed by the Dell Lifecycle Controller WSMAN interface are supported.
CQL, WQL and association filters can be used with -cql, -wql and -assoc flags. E.g.
GetiDRACCardAttributes -cql="select * from DCIM_iDRACCardAttribute where GroupDisplayName='iDRAC Users' and AttributeName='UserName'"
The script also provides a list of common internal commands to allow for minimal programmatic functionality. These include:-
Command Shortcut
Batch
Clear
Context //
Count +
Find /
Findall /*
Gosub >>
Goto >
If ?
Log
Print <
Return
Set $
Sleep
Unset ~$
Until {
Use the help command in interactive mode to see further details on all available commands and methods and the required syntax.
Apart from the syntax described in help, commands can also be concatenated on methods. This allows for a cleaner syntax.
E.g.
CreateRAIDConfigJob Target=$ctlr RebootJobType=3 {ReturnValue=4096 /$jid=InstanceID
Perform Until loop
On success, perform Find operation
GetRSStatus {Status=Reloading {Status=Ready
Perform Until looking for Status=Reloading
Perform Until looking for Status=Ready
GetLifecycleJobs +$njob ?$njob=1 >End
Count number of jobs
If only one job, Goto End
Script execution is terminated if:
- A command returns an error. E.g. Find, Context, etc.
- A method returns no data. E.g. GetPhysicalDiskViews when no disks are present.
- A command has a syntax error
In order to ignore such errors and resume execution, prepend command with a -.
For example:
-Find InstanceID $id
-GetPhysicalDiskViews
Variables
Settable variables
The following variables are loaded from environment variables if available. If not, they are default initialized as specified.
$FORMAT
WS-MAN output is formatted as specified. Default: "normal"
Set $FORMAT xml
Set $FORMAT prettyxml
$IP
IP or hostname of the iDRAC against which WS-MAN commands are to be executed. Default: ""
Set $IP 10.0.0.1
Set $IP idrac.dell.com
Set $IP username:password@10.0.0.1
Set $IP username@10.0.0.1
$LOGIN
iDRAC username with WS-MAN privileges. Default: username
Set $LOGIN username
$PASS
iDRAC password. Default: password
Set $PASS dell123
$PORT
Port on the iDRAC against where WS-MAN service is listening. Default: 443
Set $PASS dell123
$PROGRAM
Set to True to use Recite interactively from an external program. Returns all output in XML format for easy interop. Forces: $FORMAT = xml, $VERBOSE = 1
$TIMER
If True, display time taken by WS-MAN command. Default: False
Set $TIMER True
$USLEEP
Default sleep delay in seconds used by until commands between method invocations.
Set $USLEEP 20
$UTIMEOUT
Default total delay in seconds used by until commands before giving up.
Set $UTIMEOUT 900
$VERBOSE
Control level of output from Recite where x is: 0 - Quiet, 1 - WS-MAN, 2 - Full
Set $VERBOSE x
Internal variables
$_BATCHFILE
Name of current batch file (including path) with \ and / replaced with _.
$_DATE
Current date and time in yyyymmddhhmmss format.
$_LOCALIP
IP of the local system where script is running.
$_LINE
Current line number in a batch script.
Interactive help
Following is the current list of functions currently supported by Recite. For additional information on a specific command, type "help <function>".
--> help
INTERNAL METHODS
----------------
Batch Clear
Context Count
Exit Find
Findall Gosub
Goto Help
If Log
Print Quit
Report Return
Set Sleep
Unset Until
BACKUP RESTORE METHODS
----------------------
BackupImage ClearBackupSchedule
GetBackupSchedule RestoreImage
SetBackupSchedule
BIOS METHODS
------------
ChangePassword CreateBIOSConfigJob
DeletePendingBIOSConfiguration GetBIOSEnumeration
GetBIOSEnumerations GetBIOSInteger
GetBIOSIntegers GetBIOSString
GetBIOSStrings SetBIOSAttribute
SetBIOSAttributes
BOOT METHODS
------------
ChangeBootOrderByInstanceID ChangeBootSourceState
GetBootConfigSetting GetBootConfigSettings
GetBootSourceSetting GetBootSourceSettings
EVENT FILTER METHODS
--------------------
GetEventFilterView GetEventFilterViews
SetEventFilterByCategory SetEventFilterByInstanceIDs
FC METHODS
----------
CreateFCConfigJob DeletePendingFCConfiguration
GetFCAttributes GetFCCapabilities
GetFCCapability GetFCEnumeration
GetFCEnumerations GetFCInteger
GetFCIntegers GetFCStatistic
GetFCStatistics GetFCString
GetFCStrings GetFCView
GetFCViews SetFCAttribute
SetFCAttributes
iDRAC METHODS
-------------
ApplyAttributes CreateiDRACConfigJob
DeletePendingiDRACConfiguration DeleteSSLCertificate
ExportSSLCertificate GenerateSSLCSR
GetiDRACCardAttributes GetiDRACCardEnumeration
GetiDRACCardEnumerations GetiDRACCardInteger
GetiDRACCardIntegers GetiDRACCardString
GetiDRACCardStrings GetiDRACCardView
GetiDRACCardViews ImportSSLCertificate
SSLResetCfg SetiDRACAttribute
SetiDRACAttributes iDRACReset
iDRACResetCfg
JOB METHODS
-----------
CreateRebootJob DeleteJobQueue
GetLifecycleJob GetLifecycleJobs
SetupJobQueue
LC METHODS
----------
ClearProvisioningServer CreateLCConfigJob
ExportCertificate ExportCompleteLCLog
ExportFactoryConfiguration ExportHWInventory
ExportLCLog ExportSystemConfiguration
ExportTechSupportReport ExportePSADiagnosticsResult
GetConfigResults GetLCEnumeration
GetLCEnumerations GetLCInteger
GetLCIntegers GetLCString
GetLCStrings GetRSStatus
GetRemoteServicesAPIStatus GetSystemQuickSyncViews
ImportSystemConfiguration ImportSystemConfigurationPreview
InsertCommentInLCLog LCWipe
ReInitiateDHS RunePSADiagnostics
SetLCAttribute SetLCAttributes
SetPublicCertificate SystemErase
TestNetworkShare UpdateOSAppHealthData
LICENSE METHODS
---------------
DeleteLicense ExportLicense
ExportLicenseByDevice ExportLicenseByDeviceToNetworkShare
ExportLicenseToNetworkShare GetLicensableDevice
GetLicensableDevices GetLicense
GetLicenses ImportLicense
ImportLicenseFromNetworkShare ReplaceLicense
ShowLicenseBits
NIC METHODS
-----------
CreateNICConfigJob DeletePendingNICConfiguration
GetHostNetworkInterfaceViews GetNICAttributes
GetNICCapabilities GetNICCapability
GetNICEnumeration GetNICEnumerations
GetNICInteger GetNICIntegers
GetNICStatistic GetNICStatistics
GetNICString GetNICStrings
GetNICView GetNICViews
SetNICAttribute SetNICAttributes
OSD METHODS
-----------
BootToHD BootToISOFromVFlash
BootToNetworkISO BootToPXE
ConfigurableBootToNetworkISO ConnectNetworkISOImage
ConnectRFSISOImage DeleteISOFromVFlash
DetachDrivers DetachISOFromVFlash
DetachISOImage DisconnectNetworkISOImage
DisconnectRFSISOImage DownloadISOToVFlash
GetDriverPackInfo GetHostMACInfo
GetNetworkISOImageConnectionInfo GetOSDConcreteJob
GetOSDConcreteJobs GetRFSISOImageConnectionInfo
SkipISOImageBoot UnpackAndAttach
UnpackAndShare
POWER METHODS
-------------
GetPowerManagementCapabilities RequestPowerStateChange
RequestStateChange
PROFILE METHODS
---------------
GetCIMRegisteredProfile GetCIMRegisteredProfiles
GetLCRegisteredProfile GetLCRegisteredProfiles
RAID METHODS
------------
AssignSpare BlinkTarget
CheckVDValues ClearForeignConfig
ConvertToNonRAID ConvertToRAID
CreateRAIDConfigJob CreateVirtualDisk
DeletePendingRAIDConfiguration DeleteVirtualDisk
EnableControllerEncryption GetAvailableDisks
GetControllerBatteryViews GetControllerView
GetControllerViews GetDHSDisks
GetEnclosureEMMViews GetEnclosurePSUViews
GetEnclosureView GetEnclosureViews
GetPhysicalDiskView GetPhysicalDiskViews
GetRAIDEnumeration GetRAIDEnumerations
GetRAIDInteger GetRAIDIntegers
GetRAIDLevels GetRAIDString
GetRAIDStrings GetVirtualDiskView
GetVirtualDiskViews InitializeVirtualDisk
LockVirtualDisk PrepareToRemove
ReKey RemoveControllerKey
ResetConfig SecureErase
SetControllerKey SetRAIDAttribute
SetRAIDAttributes UnBlinkTarget
UnassignSpare
RECORD LOG METHODS
------------------
GetLCLogEntries GetLCLogEntry
GetLCRecordLogCapabilities GetLCRecordLogs
GetSystemEventLogCapabilities GetSystemEventLogEntries
GetSystemEventLogs SetLCLogEntryComment
ROLE BASED AUTHORIZATION
------------------------
GetUsersAssignedCLPPrivileges GetUsersAssignedLANPrivileges
GetUsersAssignedSerialOverLANPrivileges
SENSOR METHODS
--------------
GetNumericSensorView GetNumericSensorViews
GetSensorView GetSensorViews
SetNumericSensor SetSensorThreshold
SERVICE METHODS
---------------
GetAssociatedPowerManagementService GetClass
GetEFConfigurationService GetEPR
GetInstance GetPowerManagementService
Identify
SYSTEM METHODS
--------------
CreateSystemConfigJob DeletePendingSystemConfiguration
GetCPUView GetCPUViews
GetComputerSystems GetFanView
GetFanViews GetMemoryView
GetMemoryViews GetPCIDeviceView
GetPCIDeviceViews GetPCIeSSDBackPlaneViews
GetPCIeSSDExtenderViews GetPCIeSSDViews
GetPowerSupplyView GetPowerSupplyViews
GetSystemAttributes GetSystemEnumeration
GetSystemEnumerations GetSystemInteger
GetSystemIntegers GetSystemString
GetSystemStrings GetSystemView
GetSystemViews GetUSBDeviceViews
GetVideoView GetVideoViews
GetViews SetSystemAttribute
SetSystemAttributes
UPDATE METHODS
--------------
ClearUpdateSchedule GetRepoBasedUpdateList
GetSoftwareIdentities GetSoftwareIdentity
GetUpdateSchedule InstallFromRepository
InstallFromSoftwareIdentity InstallFromURI
SetUpdateSchedule
VFLASH MANAGEMENT METHODS
-------------------------
AttachPartition CreatePartition
CreatePartitionUsingImage DeletePartition
DetachPartition ExportDataFromPartition
FormatPartition GetVFlashPartitionViews
GetVFlashView GetVFlashViews
InitializeMedia ModifyPartition
VFlashStateChange
BASE METRIC METHODS
-------------------
GetAggregationMetricDefinition GetAggregationMetricDefinitions
GetAggregationMetricValue GetAggregationMetricValues
GetAvgPowerConsumptionByInterval PeakReset
PCSV METHODS
------------
GetPhysicalComputerSystemViews ModifyPersistentBootConfigOrder
RequestStateChange
Python API
Given Recite's limited programmatic capabilities, complex workflows that require more power are better of written in Python. Using Recite as a library is fairly simple. The code below demonstrates how to use Recite as a Python module.
import recite
# Get the current verbosity level
print recite.get_verbosity()
# Set the verbosity level
recite.set_verbosity(0)
# Set logfile to capture all WS-MAN data
recite.set_logfile("filename.txt")
# Set IP details
if recite.process("Set $IP username:password@10.0.0.1"):
print "Succeeded"
# Execute a simple command
if recite.process("GetRSStatus"):
print "Succeeded"
# Execute a script file
if recite.batch(filepath):
print "Succeeded"
# Execute a list of commands
commands = """
CreateBIOSConfigJob Target=BIOS.Setup.1-1 RebootJobType=3 {ReturnValue=4096 /$jid=InstanceID
GetLifecycleJob InstanceID=$jid {JobStatus=Completed
GetRSStatus {Status=Reloading {Status=Ready
"""
if recite.batch("workflow-name", commands):
print "Succeeded"
# Obtain the command line of the last WS-MAN command
print recite.get_input()
# Obtain the input XML of the last WS-MAN command (if applicable)
print recite.get_inputxml()
# Obtain the output of the last WS-MAN command
print recite.get_output()
# Obtain the XML output of the last WS-MAN command
xml = recite.get_outputxml()
# Obtain the XML object output of the last WS-MAN command
xml = recite.get_outputxmlobj()
# Get the full path to the script executing currently
path = recite.get_curr_scriptpath()