WS_API

There is a newer version of this page. You can find it here.

The Resources provided by the xCAT Web Service are documented below.

Introduction

xCAT provides a REST API (also called a web services API) that is currently implemented as a front end (translation layer) to xcatd. This provides programmatic access to xCAT from any language. This document describes how to set it up and use it.

The xCAT REST API is still under development. Post problems, suggestions, etc. to the xCAT mailing list.

Enable the https service for REST API

  • RHEL 6 (x86_64/ppc64) and RHEL 5 (x86_64)

    yum install mod_ssl
    service httpd restart

    If you plan on using the JSON output format, also:

    yum install perl-JSON

  • RHEL 5 (ppc64)

    Uninstall httpd.ppc64 and install httpd.ppc:

    rpm -e --nodeps httpd.ppc64
    rpm -i httpd.ppc mod_ssl.ppc

  • SLES 10 & 11 (x86_64/ppc64)

    a2enmod ssl
    a2enflag SSL
    /usr/bin/gensslcert
    cp /etc/apache2/vhosts.d/vhost-ssl.template /etc/apache2/vhosts.d/vhost-ssl.conf
    Insert line 'NameVirtualHost *:443' before the line '## SSL Virtual Host Context'
    /etc/init.d/apache2 restart

  • Ubuntu

    sudo a2enmod ssl
    sudo service apache2 restart

    verify it is loaded:

    sudo apache2ctl -t -D DUMP_MODULES | grep ssl

    If you plan on using the JSON output format, also:

    apt-get install libjson-perl

Set Up an Account for Web Service Access

The REST API calls need to provide a username and password. When this request is passed to xcatd, it will first verify that this user/pw is the xCAT passwd table, and then xcatd will look in the policy table to see if that user is allowed to do the requested operation.

You can use the root userid for your API calls, but we recommend you create a new userid (for example wsuser) for the APi calls and give it the specific privileges you want it to have: 

useradd wsuser
passwd wsuser     # set the password
tabch key=xcat passwd.username=wsuser passwd.password=<wsuser-pw>
mkdef -t policy 6 name=wsuser rule=allow

Note: in the tabch command above you can put the salted password (from /etc/shadow) in the xCAT passwd table instead of the clear text password, if you prefer.

Run a test request to see if everything is working: 

curl -X GET -k 'https://<xcat-mn-host>/xcatws/nodes?userName=wsuser&password=<wsuser-pw>'

You should see some HTML output that includes your list of nodes.

Overview of the xCAT REST API

The API lets you query, change, and manage the following resources: nodes, images, networks, site, tables, and VMs.

The format of the URL used in the API call is:

https://<xcat-mn-hostname>/xcatws/<resource>?userName=<user>&password=<pw>&format=<output-format>&<parameters>

where:

  • xcat-mn-hostname: the hostname or IP address of the xCAT management node
  • resource: one of the xCAT resources listed above
  • user: the userid that the operation should be run on behalf of. See the previous section on how to add a userid.
  • pw: the password of the userid (can be the salted version from /etc/shadow)
  • output-format: the output can be returned in html, json, or xml format. If not specified, the default is html.
  • parameters: additional parameters specific to this operation as documented in the rest of this document. Each parameter should be of the format 'attribute=value' and multiple parameters should separated by '&'.

Testing the API

Normally you will make REST API calls from your code. But you can test individual API calls from your browser or using the curl command.

To make an API call from your browser, use the desired URL from this document. For example: 

https://myserver/xcatws/nodes?userName=xxx&password=xxx&field=mac

Examples of making an API call using curl:

  • To query resources:

    curl -X GET -k 'https://xcatmnhost/xcatws/nodes?userName=xxx&password=xxx&format=json'

  • To change attributes of resources:

    curl -X PUT -k 'https://xcatmnhost/xcatws/nodes/{noderange}?userName=xxx&password=xxx&netboot=xnba'

  • To run an operation on a resource:

    curl -X POST -k 'https://xcatmnhost/xcatws/nodes/{noderange}?userName=xxx&password=xxx&groups=compute,all'

  • To delete a resource:

    curl -X DELETE -k 'https://xcatmnhost/xcatws/nodes/{noderange}?userName=xxx&password=xxx'

