The Cisco UCS Manager (UCSM) is an embedded software agent providing access to the hardware and configuration management features of attached Cisco UCS hardware. The Management Information Model for the UCSM is organised into a structured heirachy of both physical and virtual objects. Accessing objects within the heirachy is done through a number of high level calls to heirachy search and traversal methods.

The primary aim of this package is to provide a simplified and abstract interface to this management heirachy.

Creates a connection to the XML API interface of a USCM management instance. If sucessful, the attributes of the UCSM management instance are inherited by the object. Most important of these parameters is 'cookie' representing the authetication token that uniquely identifies the connection and which is subsequently passed transparently on all further communications.

The default time-out value for a token is 10 minutes, therefore if you intend to create a long-running session you should periodicalily call refresh.

Expires the current authentication token. This method should always be called on completion of a script to expire the authentication token and free the current session for use by others. The UCS XML API has a maximum number of available connections, and a maximum number of sessions per user. In order to ensure that the session remain available (especially if using common credentials), you should always call this method on completion of a script, as an argument to die, or in any eval where a script may fail and exit before logging out;

Returns a Cisco::UCS::Fault object representing the specified error. Note that this is a caching method and will return a cached object that has been retrieved on previous queries should on be available.

If you require a fresh object, consider using the equivalent non-caching get_error method below.

Returns a Cisco::UCS::Fault object representing the specified error. Note that this is a non-caching method and that the UCSM will always be queried for information. Consequently this method may be more expensive than the equivalent caching method error described above.

This method is used to retrieve objects from the UCSM management heirachy by resolving the classId for specific object types. This method reflects one of the base methods provided by the UCS XML API for resolution of objects. The method returns an XML::Simple parsed object from the UCSM containing the response.

This method accepts a hash containing the value of the classID to be resolved and Unless you have read the UCS XML API Guide and are certain that you know what you want to do, you shouldn't need to alter this method.

This method is used to retrieve objects from the UCSM management heirachy by resolving several classIds for specific object types. This method reflects one of the base methods provided by the UCS XML API for resolution of objects. The method returns an XML::Simple object from the UCSM containing the parsed response.

Unless you have read the UCS XML API Guide and are certain that you know what you want to do, you shouldn't need to alter this method.

This method is used to retrieve objects from the UCSM management heirachy by resolving a specific distinguished name (dn) for a managed object. This method reflects one of the base methods provided by the UCS XML API for resolution of objects. The method returns an XML::Simple parsed object from the UCSM containing the response.

The method accepts a single key/value pair, with the value being the distinguished name of the object. If not known, the dn can be usually be retrieved by first using one of the other methods to retrieve a list of all object types (i.e. get_blades) and then enumerating the results to extract the dn from the desired object.

This method is used to resolve all child objects for a given distinguished named (dn) object in the UCSM management heirachy. This method reflects one of the base methods provided by the UCS XML API for resolution of objects. The method returns an XML::Simple parsed object from the UCSM containing the response.

In combination with Data::Dumper this is an extremely useful method for further development by enumerating the child objects of the specified dn. Note however, that the response returned from UCSM may not always accurately reflect all elements due to folding.

Unless you have read the UCS XML API Guide and are certain that you know what you want to do, you shouldn't need to alter this method.

This method is used to retrieve objects from the UCSM management heirachy by resolving the classId for specific object types matching a specified filter composed of any number of key/value pairs that correlate to object attributes.

This method is very similar to the <B>resolve_class method, however a filter can be specified to restrict the objects returned to thse having certain characteristics. This method is largely exploited by subclasses to return specific object types.

The filter is to be specified as any number of name/value pairs in addition to the classId parameter.

This method returns an anonymous hash representing a brief overall cluster status. In the standard configuration of a HA pair of Fabric Interconnects, this status is representative of the cluster as a single managed entity.

Returns a Cisco::UCS::MgmtEntity object for the specified management instance (either 'A' or 'B').

This is a caching method and will return a cached copy of a previously retrieved Cisco::UCS::MgmtEntity object should one be available. i If you require a fresh copy of the object then consider using the get_mgmt_entity method below.

