goUCS-README-v1.0.x

Cisco UCS Integration Guide for XML-based goUCS Automation Tool

Installation guide, syntax reference, and command reference examples

Eric Williams Technical Marketing Engineer

Cisco Systems, Inc. [email protected]

1 Document Version: 1.0.3 Last Updated: 3/10/2011 1:18 PM goUCS version 1.0.x – ©2011 Cisco Systems Inc.

mailto:[email protected]

Table of Contents

• What is goUCS? 3

• goUCS Pre-Requisites v1.0.x 4

• goUCS Automation Tool Installation 5

• goUCS Directory Structure 6

• What is a XML Wrapper? 7

• goUCS XML Wrapper Syntax 8

• What is a Command Wrapper? 14

• Executing Long Running Tasks with Command Wrappers 15

• goUCS Special Commands 16

• goUCS Debug / Troubleshooting 20

• Automation Example Utilizing goUCS 21

• Cisco UCS XMLAPI Overview Appendix 24

2

What is goUCS? goUCS is a toolkit that was created as a proof of concept to show how a UCS systems administrator could easily automate tasks across multiple UCS domains. Since the advent of UCS’s singular API, it has been clear to UCS admins the inherent power of being able to utilize and take advantage of this single API for use cases like auto-populating a central CMDB with the physical inventory of an entire UCS domain with one query; creating or modifying objects across multiple UCS domains like VLANs, policies, pools, etc.; and gathering data about a specific set of objects across UCS domains. goUCS was designed for a UCS sysadmin as an example of a flexible and extensible command line style interface that provides the basic framework for managing multiple UCS sessions and the communication to and from UCS via the XMLAPI; and parsing and displaying any returned XML data into multiple output formats like CSV, tables, indented hierarchical lists, and raw XML. goUCS enables the ability for a UCS sysadmin to learn at a much deeper level exactly how UCS communicates via the XMLAPI. What better way to learn than to actually perform the action in the UCSM GUI manually, use goUCS to filter the Java log file from the UCSM GUI for the exact XML method that the UCSM GUI used, and then provide a mechanism to replace the cookie and unique data in the XML document with variables enabling the UCS sysadmin to reuse the XML document over and over again programmatically. What was just described is a feature called a “XML wrapper” in goUCS. An XML wrapper allows the end user to take a parameterized XML document derived from UCS and use it as either a query or modification function on a set of UCS systems. With just a few unique XML wrappers, a UCS admin could query for the status of a blade(s), associate a service profile, create a VLAN, delete a policy, create a MAC pool, etc. The options are endless since the number of XML wrappers is not limited to what is shipped in the goUCS zip file. All the UCS sysadmin needs to do is extend goUCS by adding new XML wrapper functions by creating a parameterized XML file, and placing it in the XML Wrappers folder as described later in this document. Once the XML wrapper concept has been mastered, a goUCS user will have quickly realized goUCS’s ability to filter and format data via XML wrappers is deep, but can involve a lot of typing. goUCS command wrappers allow a goUCS user to take all of the appropriate user defined arguments from a XML wrapper command and input them into a templatized command that will execute the XML wrapper with the predefined variables. An example use case for a command wrapper would be using a query based XML wrapper to gather data from UCS about all blades in a UCS domain, but filtering the returned XML data to only display values for properties DN, numOfCpus, and totalMemory. Below shows this specific example of creating a scripted command from a XML wrapper and appropriate variables. The process type “realtime”, output type “table:*:dn-numOfCpus-totalMemory”, and XML wrapper arguments “computeBlade” and “false” were inserted into the templatized command wrapper named listblades_cpu_mem.

XML Wrapper: goucs class realtime table:*:dn-numOfCpus-totalMemory computeBlade false CMD Wrapper: goucs listblades_cpu_mem

As stated before, the options and depth of goUCS are endless. goUCS provides a UCS sysadmin the ability to automate anything a UCSM GUI can do, albeit querying for data; modifying existing objects in UCS; or even complex tasks like creating 10 service profiles from a template, associating them to 10 blades, and powering the 10 blades on all in one transaction. NOTE: If you have any questions, problems, or find any bugs with the goUCS tool and / or documentation, please feel free to email [email protected]. If

you have created any XML or CMD wrappers that you would like to share on Cisco Developer Network with the UCS community, please email [email protected] with a zip file that includes the XML and / or CMD wrapper with the appropriately documented help files and README.

DISCLAIMER: goUCS is a proof of concept tool that has been posted as freeware on Cisco Developer Network with no warranty or formal support from Cisco. Please use as

a development tool only. Use at your own risk, as it is NOT intended to be used in production. Please refer to Cisco Developer Network forums for assistance in using this tool as well as any notification of any potential bugs encountered. Feel free to edit <GOUCS_PATH>\lib\disclaimer.help to provide an appropriate disclaimer.

3







goUCS Pre-requisites v1.0.x • goUCS has been developed as a Windows only

– Has been tested and validated on Windows XP, 7, 2008, 2008 R2

• Only HTTP UCS XML API communication supported – NOTE: If UCS version 1.4 is being used, make sure “HTTP to HTTPS redirection” has been

disabled in the UCSM GUI.

• UCS versions 1.3 and 1.4 have both been tested and validated to work – NOTE: Earlier revisions should work as well, but have not been tested or validated

• Java JRE version 1.6 path needs to be defined in either the Windows System PATH variable or hard code the variable CLI_JAVA_JRE in <GOUCS_PATH>/lib/clienv.cmd to a specific JRE path. – EXAMPLE: CLI_JAVA_JRE=X:\PATH\to\java

4

goUCS Automation Tool Installation 1. Unzip goUCS.zip file to a local directory.

2. Add path to goUCS bin directory to Windows System PATH Variable – Example:

If the goUCS.zip file was extracted to the X:\ drive on your host, append X:\goucs\bin to the PATH system variable.

3. Install or update the Java JRE to version 1.6.

4. Confirm PATH variable is set properly, and the Java binary is available via the command line

① Run echo %PATH% at the command prompt to verify the path to goUCS bin directory was appended

② Run java –version at the command prompt to verify Java is installed properly

③ Run goucs at the command prompt to verify goUCS tool is working properly

2. Append path to goUCS bin directory here

4.1 Path appended properly

4.2 Java installed properly

4.3 Successful execution of goucs command

5

goUCS Directories in <GOUCS_PATH> Directory Description Files / Directories Included in base goUCS

Files / Directories Description

/bin Contains goUCS executables

goucs.cmd Main goUCS executable. To turn on cmd screen output debugging, change “@set CLI_scroutput=off” to “@set CLI_scroutput=on”

/cache Contains goUCS XML cache, saved transactions, and imported / exported XML files

Cache Stores cached XML files saved from outcache process type

Transaction Stores goUCS transaction files

Exported Stores unaltered XML files of exported DN sub-trees from UCS systems

Importable Stores importable XML files of DN sub-trees that have been cleansed of all operational (read-only) UCS data

/cmdwrappers

/cmdwrappers/<WRAPPER>/<WRAPPER>.cmd

/cmdwrappers/<WRAPPER>/<WRAPPER>.help

Contains goUCS scripted command wrappers