Node Resources

Use these API calls to query, change, and manage nodes.

List Nodes - GET /nodes

List all of the nodes in the xCAT db and optionally some of the attributes.

Parameters:

  • field - (optional) a node attribute whose value should be displayed for each node. You can specify this parameter multiple times to specify multiple attributes.

Returns:

Example:

curl -X GET -k 'https://myserver/xcatws/nodes?userName=xxx&password=xxx&field=mac&field=provmethod'

List Nodes in a Node Range - GET /nodes/<noderange>

List the nodes in a specified node range and optionally some of the attributes.

Parameters:

  • field - (optional) a node attribute whose value should be displayed for each node. You can specify this parameter multiple times to specify multiple attributes.

Examples:

  • Return all of the set attributes of each node in the node range:

    curl -X GET -k 'https://myserver/xcatws/nodes/n1-n7?userName=xxx&password=xxx'

  • Return specific attributes of each node in the node range:

    curl -X GET -k 'https://myserver/xcatws/nodes/n1-n7?userName=xxx&password=xxx&field=mac'

Change Node Attributes in a Node Range - PUT /nodes/<noderange>

Note: this call currently does not work.

Change attributes of the nodes in a specified node range and optionally some of the attributes.

Parameters:

Examples:

  • Set an attribute value of each node in the node range:

    curl -X PUT -k --data '["netboot=xnba"]' 'https://myserver/xcatws/nodes/n1-n7?userName=xxx&password=xxx'

Create Nodes - POST /nodes/<noderange>

Note: this call currently does not work.

Create nodes in a specified node range, optionally setting some of the attributes.

Parameters:

Examples:

  • Create nodes n1 through n7, setting the groups and netboot attributes in the process:

    curl -X POST -k --data '["groups=compute,all","netboot=xnba"]' 'https://myserver/xcatws/nodes/n1-n7?userName=xxx&password=xxx'

Delete Nodes - DELETE /nodes/<noderange>

Delete nodes in a specified node range.

Parameters: none

Examples:

  • Delete nodes n1 through n7:

    curl -X DELETE -k 'https://myserver/xcatws/nodes/n1-n7?userName=xxx&password=xxx'

Get the Power State of Nodes - GET /nodes/<noderange>/power

Query the power state of nodes in a specified node range.

Parameters: none

Examples:

  • Query the power state of nodes n1 through n7:

    curl -X GET -k 'https://myserver/xcatws/nodes/n1-n7/power?userName=xxx&password=xxx'

Change the Power State of Nodes - PUT /nodes/<noderange>/power

Note: this call currently does not work.

Change the power state of nodes in a specified node range.

Parameters:

  • Post Data - JSON array containing 1 element that is the string "on", "off", or "reset". For example:

    ["on"]

Examples:

  • Power on nodes n1 through n7:

    curl -X PUT --data '["on"]' -k 'https://myserver/xcatws/nodes/n1-n7/power?userName=xxx&password=xxx'

Get the Running Status of Nodes - GET /nodes/<noderange>/status

Query the running status (nodestat) of nodes in a specified node range.

Parameters: none

Examples:

  • Query the running status of nodes n1 through n7:

    curl -X GET -k 'https://myserver/xcatws/nodes/n1-n7/status?userName=xxx&password=xxx'

Get the Hardware Inventory of Nodes - GET /nodes/<noderange>/inventory

Query the hardware inventory (rinv) of nodes in a specified node range.

Parameters: none

Examples:

  • Query the hardware inventory of nodes n1 through n7:

    curl -X GET -k 'https://myserver/xcatws/nodes/n1-n7/inventory?userName=xxx&password=xxx'