Please see the Caching Methods section in NOTES for further information.

Returns a Cisco::UCS::ServiceProfile object where $ID is the user-specified name of the service profile.

This is a caching method and will return a cached copy of a previously retrieved Cisco::UCS::ServiceProfile object should one be available. i If you require a fresh copy of the object then consider using the get_service_profile method below.

Please see the Caching Methods section in NOTES for further information.

Returns a Cisco::UCS::Interconnect object for the specified interconnect ID (either A or B).

Note that the default behaviour of this method is to return a cached copy of a previously retrieved Cisco::UCS::Interconnect object if one is available. Please see the Caching Methods section in NOTES for further information.

Returns a Cisco::UCS::Blade object representing the specified blade as given by the value of $ID. The blade ID should be given using the standard Cisco UCS blade identification form as used in the UCSM CLI; namely chassis_id/blade_id where both chassis_id and blade_id are valid numerical values for the target cluster. Note that you will have to enclose the value of $ID in quotation marks to avoid a syntax error.

Note that this is a caching method and the default behaviour of this method is to return a cached copy of a previously retrieved Cisco::UCS::Blade object if one is available. If a non-cached object is required, then please consider using the equivalent get_blade method below.

Please see the Caching Methods section in NOTES for further information.

Returns a Cisco::UCS::Blade object representing the specified blade as given by the value of $ID. The blade ID should be given using the standard Cisco UCS blade identification form as used in the UCSM CLI; namely chassis_id/blade_id where both chassis_id and blade_id are valid numerical values for the target cluster. Note that you will have to enclose the value of $ID in quotation marks to avoid a syntax error.

Note that this method is non-caching and always queries the UCSM for information. Consequently may be more expensive than the equivalent caching blade method described above.

Returns a Cisco::UCS::Chassis object representing the chassis identified by by the specified value of ID.

Note that this is a caching method and the default behaviour of this method is to return a cached copy of a previously retrieved Cisco::UCS::Chassis object if one is available. If a non-cached object is required, then please consider using the equivalent get_chassis method below.

Please see the Caching Methods section in NOTES for further information.

This method generates a new "full state" type backup for the target UCS cluster. Internally, this method is implemented as a wrapper method around the private backup method. Required parameters for this method:

The username to be used for creation of the backup file on the backup host. This username should have write/modify file system access to the backup target location on the backup host using the protocol specified in the backup-proto attribute.

This method generates a new "all configuration" backup for the target UCS cluster. Internally, this method is implemented as a wrapper method around the private backup method. For the required parameters for this method, please refer to the documentation of the full_state_backup method.

This method generates a new "system configuration" backup for the target UCS cluster. Internally, this method is implemented as a wrapper method around the private backup method. For the required parameters for this method, please refer to the documentation of the full_state_backup method.

This method generates a new "logical configuration" backup for the target UCS cluster. Internally, this method is implemented as a wrapper method around the private backup method. For the required parameters for this method, please refer to the documentation of the full_state_backup method.

Several methods in the module return cached objects that have been previously retrieved by querying UCSM, this is done to improve the performance of methods where a cached copy is satisfactory for the intended purpose. The trade off for the speed and lower resource requirement is that the cached copy is not guaranteed to be an up-to-date representation of the current state of the object.

As a matter of convention, all caching methods are named after the singular object (i.e. interconnect(), chassis()) whilst non-caching methods are named get_<object>. Non-caching methods will always query UCSM for the object, as will requests for cached objects not present in cache.

The documentation could be cleaner and more thorough. The module was written some time ago with only minor amounts of time and effort invested since. There's still a vast oppotunity for improvement.

Better error detection and handling. Liberal use of Carp::croak should ensure that we get some minimal diagnostics and die nicely, and if used according to instructions, things should generally work. When they don't however, it would be nice to know why.

Detection of request and return type. Most of the methods are fairly explanatory in what they return, however it would be nice to make better use of wantarray to detect what the user wants and handle it accordingly.

Clean up of the UCS package to remove unused methods and improve the ones that we keep. I'm still split on leaving some of the methods common to most object type (fans, psus) in the main package.