<WRAPPER>.cmd goUCS command wrapper executable

<WRAPPER>.help goUCS command wrapper help file

/help Contains goUCS globalized help files

XML_wrapper.help Common help file for XML wrappers needing exec type / print type help

Disclaimer.help Contains standard goUCS Disclaimer message, editable by end user

/lib Contains included libraries needed for goUCS execution

Clienv.cmd Contains goUCS variables. • If filterlog xml wrapper is having difficulties locating the UCSM

GUI java log files, then edit clienv.cmd and change the following line from “set CLI_LOGDIR=Automatic” to “set CLI_LOGDIR=X:\<PATH>\<TO>\<UCSM>\<LOG>\<FILES>”.

• Set CLI_LOG=1 to turn on goUCS XMLAPI communication debugging

configGen_13.jar

configGen_14.jar

Java libraries used with exportDN XML wrapper function to cleanse returned XML output from UCS system of operational (read-only) data

*.class

Java class files for goUCS

/log Contains goUCS XML API communication debug log files

<DATE>_sent.log

<DATE>_received.log

Log files detail XML documents both sent to UCSM from goUCS and returned from UCSM to goUCS. goUCS XML API debugging can be enabled by setting “CLI_LOG=1” in <GOUCS_PATH>/lib/clienv.cmd.

/session Contains goUCS session files

<SESSION>.cfg <SESSION>.cfg files contain the IP address / port, username, and password of UCS domains to be managed by goUCS.

<SESSION>.aut Contains encrypted cookie received from UCSM for <SESSION>

/xmlwrappers

/xmlwrappers/<WRAPPER>/<WRAPPER>.cmd

/xmlwrappers/<WRAPPER>/<WRAPPER>.help

Contains goUCS XML wrappers

<WRAPPER>.xml Parameterized XML file used for querying / configuring UCS systems

<WRAPPER>.help goUCS XML wrapper help file

goUCS Directory Structure

6

What is a XML Wrapper? In the Cisco UCS XMLAPI, there are a small number of XML methods that a UCS systems administrator or developer really needs to understand and use. The most important XMLAPI methods fall into four main categories: authentication (aaaLogin / aaaLogout), query (configResolveDn(s) / configResolveClass / configResolveChildren / configScope), configuration change (configConfMo(s) / configConfMoGroup), and event subscription (eventSubscribe). The aforementioned XML methods make up most of the XML communication that is performed between UCS Manager (UCSM) and the GUI / CLI. A goUCS XML wrapper allows the end user to take an XML document derived from UCS GUI to UCSM communication for example, replace the unique objects in the XML structure sent from the UCSM GUI to UCSM with variables, and provide the ability to re-use that parameterized XML document as either a query or modification function on a set of one or more UCS systems. By creating and utilizing a few unique XML wrappers, a UCS admin could query for the status of a blade(s), associate a service profile, create a VLAN, delete a policy, create a MAC pool, modify any UCS object, etc. The options are endless since the number of XML wrappers is not limited to what is shipped in the base goUCS zip file. A UCS sysadmin can extend goUCS’s base functionality by adding new XML wrapper functions by creating a parameterized XML file, and placing it in a new folder with the same name as the XML file in the goUCS XML wrappers folder with the appropriate help file describing usage of the new XML wrapper.

7

SPECIAL goUCS XML WRAPPERS Certain pre-defined XML wrappers have specialized functions within goUCS’s base functionality. These XML wrapper functions should not be edited. • SESSION

• All – Execute XML wrapper against all actively logged in sessions • ListCurrentSessions – Lists all actively logged in sessions • Login – Logs in a Session • Logout – Logs out a Session • Connect – Opens UCS GUI to appropriate session name

• TRANSACTION • Begin – Creates new goUCS transaction file • End – Closes a goUCS transaction file • ListTransactions – Lists available transactions • RmTransaction – Removes a transaction • Run – Runs a transaction

• XML IMPORT / EXPORT • ImportDn – Imports DN tree from a UCS system • ExportDn – Exports DN tree cleansed of operational data into a UCS sys. • ListExported – Lists all exported DN sub-tree’s XML file names • ListImportable – Lists all importable DN sub-tree’s XML file names

• MISCELLANEOUS • Filterlog – Filters UCS GUI java log files • Raw – Sends raw XML files to UCS • SetKey – Sets encryption / decryption key for encrypting passwords

goUCS HELP FILES Every XML wrapper folder should contain both a XML file and HELP file. Help files contain usage about a specific XML or command wrapper. The following is an example that would display the help file for a specific XML or command wrapper: goucs <XML_WRAPPER> /?

• goUCS Help File Macros – Help file macros, which are optional, provide the ability to inject a common help file in the <GOUCS_PATH>/help directory within a specific XML or command wrapper’s help file. Macros are intended to be used as a way to document commonly used parameters once by providing the ability to provide a pointer to a common goUCS help file. A single help file can have multiple macros defined. Nested macros (a common help file with an embedded that macro injects the contents of another help file with a macro, etc.) are supported. The following is an example what would need to be included to reference the “XML_wrapper.help” file located in the <GOUCS_PATH>/help directory:

<insert=”XML_wrapper"/>

• General goUCS help – Executing goucs /? will display all available XML and command wrappers. This command automatically display any newly created XML or command wrapper

goUCS EXIT CODES Every time a goUCS command is run, goUCS sets the appropriate exit code upon success (exit code is set to “0”) or failure (exit code is set to “1”).

goUCS XML Wrapper Syntax X:\goucs <session> <xml wrapper> <process type> <output type> <user args>

Session: • Session files are located in <GOUCS_PATH>\session directory • Can create multiple session files, providing the ability to manage many UCS domains • Contains IP address, web server port, and credentials of a UCS domain to manage

• Example: IP=192.168.0.130:80

USER=admin

PASSWORD=p@ssw0rd

• First time a session file is read by goUCS, the unencrypted password will be encrypted, removed, and replaced with an encrypted

password in the session file. • SETKEY – A goUCS command that enables the ability to set a key which is used for password encryption in the goUCS

session configuration files. Once a password in a goUCS session file is encrypted using key provided by the user in setkey command, it can only be decrypted by providing the same key with setkey xml wrapper for every new MS-DOS shell session. The maximum number of characters supported is eight.

• Example: goucs setkey <KEY> • A <SESSION_NAME>.aut file is created when goUCS has successfully logged into the appropriate UCS system. The .aut file is

an encrypted file that contains the authentication cookie from the appropriate UCS system. A goUCS command can be run without implicitly logging in first. If a session cookie aut file is not present, the goUCS will automatically login to the UCS system defined in the session file. If the session cookie in the aut file is invalid or expired, goUCS will try to refresh the cookie or create a new session.

• Session name is an optional parameter. If no session is defined in command, the DEFAULT session configuration will be used Reserved Session Names: Each session name must be unique. Session, XML wrapper, and command wrapper names must all be unique. The following session names Names are reserved, and can not be used for XML and command wrappers or user session names.

• DEFAULT – Default goUCS Session • ALL – Will run the command to all current actively logged in sessions

NOTE: • If you authenticate via an external UCS authentication domain like LDAP in UCS version 1.4 or later, the following user