Get the Hardware Vitals of Nodes - GET /nodes/<noderange>/vitals

Query the hardware vitals (rvitals) of nodes in a specified node range.

Parameters: none

Examples:

  • Query the hardware vitals of nodes n1 through n7:

    curl -X GET -k 'https://myserver/xcatws/nodes/n1-n7/vitals?userName=xxx&password=xxx'

Get the Energy Data of Nodes - GET /nodes/<noderange>/energy

Query the energy data (renergy) of nodes in a specified node range.

Parameters:

  • field - an attribute value to be queried. See the renergy command for the attributes that can be queried. You can specify this parameter multiple times to specify multiple attributes.

Examples:

  • Query the energy data of nodes n1 through n7:

    curl -X GET -k 'https://myserver/xcatws/nodes/n1-n7/energy?userName=xxx&password=xxx&field=cappingstatus&field=cappingvalue'

Change the Energy Settings of Nodes - PUT /nodes/<noderange>/energy

Change the energy settings (renergy) of nodes in a specified node range.

Parameters:

  • Post Data - JSON structure of attribute values to be set. See the renergy command for the attributes that can be set. For example:

    ["savingstatus=on"]

Examples:

  • Change the energy settings of nodes n1 through n7:

    curl -X PUT -k --data '["savingstatus=on"]' 'https://myserver/xcatws/nodes/n1-n7/energy?userName=xxx&password=xxx'

Change the Next-Boot State of Nodes - PUT /nodes/<noderange>/bootstate

Note: this call currently does not work.

Change the next-boot state (nodeset) of nodes in a specified node range.

Parameters:

  • Post Data - JSON structure containing the desired next-boot state. See the nodeset command for valid next-boot states. For example:

    ["osimage"]

Examples:

  • Change the next-boot state of nodes n1 through n7:

    curl -X PUT -k --data '["osimage"]' 'https://myserver/xcatws/nodes/n1-n7/bootstate?userName=xxx&password=xxx'

Change the Boot Order of Blade and PPC Nodes - PUT /nodes/<noderange>/bootseq

Note: this call currently does not work.

Persistently change the boot order (rbootseq) of BladeCenter blades or PPC LPARs in a specified node range.

Parameters:

  • Post Data - JSON structure containing the desired boot order. See the rbootseq command for valid boot order values. For example:

    ["net,hd0"]

Examples:

  • Change the boot order of nodes n1 through n7:

    curl -X PUT -k --data '["net,hd0"]' 'https://myserver/xcatws/nodes/n1-n7/bootseq?userName=xxx&password=xxx'

Change the Next Boot Order of IPMI-Controled Nodes - PUT /nodes/<noderange>/setboot

Note: this call currently does not work.

Temporarily change the boot order (rsetboot) of IPMI-controlled nodes (rack mounted and Flex x86_64 nodes) in a specified node range. This only changes the boot order for the next boot.

Parameters:

  • Post Data - JSON structure containing the desired boot order. See the rsetboot command for valid boot order values. For example:

    ["net"]

Examples:

  • Change the boot order (for the next boot) of nodes n1 through n7:

    curl -X PUT -k --data '["net"]' 'https://myserver/xcatws/nodes/n1-n7/setboot?userName=xxx&password=xxx'

  • PUT /nodes/{nodeRange}/dsh: Runs commands in parallel on nodes

  • PUT /nodes/{nodeRange}/dcp : Concurrently copies files to or from multiple nodes.

Image Resources

Network Resources

Site Resources

Table Access

Virtual Machine Resources

Web Service Status Codes

Here are the HTTP defined status codes that the Web Service can return:

  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 405 Method Not Allowed
  • 406 Not Acceptable
  • 408 Request Timeout
  • 417 Expectation Failed
  • 418 I'm a teapot
  • 503 Service Unavailable
  • 200 OK
  • 201 Created

References

MongoDB Logo MongoDB