3 steps to using the API#

1. Install CIMC FW using these [steps|http://www.cisco.com/en/US/docs/unified_computing/ucs/c/sw/gui/config/guide/1.1.1/Cisco_UCS_C-Series_Servers_Integrated_Management_Controller_Configuration_Guide_1_1_1_chapter12.html#task_94832943DCAA4854A4AA135D54FB2B50]
2. download and unzip [ client.zip|http://developer.cisco.com/web/unifiedcomputing/admin/-/document_library/view/3190018/179135?_20_redirect=http%3a%2f%2fdeveloper.cisco.com%2fweb%2funifiedcomputing%2fadmin%2f-%2fdocument_library%2fview%2f3190018 ]
3. access the API using curl (substitute your CIMC IP address)

curl https://10.193.196.2:8081/api --key client.key --cert client.crt -k

<?xml version="1.0" encoding="utf-8"?> <instance name="api" uri="/api"> <children> <child name="sensor" uri="/api/sensor"/> <child name="power-cap" uri="/api/power-cap"/> .... <child name="http" uri="/api/http"/> </children> </instance>}}}

IMPORTANT DO NOT expose the CIMC to a public network as anybody in possession of client.zip will be able to access the API.

Access API Using firefox (tested with version 4)#

install clientcert.pkcs into browser. (options->advanced->view certificates->import) Note: when importing the pkcs file firefox prompts for a password, there is none, hit enter.

We use X.509 Client certificates to identify legitimate users of the API. All API access is SSL encrypted. To allow you to get up to speed quickly the installed CIMC firmware already contains a matching server Certificate with the client.key & client.crt (downloaded as client.zip).

CIMC API cheatsheet#

working with bash formatted data

curl https://10.193.196.2:8081/api/users --key client.key --cert client.cert -k -H 'Accept: application/bash' > tmp

tmp -l list all available columnstmp -pn list all rows tmp -p 0 enabled request value for column 'enabled' for instance 0}}}api caveats -sel & syslog unsupported -SSL certificate upload (use CLI or UI to do this) Javascript upload to replace transform function curl https://10.193.196.2:8081/upload/transform.js -T yourtransform.js

CIMC Aggregation API Cheatsheet#

install ruby prerequisites (instructions for Ubuntu 10.04 'Lucid Lynx')

#INSTALL RUBY

apt-get install ruby1.9.1-full apt-get install rubygems1.9.1 gem install ip gem install sinatra }}} download and unzip [ client.zip|http://developer.cisco.com/web/unifiedcomputing/admin/-/document_library/view/3190018/179135?_20_redirect=http%3a%2f%2fdeveloper.cisco.com%2fweb%2funifiedcomputing%2fadmin%2f-%2fdocument_library%2fview%2f3190018 ] run cimc_aggr.rb as root

sudo ./cimc_aggr.rb

access the API like this

#find all CIMCS in 2 IP ranges
curl http://localhost/cimc --data "range=[[10.193.196.1, 10.193.196.10] , [1.1.1.1, 1.1.1.6]]" -X GET -v

#find all CIMCS  in IP range CIDR notation
curl http://localhost/cimc --data "cidr=10.193.196.0/24" -X GET

#set CIMC's discovered at 10.193.196.2 & 10.193.196.4 in previous commands with a description and turn locator led on
curl http://localhost/set --data-urlencode 'cimcs=[ 10.193.196.2 , 10.193.196.4 ]' --data-urlencode 'scope=/chassis' --data-urlencode 'props="description=finance server&locator-led=on"' -X POST

#power on example
curl http://localhost/set --data-urlencode 'cimcs=[ 10.193.196.2, 10.193.196.4 ]' --data-urlencode 'scope=/chassis/power' --data-urlencode 'props="on=on"' -X POST}}}


=Generating and Using your own X.509 certificates=
1.Generate a client CSR
{{{openssl req -new -newkey rsa:1024 -nodes -keyout client.key -out client.csr
echo nsCertType = client > openssl_client.conf}}}
2. Generate a server CSR using the CLI or UI and self sign according to these instructions.
http://www.cisco.com/en/US/docs/unified_computing/ucs/c/sw/cli/config/guide/131/Cisco_UCS_C-Series_CLI_Configuration_Guide_131_chapter10.html
{{{ echo nsCertType = server > openssl.conf
 openssl x509 -req -days 365 -in server.csr -CA ca.crt -set_serial 01 -CAkey ca.key -out server.crt -extfile openssl.conf
 cp server.crt host.cert
 cat ca.crt >> host.cert}}}
3. Install host.cert from step 2 to CIMC using CLI or UI. Your PEM certificate should have 2 begin-end blocks.
4. Finally sign your client certificate with the CA
{{{openssl x509 -req -days 365 -in client.csr -CA ca.crt -set_serial 01 -CAkey ca.key -out client.crt -extfile openssl_client.conf}}}
==Converting key & certs between different formats==
===to pkcs12 for browser===
{{{openssl pkcs12 -export -out clientcert.pkcs12 -in client.crt -inkey client.key}}}
===pkcs12 <-> pem===
{{{openssl pkcs12 -in clientcert.pkcs12 -out clientcert.pem
openssl pkcs12 -in clientcert.pkcs12  -nocerts -nodes -out clientcert.pem}}}
===pem <-> der===
{{{openssl x509 -in input.crt -inform PEM -out output.crt -outform DER
openssl rsa -in input.key -inform PEM -out output.key -outform DER}}}
===debugging SSL===
{{{openssl s_client -key ./client.key -cert ./client.crt -connect <cimc-ip>:8081}}}