naming convention will have to be used: ucs-<UCS Authentication Domain>\<username>

• For example is you have a UCS authentication domain called "demo" and a user called "bob", you need to put in: USER=ucs-demo\bob

Provides the ability to execute a single command against multiple UCS domains. This feature relies on the user running the appropriate “goucs <session> login” commands with the appropriate UCS sessions defined the user wants to manage. Each login command creates a session file with date and time stamp is the <GOUCS_PATH>\session\current folder. EXAMPLE: 1. Login to 2 UCS systems: 2. List Current Sessions goucs prod login goucs listcurrentsessions

goucs test login *Will list all currently active sessions

3. Perform a command on all 4 systems 4. Logout of all 4 active sessions goucs all listblades goucs all logout

HINT: If you have an old session that does not apply any longer, you can still use the logout command to

delete the session from the current folder 8


XML Wrapper Name: • Files located in <GOUCS_PATH>\xmlwrappers folder • Each XML wrapper folder contains a XML file and HELP file • Example:

X:\goucs\xmlwrappers\Class>dir

Class.help

Class.xml

• New XML Wrappers commands can be created by adding a new directory to the <GOUCS_PATH>\xmlwrappers folder, and adding a parameterized XML file and HELP file inside of the folder • XML Wrapper directory, XML file, and HELP file must have same name. A dollar sign

(“$”) may be placed at the end of the XML or command wrapper directory name to hide any XML or command wrapper function.

• Replace the real cookie in the XML file with the variable $COOKIE$. It is a requirement that cookie=“$COOKIE$” is present in each xml wrapper.

• Example parameterized XML file: <configResolveClass cookie="$COOKIE$" inHierarchical="$ARG2$"

classId="$ARG1$"/>

• $ARG1$ and $ARG2$ in this example attributes that have been replaced as variables, which are then used as parameters in the user arguments section of the xml wrapper.

NOTE: The maximum number of user arguments is limited to 10 at this time.

9


• EXPORTDN

Provides the ability to export an entire XML object stored in a UCS domain’s active XML object database by providing the appropriate DN of the desired XML tree to be exported. Running this command will create two XML files.

• Exported XML File: This file is a raw, comprehensive, direct copy of the object from the UCS domain’s active XML object database. It contains the object’s configuration detail, as well as the operational and state information that UCS stores about the object. This operational and state data is created automatically by UCS after the object is initially created in the UCS domain’s active XML object database.

• Importable XML file: This file has been created from the exported XML file that has been cleansed of the operational and state data. Only configuration data remains, which enables the file to have the ability to be imported via the IMPORTDN wrapper.

• Example: goucs exportdn fabric/lan/net-testvlan testvlan • Exported XML File Location: <GOUCS_PATH>\cache\Exported\testvlan.xml • Importable XML File Location: <GOUCS_PATH>\cache\Importable\testvlan.xml

• IMPORTDN Provides the ability to import an importable XML object into an active UCS domain. This wrapper only supports XML files that have been cleansed of operational and state data • CAUTION: When using the exportdn / importdn command, the importable XML file does not have a

status property defined. Without the status flag set to either create or modify, the import function will overwrite any data in the same subtree of the MIT the XML document is editing without providing an error that the item exists already. Use with caution, care, and a backup.

• Use the goucs listimportable command to list importable XML objects • Example: goucs importdn testvlan y

• Please note that the "y" in the end of the previous command denotes a "yes” answer to force importing of the object. Without this switch goUCS will prompt the user to answer either yes or no to confirm. 10


Process Types: • REALTIME (most commonly used process type)

• goUCS command is executed in real-time on the defined UCS session • Example: goucs test realtime class xml indent computeBlade

• RAW • Provides the ability to deliver a raw XML file to the defined UCS session. Requires the

cookie in the raw XML file to be replaced with $COOKIE$ as shown in the example below: <configResolveDn cookie="$COOKIE$" inHierarchical="false" dn="sys"/>

• Will load the XML file into memory, replace $COOKIE$ with the actual cookie, and send the XML document to the defined session. The resulting output will only be displayed in raw XML. • Example: goucs test raw MyRawXMLFile.xml

• OUTCACHE • goUCS command is executed in real-time on the defined UCS Session, but returned data is

stored in a local cache file <GOUCS_PATH>\cache\cached\cache.xml

• Example: goucs test class outcache xml computeBlade • INCACHE

• goUCS command is executed in real-time using the local cache file <GOUCS_PATH>\cache\cached\cache.xml as the data source. Does not connect to a UCS host, so no UCS session needs to be provided.

• Example: goucs class incache xml computeBlade 11


Output Type (page 1 of 2): • INDENT (Default Output Type)

• Prints the output in an indented list based on XML hierarchy. • Example: X:\>goucs class realtime indent topSystem

topSystem=

address=192.168.0.129

dn=sys

mode=cluster

name=machine

systemUpTime=02:23:04:07

• XML • Prints the output in native raw XML format • Example: X:\>goucs class realtime xml topSystem

<configResolveClass cookie=“" response="yes" classId="topSystem">

<outConfigs>

<topSystem address="192.168.0.129” dn="sys" mode="cluster" name="eric-pod"

systemUpTime="20:03:17:52"/>

</outConfigs>

</configResolveClass>

• QUIET • Suppresses any returned output data from being displayed when no errors occur with goucs command.

If the is an error (authentication, communication, etc.) with the command, goucs will not suppress

the error, and will print the error message. • Example: goucs class realtime quiet topSystem

• XPATH Based Output • xpath:<query> Prints out attribute and value / element from xpath query • axpath:<query> Prints out attribute value only from xpath query • fxpath:<query> Print out full path with in ‘/’ delimiters of elements, or attribute and value for attribute nodes. • Example: X:\>goucs cache xpath://@dn

12


Output Type (page 2 of 2): • Table and CSV Based Output

• Table – Formats the data to be displayed in a tabular form. Column headers are displayed by default. Use tablenh option to suppress the column headers

• CSV – Formats the data to be displayed in a comma-separated value form. Cell headers are displayed by default. Use csvnh option to suppress the column headers

Output Type Example Description

csv goucs class realtime csv computeBlade All returned data will be reformatted in either CSV or table form. NOTE: Default cell and table column width is 15 characters

csvnh

table goucs class realtime table computeBlade

tablenh

csv:<width|*> goucs class realtime csv:25 computeBlade All returned data will be reformatted in either CSV or table form. In this example, cell and column width has been overridden to 25 characters. NOTE: If width equals ‘*’ the cell and column width will not truncate, and will keep the original length of the column

csvnh:<width|*>

table:<width|*> goucs class realtime table:25 computeBlade

tablenh:<width|*>

csv:<width|*>:<column nameX>-<column nameY>

goucs class realtime csv:*:dn-numOfCpus computeBlade

Only the returned data that has been filtered by the desired columns will be reformatted in either CSV or table form. Cell and column width has been overridden to not truncate data. NOTE: Columns can either can either by the sequential number of the column to be displayed, or the property name that is to be displayed. In this example the dn and numOfCpus property types that will be displayed for all objects returned.

csvnh:<width|*>:<column nameX>-<column nameY>

