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.

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'

Run Commands in Parallel on Nodes - PUT /nodes/<noderange>/dsh

Note: this call currently does not work.

Run an specified command in parallel on a specified node range.

Parameters:

  • devicetype = device type value : Specify a user-defined device type that references the location of relevant device configuration file.
  • execute = filename : Indicates that command_list specifies a local script filename and arguments to be executed on the remote targets.
  • environment = filename : Specifies that the environment file contains environment variable definitions to export to the target before executing the command list.
  • fanout = value : Specifies a fanout value for the maximum number of concurrently executing remote shell processes.
  • userid = id value : Specifies a remote user name to use for remote command execution.
  • options = node options : Specifies options to pass to the remote shell command for node targets.
  • remoteshell = node remote shell path : Specifies the path of the remote shell command used for remote command execution on node targets.
  • syntax = csh|ksh : Specifies the shell syntax to be used on the remote target.
  • timeout = timeout value : Specifies the time, in seconds, to wait for output from any currently executing remote targets.
  • envlist = env list :Ignore xdsh environment variables. This option can take an argument which is a comma separated list of environment variable names that should NOT be ignored.
  • sshsetup : Set up the SSH keys for the user running the command to the specified node list.
  • rootimg = install img : For Linux, Specifies the path to the install image on the local node. For AIX, specifies the name of the osimage on the local node.
  • command = cmd_list : command[; command]... where command is the command to run on the remote target. Quotation marks are required to ensure that all commands in the list are executed remotely, and that any special characters are interpreted correctly on the remote target.
  • nolocale : Specifies to not export the locale definitions of the local host to the remote targets.
  • monitor : Monitors remote shell execution by displaying status messages during execution on each target.
  • showconfig : Displays the current environment settings for all DSH Utilities commands.
  • silent : Specifies silent mode.

  • Post Data - JSON structure containing the command to run on the nodes. For example:

    ["command=date"]

For more parameter information, refer to the xdsh man page.

Examples:

  • Run the date command on nodes n1 through n7:

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

Copy Files in Parallel to Nodes - PUT /nodes/<noderange>/dcp

Note: this call currently does not work.

Copy files in parallel to a specified node range.

Parameters:

  • fanout = fanout value : Specifies a fanout value for the maximum number of concurrently executing remote shell processes.
  • rootimg = img path : Specifies the path to the install image on the local Linux node.
  • options = node options : Specifies options to pass to the remote shell command for node targets. The options must be specified within double quotation marks ("") to distinguish them from xdsh options.
  • rsyncfile = sync configure file : Specifies the path to the file that will be used to build the rsync command.
  • remotecopy = command path : Specifies the full path of the remote copy command used for remote command execution on node targets.
  • timeout = timeout value : Specifies the time, in seconds, to wait for output from any currently executing remote targets.
  • source = source file path
  • target = target file path

Flags:

  • preserve : Preserves the source file characteristics as implemented by the configured remote copy command.
  • pull : Pulls (copies) the files from the targets and places them in the target_path directory on the local host.
  • showconfig : Displays the current environment settings for all DSH Utilities commands.
  • recursive: Recursively copies files from a local directory to the remote targets

  • Post Data - JSON structure containing the command to run on the nodes. For example:

    ["remotecopy =/usr/bin/rsync", "options=\"-t\"", "source=/localnode/smallfile /tmp/bigfile", "target=/tmp"]

For more parameter information, refer to the xdcp man page.

Examples:

Image Resources

Use these API calls to list, change, and manage OS images.

List OS Images - GET /images

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

Parameters:

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

Returns:

  • JSON: structure containg the osimage name and any attributes that were requested.

Example:

  • List the osimages in the db:

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

  • Display the osvers attribute for all of the osimages in the db:

    curl -X GET -k 'https://myserver/xcatws/images?userName=xxx&password=xxx&field=osvers'

List Attributes of OS Images - GET /images/<imagename>

List some or all of the attributes of an osimage in the xCAT db.

Parameters:

  • field - (optional) a osimage attribute whose value should be displayed for this osimage. You can specify this parameter multiple times to specify multiple attributes. If this parameter is not specified, all of the attributes of this osimage (that have a value) will be displayed.

Returns:

  • JSON: structure containg the osimage name and any attributes that were requested.

Example:

  • List all of the attributes of my osimages:

    curl -X GET -k 'https://myserver/xcatws/images/my-netboot-image?userName=xxx&password=xxx'

  • Display the osvers attribute for all of the osimages in the db:

    curl -X GET -k 'https://myserver/xcatws/images/my-netboot-image?userName=xxx&password=xxx&field=osvers'

Capture an OS Image From a Running Node - POST /images/capture

Note: this call currently does not work.

Captures an image from a Linux diskful node and create a diskless or diskful image on the management node. See the imgcapture command man page for details.