table:<width|*>:<column nameX>-<column nameY>

goucs class realtime table:*:dn-numOfCpus computeBlade

tablenh:<width|*>:<column nameX>-<column nameY> 13

14

Variable Name Variable Value Description

CLI_XML_WRAPPER class Sets XML wrapper name invoked by the CMD wrapper

minUserArgs 1 Sets minimum number of User Args XML wrapper requires (acceptable value range is 1-10)

UserConfirmation disable If enabled, CMD wrapper will need a “yes” confirmation to execute. If “y” or “yes” confirmation is omitted, CMD will exit without executing

CLI_PROCESS realtime Sets XML wrapper process execution type

CLI_OUTPUT table:*:dn-

numOfCpus

Sets XML wrapper output type. In this example, set to table and displays computeBlade class properties dn and numOfCpus.

UserArg1 computeBlade Passes XML wrapper user arguments (max of 10). CMD wrappers can be passed user arguments via the command line as well. UserArgX variables (variables defined in a CMD wrapper that are sent to XML wrappers) can be set to %inUserArgX% (user variables provided to the CMD wrapper) which can be passed as user argument variables from the CMD wrapper to XML wrapper. For example:

goucs <session> <cmdwrapper> aaa bbb

aaa is the first argument mapped to inUserArg1, and bbb is the second argument mapped to inUserArg2. These arguments can be passed in any given order to the XML wrapper’s defined arguments. In this example, the class type computeBlade is passed from the command wrapper to the defined XML wrapper to query UCS.

What is a Command Wrapper? A goUCS user familiar with the power of goUCS’s ability to filter and format data via XML wrapper will quickly realize can involve a lot of typing and more potential points of human error. goUCS Command wrappers provide the ability via scripted commands to take the user defined argument variables from a XML wrapper and input them into a templatized goUCS command wrapper that will be executed with either some or all of the user argument variables being predefined. By providing the ability to predefine the user argument variables, it enables the goUCS commands to be shortened. XML wrapper arguments like process type and output type, as well as any of the 10 user argument variables can be predefined in the command wrappers. Command wrappers enables the end user to reuse the same XML wrapper for totally different use cases. XML wrappers and command wrappers do not require a 1:1 relationship in their usage. For example, a XML wrapper that queries UCS for all instances of a specified class could be used for multiple functions like listing all UCS blades by querying for the computeBlade class, listing all faults actively raise in UCS by querying for the faultInst class, or listing all service profiles in UCS by querying for the lsServer class, to name a few. An example use case for a command wrapper would be using a query based XML wrapper to gather data from UCS about all blades in a UCS domain, but filtering the returned XML data to only display the values for properties DN and numOfCpus. Below shows this specific example of creating a scripted command from a XML wrapper and appropriate variables. The process type “realtime”, output type “table:*:dn-numOfCpus”, and XML wrapper arguments “computeBlade” and “false” were inserted into the templatized command wrapper named listblades_cpu.

XML Wrapper: goucs class realtime table:*:dn-numOfCpus computeBlade CMD Wrapper: goucs listblades_cpu

CREATING COMMAND WRAPPERS EXAMPLE In this example, a command wrapper called listblades_cpu will be created that uses an xml wrapper called class and displays the UCS blades DN and number of CPUs: 1. Create a listblades_cpu directory in folder: X:\goucs\cmdwrappers

2. Copy the command wrapper HELP and CMD file from existing command wrapper ListBlades into the newly created X:\goucs\cmdwrappers\listblades_cpu directory.

3. Rename the CMD and HELP files in X:\goucs\cmdwrappers\listblades_cpu to the same name as listblades_cpu_mem directory. Command wrapper directory X:\goucs\cmdwrappers\listblades_cpu should now include the following two files:

a. listblades_cpu.help – Help file for the command wrapper b. listblades_cpu.cmd – Command wrapper executable

4. Modify the listblades_cpu.cmd file and change the variables to the values as described in the table to the right.

5. Modify the listblades_cpu.help file to reflect the usage of the newly created command wrapper to be used for goUCS inline help.

6. Run the newly created command wrapper against a UCS system Example: X:\>goucs <session> listblades_cpu

dn numOfCpus

--------------------- ---------

sys/chassis-1/blade-2 2

Executing Long Running Tasks with Command Wrappers Some tasks in UCS are long running, like a service profile association. To understand this deeper, the end user needs to know how transactions work within UCS. For example, when sending a XML document asking UCS to associate a service profile to a particular blade, UCS Manager validates the request, applies the configuration changes to the UCS XML database if the request is valid, and sends a response back to the original sender stating if request was accepted successfully. The aforementioned response is just a response confirming that the request was accepted and the process was successfully started. From that point on, UCS Manager will start a longer workflow (FSM) that could take anywhere from five to ten minutes. UCS Manager will perform all necessary operations to complete the service profile association; like updating the server’s firmware (BIOS, adapters, CIMC, etc.), firmware settings, and network configuration (VLAN, VSAN, QoS, etc.). Because of tasks like these, goUCS command wrappers provides the ability to monitor workflows, which will allow a goUCS end user to create a command that will wait for the workflow to complete successfully or will timeout. To monitor the status of the running workflow, two types of communications methods are supported, one via XML query (status pulled from UCSM) and the preferred method via event subscription (status updates pushed from UCSM in near real time). If XML query based monitoring is used, goUCS will poll UCSM every minute monitoring the value of CLI_WAIT_ATTRIBUTE_VALUE for the UCS attribute defined in CLI_WAIT_ATTRIBUTE, which are both located in the command wrapper being executed. If event subscription based monitoring is used, goUCS will monitor the event subscription stream in realtime monitoring the value of CLI_WAIT_EVENT_ATTRIBUTE_VALUE for the UCS attribute defined in CLI_WAIT_EVENT_ATTRIBUTE, which are both located in the command wrapper being executed. The command wrapper will either exit when either a successful poll or an event via the subscription stream is sent by UCSM providing the value defined in either the CLI_WAIT_ATTRIBUTE_VALUE (pull) or CLI_WAIT_EVENT_ATTRIBUTE_VALUE (push) variable, or when the time value provided in either the CLI_WAIT_MINUTES (pull) or CLI_WAIT_EVENT_MINUTES (push) variable has expired.

Example: Execute goucs ReAssociateSp org-root/ls-bob sys/chassis-1/blade-1. ReAssociateSp is a scripted command that executes the ReAssociateSp XML wrapper to request association of service profile org-root/ls-bob to blade sys/chassis-1/blade-1. Once UCSM has accepted the request, goUCS will monitor UCSM for successful service profile association. The ReAssociateSp command wrapper will monitor the service profile association process by whichever wait mode, either pull or push, is enabled in the command wrapper. goUCS will monitor the attribute “assocState” for a change in value matching “associated” from the returned XML output via enabled wait mode (either push or pull), or will timeout.

NOTE: It is not recommended that both pull and push wait modes are used simultaneously for synchronous execution of long running tasks.

15

XML Query (Pull) Variables Event Subscription (Push) Variables

Example Values Description

CLI_WAIT CLI_WAIT_EVENT Enable Enables either pull or push wait mode

disable Disables either pull or push wait mode