Parameters:

  • nodename : (required) specify the node to capture the image from.
  • profile = profilename : Assign profile as the profile of the image to be created.
  • osimage = imgname : Assign the predefined osimage object. The attributes of osimage will be used to capture and prepare the root image.
  • bootinterface = interface name : The network interface the diskless node will boot over.
  • netdriver = driver name : The driver modules needed for the network interface, which is used by the generage image API to generate initial ramdisks.

Example:

Delete the OS Image Files from the MN - DELETE /images/<imagename>

Delete the files in the rootimg directory on the xCAT management node associated with this osimage. See the rmimage command man page for details. This call will not remove the osimage definition in the xCAT DB.

Parameters: none

Example:

  • Remove the files in the rootimg directory that my-netboot-image points to:

    curl -X DELETE -k 'https://myserver/xcatws/images/my-netboot-image?userName=xxx&password=xxx'

Network Resources

Use these API calls to list, create, change, and delete networks objects in the xCAT DB.

List All Networks - GET /networks

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

Parameters:

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

Returns:

  • JSON: structure containing each network name and any attributes that were requested.

Example:

  • List all of the networks defined in the db:

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

  • Display the gateway and tftpserver attributes for all of the networks in the db:

    curl -X GET -k 'https://myserver/xcatws/networks?userName=xxx&password=xxx&field=gateway&field=tftpserver'

List Attribues of a Network - GET /networks/<networkname>

List some or all of the attributes of a network defined in the xCAT db.

Parameters:

  • field - (optional) a network attribute whose value should be displayed for each network. You can specify this parameter multiple times to specify multiple attributes. If this parameter is not specified, all of the attributes of this osimage (that have a value) will be displayed.

Returns:

  • JSON: structure containing each network name and any attributes that were requested.

Example:

  • List all of the attributes of the specified network:

    curl -X GET -k 'https://myserver/xcatws/networks/mynet?userName=xxx&password=xxx'

  • Display the gateway and tftpserver attributes for the specified network:

    curl -X GET -k 'https://myserver/xcatws/networks/mynet?userName=xxx&password=xxx&field=gateway&field=tftpserver'

Change Attribues of a Network Definition - PUT /networks/<networkname>

Note: this call currently does not work.'

Change attributes of a network defined in the xCAT db.

Parameters:

Example:

  • Change the gateway attribute of the specified network:

    curl -X GET -k --data '["gateway=10.0.0.250"]' 'https://myserver/xcatws/networks/mynet?userName=xxx&password=xxx'

Create a New Network Definition - POST /networks/<networkname>

Note: this call currently does not work.'

Create a new network definition in the xCAT db.

Parameters:

Example:

Delete a Network Definition - DELETE /networks/<networkname>

Delete a network definition from the xCAT db.

Parameters: none

Example:

  • Delete the network definition called mynet:

    curl -X DELETE -k 'https://myserver/xcatws/networks/mynet?userName=xxx&password=xxx'

Site Resources

Use these API calls to list, create, change, and delete networks objects in the xCAT DB.

List the Site Attributes - GET /site

List all of the site attributes defined in the xCAT db. For a description of each site attribute, see site attributes.

Parameters: none

Returns:

  • JSON: structure containing the site attributes.

Example:

  • List all of the site attributes defined in the db:

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

Change Site Attributes - PUT /site

Note: this call currently does not work.

Change the specified site attributes in the xCAT db. For a description of each site attribute, see site attributes.

Parameters:

Example:

Table Access

Use these API calls to list the tables in the xCAT DB, and to list the contents of any table.

List the DB Tables - GET /tables

List the names of all of the tables in the xCAT db. For a description of each table, see xCAT DB.

Parameters: none

Returns:

  • JSON: structure containing the table names.

Example:

  • List the names of all of the tables in the db:

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

List Rows or Attributes in a DB Table - GET /tables/<tablename>

List the rows or attributes of the specified table in the xCAT db. For a description of each table, see xCAT DB.

Parameters:

  • col=column-name: (optional) The column name for the select condition. This parameter should used with parameters value and attribute.
  • value=value : (optional) the value for the select condition. Will only display the 1st row satisfying this criteria. This parameter should used with parameters col and attribute.
  • attribute=attr-name : (optional) the attribute to display for the selected row. This parameter can be repeated multiple times. This parameter should used with parameter col and value.

Example:

  • List the rows of the nodehm table:

    curl -X GET -k 'https://myserver/xcatws/tables/nodehm?userName=xxx&password=xxx'

  • List the mgt attribute for the row of the nodehm table whose node is blade01:

    curl -X GET -k 'https://myserver/xcatws/tables/nodehm?userName=xxx&password=xxx&col=node&value=blade01&attribute=mgt'

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