CLI_WAIT_MINUTES CLI_WAIT_EVENT_MINUTES 1-10 Timeout wait length defined in minutes (maximum value is 10)

CLI_WAIT_XMLWRAPPER No equivalent variable needed for push wait mode

dn XML wrapper that pull wait mode uses to query UCSM every minute for updated status. Any query based XML wrapper can be used

CLI_WAIT_ARGS No equivalent variable needed for push wait mode

%inUserArg1% false Arguments that are passed to the XML wrapper defined in pull wait mode that is used to query UCSM for updated status. User arguments (%inUserArgX%) passed to the command wrapper can be used. The %inUserArg1% variable in this case would be the Service Profile DN (i.e. org-root/ls-bob) provided as input to the executed command wrapper.

CLI_WAIT_ATTRIBUTE CLI_WAIT_EVENT_ATTRIBUTE assocState Attribute that will be monitored from the XML output of either the XML wrapper defined in pull wait mode or events pushed from UCS via event subscription which will be used as a status trigger. Any property from the returned XML output from either push or pull wait modes can be used.

CLI_WAIT_ATTRIBUTE_VALU

E

CLI_WAIT_EVENT_ATTRIBUTE_VALUE associated Attribute’s value that will be monitored from the XML output of either the XML wrapper defined in pull wait mode or events pushed from UCS via event subscription which will be used as the status trigger confirming successful completion of the task. Any valid value for the property monitored from the returned XML output from either push or pull wait modes can be used.

15

goUCS Special Commands Special Commands (page 1 of 4): • FILTERLOG

Filterlog is a goUCS command that aids in parsing the UCS Manager GUI java log. Every time a UCS Manager java GUI is opened, it creates a new java log file. The UCS Manager GUI logs the XML documents sent and received to the managed UCS Manager domain. To utilize the Filterlog command, the intention is to do an operation in the UCS Manager GUI, filter the java log file for the desired XML document, search and replace the desired parameters with variables, and create a parameterized goUCS cmd or XML wrapper from operation that was done in UCS Manager GUI. Since UCSM log files roll every 10MB, open a new UCSM GUI, perform the action you want to automate in the UCSM GUI, and then use Filterlog to extract the XML query from the logs. Be sure to use UCSPE to see the security methods, as a non-emulated UCSM GUI will filter them. • LOGTAIL – Actively parses most recent UCSM GUI java log file, watching for and displaying any UCS configuration change methods

being sent to UCS from UCSM GUI. • Example: goucs filterlog logtail

goucs filterlog [logfile] <replace> <search> <trig1> ... <trig10>

** NOTE: KNOWN LIMITATION ** If the plan is to modify an object in UCS Manager GUI and use the goUCS filterlog to get the actual XML API call, sometimes the GUI will include operational and state parameters in addition to the actual attributes that were changed. Since there is no way for goUCS to know the intention of the xml or command wrapper being created, manual edits of the results from the filter log may have to be performed to remove any unwanted additional attributes.

Logfile Parameter Filterlog automatically picks the most recent log file to filter from. This parameter provides the ability to specify an older file to filter from other than the latest log file. • Optional parameter • Option to show available log files

goucs filterlog showlog

NOTE: If log files aren’t shown with the showlog function, edit goucs.cmd and change CLI_LOG variable to point to the correct .ucsm directory path.

Logfile Override Example: goucs filterlog centrale_5276.log …

Replace Parameter Trigger to automatically replace and label the cookie with the variable $COOKIE$ and any user arguments with $ARGx$. • Adding “co” to either true or

false only shows configuration change XML methods.

• Adding “ro” to either true or false only shows query XML methods.

Replace Param. Input Options: • True(ro|co) - Replaces data with $ARGx$ labels.

• False(ro|co) – Does not replace data with $ARGx$ labels

Search Parameter Provides the search string of a series of characters to use as filter on the desired logfile Search Param. Input Options: • Ignore - Ignores search

option parameter • <text> - Any series of

characters used as search string to filter log file.

Trigger Parameters Provides the ability to search the output of the logfile for a certain series of characters and replace every found instance with a $ARGx$ label. Filterlog has the ability to search and replace up to 10 items.

Trigger Parameter Input Options: <text> Search for any match and replace with $ARGx$ #<text>:<tag> If a line contains <text> and <tag>, replace <tag> #<text>:* If a line contains <text>, replace everything in the line within double quotes

16

METHODS MONITORED: aaaLogin, aaaLogout, configConfMo(s), lsClone, lsInstantiateNTemplate

goUCS Special Commands Special Commands (page 2 of 4): • FILTERLOG (continued) – EXAMPLE

Objective: Create a XML Wrapper command for creating a VLAN in UCS, which takes accept two parameters, “VLAN name” and “VLAN ID.”

1. Open the UCSM GUI. For ease of filtering, make sure a new UCSM GUI session is being used. 2. Create a new VLAN with a unique name (like ”myvlan”) and a unique VLAN ID (like “1234”). 3. Close the UCSM GUI. 4. With goUCS run the following command: goucs filterlog trueco ignore myvlan #id:1234

5. The output of the goUCS command will look similar to the XML output below. Notice that the actual cookie has been replaced with $COOKIE$, each of the three instances of the VLAN name “myvlan” has been replaced with $ARG1$, and the single instance of VLAN ID has been replaced with $ARG2$. <configConfMos cookie="$COOKIE$” inHierarchical="true">

<inConfigs>

<pair key="fabric/lan/net-$ARG1$">

<fabricVlan defaultNet="no” dn="fabric/lan/net-$ARG1$” id="$ARG2$” name="$ARG1$” status="created">

</fabricVlan>

</pair>

</inConfigs>

</configConfMos>

6. The parameterized XML output can now be saved as an XML wrapper in the <GOUCS_PATH>\xmlwrappers folder. To add a new XML wrapper, create a new folder called “CreateVlan” in the xmlwrappers folder with the parameterized XML output saved with the same filename as the newly created folder.

Files created in this example: Folder: <GOUCS_PATH>\xmlwrappers\CreateVlan

Parameterized XML file: <GOUCS_PATH>\xmlwrappers\CreateVlan\CreateVlan.xml goUCS help file <GOUCS_PATH>\xmlwrappers\CreateVlan\CreateVlan.help

7. Once the wrapper has been successfully created, it can be called just like any of the pre-created XML wrappers. The example below will create a new VLAN with the name “TestVLAN” and VLAN ID “23” on the UCSM with the “default” session name.

goucs default createvlan realtime quiet TestVLAN 23

** NOTE: KNOWN LIMITATION ** If the plan is to modify an object in UCS Manager GUI and use the goUCS filterlog to get the actual XML API call, sometimes the GUI will include operational and state parameters in addition to the actual attributes that were changed. Since there is no way for goUCS to know the intention of the xml or command wrapper being created, manual edits of the results from the filter log may have to be performed to remove any unwanted additional attributes. 17

goUCS Special Commands Special Commands (page 3 of 4): • TRANSACTION

Provides the ability to execute multiple modification based XML wrapper commands whose XML output is batched and queued as a single XML document to be sent to the UCS system as a single transaction. An example use case for using transactions is creating 10 service profiles, associated the 10 created service profiles to 10 blades, and powering all 10 blades. In this example, if a user were to execute each service profile creation, association, and power on process as totally separate commands that would equate to 30 separate transactions UCSM would have to manage. It is much more efficient and practical for UCSM to receive this action as one transaction from a singular XML document. Transaction files can be saved and reused for common configuration actions like configuring LDAP, creating common VLANs, etc.

NOTE: Transactions in goUCS only works if both the UCS XML method each XML wrapper uses is configConfMos and the parameterized XML makes use of <pair> keys, which is normally true for all UCSM GUI XMLAPI calls.

Create and execute a Transaction 1. Start by creating a new transaction file. Transaction files are stored in

<GOUCS_PATH>\cache\Transaction directory.

goucs begin <transaction file>

2. Run as many XML wrappers as you want to be executed. Each XML wrapper command will only append the data between the <pair> keys in the parameterized XML file for the particular wrapper being executed.

goucs <xmlwrapper> transaction <file> <arg1 ... Arg10>

3. After you have executed the desired XML wrappers, end the transaction, which will finalize the transaction and close the transaction file.

goucs end <transaction file>

4. Execute the transaction on a UCS system.

goucs run <transaction file>

Listing Transaction Files Lists all currently available transaction files, regardless of if the transaction files have been finalized and closed or not. goucs listtransactions

Removing Transaction Files Deletes a transaction from the <GOUCS_PATH>\cache\Transaction directory

goucs rmtransaction <transaction file>

Transaction example: Create multiple VLANs as a single transaction. In this example the VLAN XML wrapper is createvlan, which takes two arguments (VLAN name and ID), and the transaction file is called vlan_setup. The transaction will create three VLANs (name=prod / id=1, name=qa / id=2,

name=dev / id=3).

1. Create the transaction file called vlan_setup: goucs begin vlan_setup

2. Add the three VLANs to the vlan_setup transaction file. goucs createvlan transaction vlan_setup prod 1

goucs createvlan transaction vlan_setup qa 2

goucs createvlan transaction vlan_setup dev 3

3. Finalize and close the vlan_setup transaction. goucs end vlan_setup

4. Execute the transaction on a UCS System: goucs [session] run vlan_setup

18

goUCS Special Commands Special Commands (page 4 of 4): • CONNECT

Enables the ability to directly launch a UCSM GUI from the goUCS command line.

1. Launch the UCSM GUI from a web browser as normal.

2. Copy the downloaded ucsm.jnlp file for the UCSM GUI, and paste it into the <GOUCS_PATH>\session folder.

3. Rename ucsm.jnlp to <SESSION_NAME>.jnlp, where <SESSION_NAME> is the same file name of matching session configuration file. In the example to the right, ucsm.jnlp has been renamed to DEFAULT.jnlp, which matches the DEFAULT session name.

4. To launch a UCSM GUI from goUCS, use the following command: goucs <SESSION_NAME> connect

1. Click “Launch” to trigger ucsm.jnlp download

3. Rename ucsm.jnlp to <SESSION_NAME>.jnlp

4. Command will launch “DEFAULT” session UCSM GUI

19

goUCS Debug / Troubleshooting Troubleshooting Error Message: Error in creating outputstream writer

Potential Root Causes: • The session configuration file is not formatted correctly • The session configuration file is not using a valid IP address • The desired UCS domain is not reachable Error Message: Error creating url

Potential Root Cause: • The session file is not formatted correctly Suggested Action: • Delete, and recreate the session configuration file

Error Message: Session not found

Potential Root Cause: • Cookie has expired and been expunged from the desired UCS

domain’s session list. • UCS Platform Emulator is being used, and your cookie is old. Suggested Action: Delete the cookie session file <session_name>.aut from the <GOUCS_PATH>/session folder.

How to setup Debug Logfiles • To enable logfiles, edit the

<GOUCS_PATH>\lib\clienv.cmd file, and modify the following line:

Change: To: set CLI_LOG=0 set CLI_LOG=1

NOTE: Any value other "1" will disable the logging • Two logfiles will be created for each command that is

performed in the following directory <GOUCS_PATH>/log/ • SENT - The sent log file contains the actual XML

document sent from the goUCS tool to the desired UCS domain

• RECEIVED - The received log file contains the XML document response sent from the desired UCS domain back to the goUCS tool.

• The naming convention for each type of logfile is: SENT - YYYYMMDD_HHmmssSSS_sent.log RECEIVED - YYYYMMDD_HHmmssSSS_received.log

I

20

Automation Example Utilizing goUCS Let’s now take what has been learned and put it to good use automating actions in UCS! In this example, the goUCS end user will run through the process of creating a VLAN in the UCSM GUI, actively monitoring the UCSM GUI java log file with goUCS’s logtail functionality, utilizing goUCS’s filterlog functionality to create a reusable XML wrapper derived from the UCSM GUI java log file, create a command wrapper utilizing the newly created VLAN creation XML wrapper, and utilize both wrappers by creating a reusable transaction that will be executed against multiple UCS systems. NOTE: This example assumes the end user has installed, configured, and verified goUCS to be functioning properly, as well as created and validated the appropriate goUCS session credential files to be working

properly. Any references to using logtail in Steps 2, 3, and 4 are optional.

Create a XML wrapper called CreateVlan.

1. Open a new Cisco UCS Manager GUI to a UCS System.

2. Once the UCSM GUI has been opened and logged into successfully, initialize goUCS’s UCSM java logfile “logtail” functionality, which will actively monitor for configuration change methods being sent from the UCSM GUI opened in Step 1 to UCSM.

X:\>goucs filterlog logtail

3. Go to the “LAN” tab in the UCSM GUI, and create a new VLAN called testing123 with VLAN ID 123. Once it has been successfully added to UCSM, the configuration change method should have been displayed in the output of goUCS logtail command.

4. Stop goUCS logtail from actively filtering the UCSM GUI. (The process can be exited by using CTRL-C).

5. Use goUCS filterlog to parse through the UCSM GUI java log file. By using the trueco replace parameter field, goUCS filterlog will only return and display configuration change methods. The testing123 parameter will search for every instance of testing123 and replace it with $ARG1$ in the returned XML output. The #id:* parameter will search for every instance of the id property type and replace the entire value (the value that will be replaced in this example is 123) with $ARG2$ in the returned XML output.

X:\>goucs filterlog trueco ignore testing123 #id:*

6. Create a CreateVlan folder in the goUCS XML wrapper folder. CreateVlan will be the XML wrapper name used for execution in goUCS.

X:\>mkdir X:\goucs\xmlwrappers\CreateVlan

7. Save the output of Step 5 as a parameterized XML file in the goUCS XML wrapper folder created in Step 6. Remember that the XML wrapper folder name and XML file must have the same name.

X:\>goucs filterlog trueco ignore testing123 #id:* > X:\goucs\xmlwrappers\CreateVlan\CreateVlan.xml

8. Create a HELP file in the goUCS XML wrapper folder created in Step 6 that details the usage for the CreateVlan XML wrapper. Remember that the XML wrapper folder name, XML file, and HELP file must have the same name. Verify the XML wrapper has now been added to the list of available XML wrappers listed in goUCS by executing goucs /? command. Here’s an example of what the HELP file should look like:

X:\>goucs CreateVlan /? CreateVlan is a command that creates a new VLAN.

Syntax:

goucs SessionName CommandName ExecType PrintType VlanName VlanId

<insert="XML_Wrapper"/>

VlanName Vlan Name

VlanID Vlan ID

Example:

goucs default createvlan realtime quiet testing123 123

21

Automation Example Utilizing goUCS goUCS AUTOMATION EXAMPLE CONTINUED (Page 2 of 3) 9. Test and verify the newly created CreateVlan XML wrapper works by executing the XML wrapper against a goUCS session. Verify the new VLAN was successfully created by

checking in the UCSM GUI. XML wrapper will be run against the DEFAULT session in this example.

X:\>goucs createvlan realtime indent TestVLAN 321

NOTE: It is recommended to test newly created XML and command wrappers be tested against the UCS Platform Emulator (UCSPE). UCSPE can be downloaded from Cisco Developer Network.

Next, create a goUCS command wrapper called CreateNewVlan that will use the CreateVlan XML wrapper created in Steps 7 and 8 of the previous section. 1. Create the CreateNewVlan directory in the goUCS command wrappers folder. X:\>mkdir X:\goucs\cmdwrappers\CreateNewVlan

2. Copy the contents of an existing command wrapper, ListBlades in this example, into CreateNewVlan directory created in step 1. Rename the CMD and HELP files to the same name as the CreateNewVlan directory.

X:\>copy X:\goucs\cmdwrappers\ListBlades\*.* X:\goucs\cmdwrappers\CreateNewVlan

X:\>move X:\goucs\cmdwrappers\CreateNewVlan\ListBlades.cmd X:\goucs\cmdwrappers\CreateNewVlan\CreateNewVlan.cmd

X:\>move X:\goucs\cmdwrappers\CreateNewVlan\ListBlades.help X:\goucs\cmdwrappers\CreateNewVlan\CreateNewVlan.help

3. Edit the CreateNewVlan.cmd and set the following variables with the appropriate values as listed below. Notice the XML wrapper variables are passing the CreateVlan XML wrapper’s variables, both pull and push wait modes are disabled, and two user arguments are being passed from the CreateNewVlan command wrapper to the CreateVlan XML wrapper. In this example, %inUserArg1% corresponds to the VLAN Name, and %inUserArg2% corresponds to the VLAN ID.

4. Edit the HELP file in the goUCS command wrapper folder renamed in Step 2 that details the usage for the CreateNewVlan command wrapper. Remember that the command wrapper folder name, CMD file, and HELP file must have the same name. Verify the command wrapper has now been added to the list of available command wrappers listed in goUCS by executing goucs /? command. Here’s an example of what the HELP file should look like:

X:\>goucs CreateNewVlan /? CreateNewVlan is a command that creates a new VLAN in a UCS system

Syntax:

goucs [SessionName] CreateNewVlan VlanName VlanID

SessionName Optional, defaults to "DEFAULT"

VlanName Vlan Name

VlanID Vlan ID

Example:

goucs default createvlan newvlan 40

5. Test and verify the newly created CreateNewVlan command wrapper works by executing the command wrapper against a goUCS session. Verify the new VLAN was successfully created by checking in the UCSM GUI. Command wrapper will be run against the DEFAULT session in this example.

X:\>goucs createnewvlan TestVLAN2 234

22

XML Wrapper Variables CLI_XML_WRAPPER=CreateVlan

minUserArgs=2

UserConfirmation=disable

CLI_PROCESS=realtime

CLI_OUTPUT=quiet

Query (Pull) Wait Mode Variables CLI_WAIT=disable

CLI_WAIT_MINUTES=

CLI_WAIT_XMLWRAPPER=

CLI_WAIT_ARGS=

CLI_WAIT_ATTRIBUTE=

CLI_WAIT_ATTRIBUTE_VALUE=

Event (Push) Wait Mode Variables CLI_WAIT_EVENT=disable

CLI_WAIT_EVENT_MINUTES=

CLI_WAIT_EVENT_DN=

CLI_WAIT_EVENT_ATTRIBUTE=

CLI_WAIT_EVENT_ATTRIBUTE_VALUE=

User Arguments UserArg1=%inUserArg1%

UserArg2=%inUserArg2%

UserArg3=

...

UserArg10=

Automation Example Utilizing goUCS goUCS AUTOMATION EXAMPLE CONTINUED (Page 3 of 3)

Next, create a goUCS transaction that will be used to create three VLANs in a single XML transaction to a UCS system.

1. Create a new goUCS transaction called Create3Vlans.

X:\>goucs begin Create3Vlans

2. Add the following three VLANs to the Create3Vlans goUCS transaction file created in step 1. Notice the CreateVlan XML wrapper is being used. NOTE: goUCS transactions require XML wrappers utilizing <pair> keys in the XML wrapper’s parameterized XML file only be used.

X:\>goucs createvlan transaction Create3Vlans prod 100

X:\>goucs createvlan transaction Create3Vlans qa 200

X:\>goucs createvlan transaction Create3Vlans test 300

3. Close the Create3Vlans goUCS transaction file started in step 1.

X:\>goucs end Create3Vlans

4. Test and verify the newly created Create3Vlans transaction works by executing the goUCS transaction against a goUCS session. Verify the three new VLANs were successfully created by checking in the UCSM GUI. Create3Vlans transaction will be run against the DEFAULT session in this example.

X:\>goucs run Create3Vlans

Next, run the Create3Vlans transaction against multiple UCS systems utilizing the ALL session flag.

1. Logout of all active goUCS sessions as a precautionary measure.

X:\>goucs ALL logout

2. Perform a goUCS session login command to the UCS systems that the Create3Vlans transaction will be executed against. Verify the goUCS session logins were successfully logged into by using the listcurrentsessions goUCS command.

NOTE: It is assumed that session files, session-one and session-two, have been pre-created

by the goUCS end user.

X:\>goucs session-one login X:\>goucs session-two login

X:\>goucs listcurrentsessions

The following Sessions are current:

session-one

session-two

3. Execute the Create3Vlans goUCS transaction against the sessions that were logged into in Step 5. Verify the three new VLANs were successfully created by checking in the UCSM GUIs for both goUCS sessions, session-one and session-two.

X:\>goucs ALL run Create3Vlans

Session: session-one

Session: session-two

23

Exporting goUCS XML and Command Wrappers

To export a goUCS XML or command wrapper, create a zip file that includes the XML or command wrapper folder and all recursive contents which are located in either the

<GOUCS_PATH>/xmlwrappers or <GOUCS_PATH>/cmdwrappers directories.

EXAMPLE: Create a zip file of the CreateVlan XML wrapper folder, including CreateVlan directory, and both the CreateVlan.xml and CreateVlan.help files.

Importing goUCS XML and Command Wrappers

To import a goUCS XML or command wrapper, unpack the zip file containing either a XML or command wrapper in the corresponding <GOUCS_PATH>/xmlwrappers or <GOUCS_PATH>/cmdwrappers directories depending on what wrapper type it is.

EXAMPLE: Unzip the CreateVlan XML Wrapper zip file that contains the CreateVlan directory, CreateVlan.xml file, and CreateVlan.help file from example above into the <GOUCS_PATH>/xmlwrappers folder.

Appendix – Cisco UCS XMLAPI Overview

The next section provides a high level overview of the Cisco UCS XMLAPI, its communication, and most used methods for querying and modifying the Cisco UCS XML database.

• For more detailed information about integrating with the Cicso UCS XMLAPI, please visit the Cisco Developer’s Network:

http://developer.cisco.com/web/cdc/tech/unifiedcomputing

24



Cisco UCS XML Interface Embedded apache webserver

Xml content sent in body of http post

Result contained within body of http response

URL: http://server-ip-address/nuova http://10.193.164.169/nuova Clients invoke methods to query and configure the server

Method categories: instance, class, generic

APACHE DME

S A M

MIT

AG1 AG2 AGn

Events HTTP {xml}

GUI uses the same API – look at logs in: C:\Documents and Settings\{user}\Application Data\Sun\Java\Deployment\log\.ucsm

http (port 80) and https (port 443)

25

http://server-ip-address/nuova





http://10.193.164.169/nuova

Long Lived Transactions

1) Client sends configuration request to server.

3) Applies config to MIT.

4) Changes persisted to DB (peer)

5) Response sent to client

7) DME attempts to apply stimuli. It may raise faults related to a configuration error.

8)FSM controls work-flow – requests to AGs

APACHE/XML API DME

S A M

AG1 AG2 AGn

Events

HTTP {xml}

10) AGs poll and receive update messages from endpoints. They propagate to DME. MIT reflects system state.

2) DME validates request.

6) Asynchronous change events sent to client

9) AGs send configuration changes to endpoints

DB

AGn

Polling/notification

bash> telnet 192.168.0.42 80 POST /nuova HTTP/1.1 User-Agent: lwp-request/2.06 Host: 1902.168.0.42 Content-Length: 132 Content-Type: application/x-www-form-urlencoded <configResolveClass

cookie=" 1206347805/4fa58144-c7f0-4990-b9f3-dc71a164aed7 " classId="equipmentChassis"/>

Message Body

HTTP Headers

Request Line

Hello World

27

Root

Everything is an object

Objects are hierarchically organized

Class identifies object type Card, Port, VNIC…

Class Inheritance Server port is a subclass of port. A server blade is a subclass of compute entity.

Set of attributes

identity states descriptions

references lifecycle MO

MIT contains comprehensive system information Discovered components System configuration Operational status including statistics and faults

MIT

Managed Object (MO)

28

Root Each object is uniquely identified by a Dn

Slash delimited sequence of Rns

Rns (Relative Names) are unique within the context they are defined. Example compute blade slot id.

Rn format is defined in naming rules

dn = {rn1}/{rn2}/{rn3}

Immutable

prefix naming properties

rn1

rn2

rn3

Examples: sys sys/switch-A/envstats sys/chassis-1/blade-5 org-root/ls-Webserver

topRoot dn is empty string

validation

Distinguished Names

29

Method Categories Authentication

MO

Root

DN {RN}*

DN Registry

Class Registry

Instance ID Registry

Object Navigation

DN (Name) Resolution

Class Resolution

Ancestor-Descendant Resolution

Sub-tree “Scope”

Child

Parent

Object Property Filters

Apply to DN or matching class

Single or multiple objects

Apply a hierarchical config

Object Configuration

Event Channel

Events

30

Authentication (Session Management) aaaLogin Login aaaRefresh Refresh Cookie aaaLogout Logout

Query configResolveDn Retrieve object by dn. configResolveDns Refresh object by set of dn’s. configResolveClass Retrieve all objects of a given class. configResolveChildren Retrieve children of an identified object. configScope Perform class query on identified subtree.

Event Subscription eventSubscribe Event subscription.

Configuration Change configConfMo Configure identified subtree (dn). configConfMos Configure identified subtrees (dn). configMoGroup Affects subtree’s corresponding to class.

UCS XML Methods

31

<aaaLogin

inName=“admin“

inPassword="abc123“

/>

Authentication Cookie based authentication

SSL (port 443)

aaaLogin

Refresh period 600 seconds

Cookie is attribute for all methods

32

Resolve DN Instance method (dn).

All attributes of objects returned.

Query a single objects state.

See method documentation.

Enumeration values, classIds, and bitmasks are stringified.

<configResolveDn cookie=“<cookie>" inHierarchical="false" dn="sys/chassis-1/blade-2"/>

33

Resolve DNs

<configResolveDns cookie=“<cookie>“ inHierarchical="false"> <inDns> <dn value="sys/chassis-1/blade-3"/> <dn value="sys/chassis-1/blade-1"/> <dn value="sys/chassis-1/blade-2"/> </inDns> </configResolveDns>

Generic method.

Results can be hierarchical.

Query multiple MO’s state.

Complex argument - DnSet

Efficiency reasons.

34

<configResolveClass cookie=“<cookie>" inHierarchical="false“ classId="computeBlade“ />

Generic method.


Get all instances of a class.

Optional filter.

Potentially expensive and large result set.

Resolve Class

35

<configResolveChildren cookie=“<cookie>" classId="adaptorHostEthIf“ inDn="sys/chassis-1/blade-2/adaptor-1“ inHierarchical="false“ />

Instance Method (dn)


Get all children of named object that are instances of named class.

Optional filter.

Resolve Children

36

<configScope cookie=“<cookie> " inClass=“computeBlade“ inHierarchical="false“ dn=“sys/chassis-1” </configScope>

Instance Method (dn)

Search subtree for instances of identified class.

Optional filter.

Can be very effective in reducing result sets to objects of interest.

Resolve Scope

37

Root

lsPower

XML

dn state = “down”

<configConfMo cookie=“<cookie>" dn="org-root/ls-dev1/power"> <inConfig> <lsPower dn="org-root/ls-dev1/power" state="down"/> </inConfig> </configConfMo>

Shut-down a server.

Target object is lsPower.

inConfig is a complex argument.

Modify state of an admin property.

Configuration Operations

38

Delete is done via configuration operation

Deletes are hierarchical

Set target object’s status property to “deleted”.

Class and Dn are required.

<configConfMo cookie=“<cookie>" dn="org-root/ls-WS "> <inConfig> <lsServer dn="org-root/ls-WS" status="deleted"/> </inConfig> </configConfMo>

XML

dn status= “deleted”

Root

Configuration Operations

39

<configConfMos cookie=“<cookie>"> <inConfigs> <pair key="org-root/ls-dev1/power"> <lsPower dn="org-root/ls-dev1/power" state="down"/> </pair> <pair key="org-root/ls-dev2/power"> <lsPower dn="org-root/ls-dev2/power" state="down"/> </pair> </inConfigs> </configConfMos>

Root

lsPower

lsPower

XML

dn state = “down”

Server is transactional.

inConfigs is a complex argument.

Use configConfMos

Configure Multiple Objects

40

goUCS-README-v1.0.x

Documents

equivalent

pull wait

service profile

pull wait

push wait

process type

email goucscisco

cisco developer