Table of Contents

1 Introduction

1.1 Moab® Web Services Overview

MWS communicates with the Moab Workload Manager (MWM) server using the same wire protocol as the Moab command-line interface. By publishing a standard interface into Moab's intelligence, MWS significantly reduces the amount of work required to integrate MWM into your solution.

This documentation is intended for developers performing such integrations. If you are a Moab administrator, and for conceptual information about MWM, see the Moab Administrator's Guide.

1.2 Upgrading from Previous Versions

It is highly recommended to perform a full database backup before performing database updates. This may be done using the mongodump utility documented in the MongoDB documentation.

1) Stop Tomcat, re-deploy mws.war, remove exploded mws directory, and start Tomcat.

# CentOS 6 example
service tomcat6 stop
cp /tmp/mws-install/mws-<VERSION>/mws.war /var/lib/tomcat6/webapps
rm -rf /var/lib/tomcat6/webapps/mws
service tomcat6 start

2) Visit http://localhost:8080/mws/ in a web browser to verify that MWS is running again.

3) Log into MWS to verify configuration and check for required database updates.

If you encounter problems, or if MWS does not seem to be running, see the steps in the Troubleshooting section.

4) Perform database updates.

If database updates are required, a warning box will be shown at the top of the MWS home page. Click "Please upgrade now" to continue.

A dialog will appear confirming if the upgrade should be applied or not.

When the upgrade is completed, a confirmation notice will be displayed. MWS is then ready for normal usage.

1.3 Installation Guide

1.3.1 Requirements

Hardware Requirements

• Dual-core Intel/AMD x86-64 processor
• At least 4 GB of RAM

Software Requirements

• Moab® Workload Manager (version must match exactly the version of MWS)
• Oracle® Java® 6 Runtime Environment
• Apache Tomcat™ 6
• MongoDB® 2.0.2 - 2.0.8

Oracle Java 6 Runtime Environment is the only supported Java environment.

All other versions of Java, including Oracle Java 7, OpenJDK/IcedTea, GNU Compiler for Java, and so on, are not supported.

Microsoft Active Directory or OpenLDAP (must support the LDAPv3 protocol) is required if you want the Principal resource functionality in Moab Web Services, or if you are going to install Moab Viewpoint. For a basic tutorial on how to set up OpenLDAP, see Setting up OpenLDAP on Centos 6 in the Viewpoint Management and User Guide.

1.3.2 Quickstart Guide

1) Install MongoDB version 2.0.8.

MWS does not yet support MongoDB 2.2 or later. Be sure to install the 2.0.8 packages. The RPM package names are mongo20-10gen-2.0.8-mongodb_1.x86_64.rpm and mongo20-10gen-server-2.0.8-mongodb_1.x86_64.rpm.

• Install MongoDB on RedHat Enterprise, CentOS, or Fedora Linux
• Install MongoDB on Debian or Ubuntu Linux

2) Start MongoDB.

# CentOS 6 example
chkconfig mongod on
service mongod start

The instructions provided above for installing MongoDB describe a base installation only. See the MongoDB section of the security page.

3) Install and configure Moab Workload Manager (MWM).

• You must deploy Moab Web Services (MWS) on the same server as Moab Workload Manager (MWM).
• The version of MWS must match exactly the version of MWM. For example, MWS 7.1.1 works only with MWM 7.1.1.

4) Generate a secret key to be used for communication between MWM and MWS.

# All these steps are required. Do not skip any steps.
service moab stop
dd if=/dev/urandom count=18 bs=1 2>/dev/null | base64 > /opt/moab/etc/.moab.key
chown root:root /opt/moab/etc/.moab.key
chmod 400 /opt/moab/etc/.moab.key
service moab start

5) Install Apache Tomcat 6.

# CentOS 6 example
yum install tomcat6

6) Install the 64-bit RPM version of the Oracle Java SE 6 JRE.

Oracle Java 6 Runtime Environment is the only supported Java environment.

All other versions of Java, including Oracle Java 7, OpenJDK/IcedTea, GNU Compiler for Java, and so on, are not supported.

# CentOS 6 example
sh jre-6u45-linux-x64-rpm.bin

7) Create the MWS home directory and its subdirectories etc, hooks, plugins, and log.

The default location for the MWS home directory is /opt/mws. These instructions assume the default location.

• Give the Tomcat user read access to these directories and write access to the plugins and log directories.
• Here is a sample script for these steps:

mkdir -p /opt/mws/etc /opt/mws/hooks /opt/mws/plugins /opt/mws/log
chown -R tomcat:tomcat /opt/mws # Depending on your OS, the Tomcat username might be tomcat6.
chmod -R 555 /opt/mws
chmod u+w /opt/mws/plugins /opt/mws/log

8) Extract the contents of the MWS tarball into a temporary directory.

mkdir /tmp/mws-install
cd /tmp/mws-install
tar xvzf $HOME/Downloads/mws-<VERSION>.tar.gz
cd /tmp/mws-install/mws-<VERSION>

9) Set up the MWS configuration file.

• In the extracted MWS directory are two sample configuration files: mws-config-cloud.groovy and mws-config-hpc.groovy.
• mws-config-cloud.groovy provides sample configuration for the Moab Cloud Suite.
• mws-config-hpc.groovy provides sample configuration for the Moab HPC Suites.
• Choose the correct file for your suite, rename it to mws-config.groovy, and copy it to /opt/mws/etc.
• Give the Tomcat user read access to /opt/mws/etc/mws-config.groovy.
• In the /opt/mws/etc/mws-config.groovy file, change these settings:
• moab.secretKey: needs to match the MWM secret key you generated earlier (contained in /opt/moab/etc/.moab.key)
• auth.defaultUser.username: any value you like, or leave as is
• auth.defaultUser.password: any value you like, but choose a good password

vi /opt/mws/etc/mws-config.groovy
…
moab.secretKey = "<ENTER-KEY-HERE>"
moab.server = "localhost"
moab.port = 42559
// Change these to be whatever you like.
auth.defaultUser.username = "admin"
auth.defaultUser.password = "adminpw"

If you do not change auth.defaultUser.password, then your MWS is not secure, since anyone reading these instructions can log into your MWS. Here are some tips for choosing a good password.

10) Add the following lines to the end of /etc/tomcat6/tomcat6.conf:

CATALINA_OPTS="-DMWS_HOME=/opt/mws -Xms256m -Xmx3g -XX:MaxPermSize=384m"
JAVA_HOME="/usr/java/latest"

Some Linux distributions use /etc/default/tomcat6 or /etc/sysconfig/tomcat6 instead of /etc/tomcat6/tomcat6.conf.

11) Start Tomcat and deploy mws.war.

# CentOS 6 example
chkconfig tomcat6 on
service tomcat6 stop
cp /tmp/mws-install/mws-<VERSION>/mws.war /var/lib/tomcat6/webapps
service tomcat6 start

12) Visit http://localhost:8080/mws/ in a web browser to verify that MWS is running.

13) Log into MWS to verify that the MWS credentials are working.

If you encounter problems, or if MWS does not seem to be running, see the steps below in the Troubleshooting section.

1.4 Troubleshooting

1. The MWS log file. By default this is /opt/mws/log/mws.log.
2. The Tomcat catalina.out file, usually in /var/log/tomcat6 or $CATALINA_HOME/logs.

If you remove the log4j configuration from mws-config.groovy, MWS will write its log files to java.io.tmpdir. For Tomcat, java.io.tmpdir is generally set to $CATALINA_BASE/temp or CATALINA_TMPDIR.

Here is a list of some errors and their fixes:

MongoDB: Errors during MWS startup

If the application fails to start and gives error messages such as these:

Error creating bean with name 'mongoDatastore'
can't say something; nested exception is com.mongodb.MongoException

MongoDB: Out of semaphores to get db connection

To resolve this error, adjust the values of connectionsPerHost or threadsAllowedToBlockForConnectionMultiplier by adding them to mws-config.groovy. Example:

grails.mongo.options.connectionsPerHost = 60
grails.mongo.options.threadsAllowedToBlockForConnectionMultiplier = 10

For more information on these options, refer to these documents:

• The Configuration page under Moab Web Services in the Quick Reference menu, which briefly discusses a few MongoDB driver options.
• The MongoOptions documentation, which contains full details on all MongoDB driver options.

• You must restart Tomcat after adding, removing, or changing grails.mongo.options parameters.
• As shipped, mws-config.groovy does not contain any grails.mongo.options parameters. To adjust their values, you need to add them to mws-config.groovy.
• The default value of connectionsPerHost is normally 10, but MWS sets it internally to 50.
• The default value of threadsAllowedToBlockForConnectionMultiplier is 5.
• Any of the options listed in MongoOptions can be specified in mws-config.groovy. Just use the prefix grails.mongo.options as shown above.

MongoDB: Connection wait timeout after 120000 ms

See the section "MongoDB: Out of semaphores to get db connection" above.

java.lang.OutOfMemoryError: Java heap space

Increase the size of the heap using JVM options -Xms and -Xmx. Here are the suggested values from the Quickstart Guide:

CATALINA_OPTS="-DMWS_HOME=/opt/mws -Xms256m -Xmx3g -XX:MaxPermSize=384m"

• -Xms: Set initial Java heap size.
• -Xmx: Set maximum Java heap size.

java.lang.OutOfMemoryError: PermGen space

Increase the size of the permanent generation using JVM option -XX:MaxPermSize. Here are the suggested values from the Quickstart Guide:

CATALINA_OPTS="-DMWS_HOME=/opt/mws -Xms256m -Xmx3g -XX:MaxPermSize=384m"

SEVERE: Context [/mws] startup failed due to previous errors

If catalina.out contains this error, look in /opt/mws/log/mws.log and /opt/mws/log/stacktrace.log for more details on the error.

Moab Reached Maximum Number of Concurrent Client Connections

When this error message is encountered, simply add a new line to the moab.cfg file:

CLIENTMAXCONNECTIONS 256

This will change the Moab configuration when Moab is restarted. Run the following command to immediately use the new setting:

changeparam CLIENTMAXCONNECTIONS 256

The number 256 above may be substituted for the desired maximum number of MWM client connections.

1.5 Configuration

To see a full reference to all configuration and logging parameters available in MWS, see the Configuration page under Moab Web Services in the Quick Reference menu.

Home Directory

The MWS home directory contains configuration files, log files, and files that serve features of MWS such as hooks and plugins. You should set the location of the MWS home directory using the MWS_HOME property as shown in the Quickstart Guide. If you do not set MWS_HOME as a Java property or as an environment variable, then MWS will use /opt/mws as the default MWS_HOME.

Configuration Files

The primary configuration file is MWS_HOME/etc/mws-config.groovy. If this file is missing or contains errors, MWS will not start. If MWS_HOME/etc/log4j.properties exists, MWS will load it as well.

Logging Configuration Using mws-config.groovy

Shown below is an example that logs all error messages and fatal messages to /opt/mws/log/mws.log. It also logs all stack traces to /opt/mws/log/stacktrace.log. Note that this example is not configured to log events.

log4j = {
	appenders {
		rollingFile name: 'stacktrace',
			file: '/opt/mws/log/stacktrace.log',
			maxFileSize: '1GB'
		rollingFile name: 'rootLog',
			file: '/opt/mws/log/mws.log',
			threshold: org.apache.log4j.Level.ERROR,
			maxFileSize: '1GB'
	}
	root {
		debug 'rootLog'
	}
}

Alternatively, you may configure a console appender instead of a rolling file as shown below.

log4j = {
	appenders {
		rollingFile name: 'stacktrace',
			file: '/opt/mws/log/stacktrace.log',
			maxFileSize: '1GB'
		console name: 'consoleLog',
			threshold: org.apache.log4j.Level.ERROR
	}
	root {
		debug 'consoleLog'
	}
}

• You may configure logging using either MWS_HOME/etc/mws-config.groovy or MWS_HOME/etc/log4j.properties.
• If you do not define any log4j configuration, MWS will write its log files to java.io.tmpdir. For Tomcat, java.io.tmpdir is generally set to $CATALINA_BASE/temp or CATALINA_TMPDIR.

LDAP Configuration Using mws-config.groovy

Using a Supported LDAP Directory Type

To configure an MWS connection to an LDAP server, add the following parameters to mws-config.groovy:

Throughout the following examples in this topic, you will see dc=acme,dc=com. "acme" is only used as an example to illustrate what you would use as your own domain controller if your domain name was "acme.com." You should replace any references to "acme" with your own organization's domain name.

• ldap.server: The hostname or IP address of the LDAP server.
• ldap.port: The port the LDAP server is listening on.
• ldap.baseDNs: A list of distinguished names that are the root entries for LDAP searches.
• ldap.bindUser: The distinguished name of the bind user.
• ldap.password: The password of the ldap.bindUser.
• ldap.directory.type: The type of LDAP directory (e.g. "Microsoft Active Directory").

The ldap.directory.type parameter can have the following values:

• Microsoft Active Directory
• OpenLDAP Using InetOrgPerson Schema
• OpenLDAP Using NIS Schema
• OpenLDAP Using Samba Schema

Here is a sample configuration for OpenLDAP.

If you followed the Adaptive Computing tutorial "Setting up OpenLDAP on CentOS 6" your ldap.directory.type should be set to "OpenLDAP Using InetOrgPerson Schema".

ldap.server  = "192.168.0.5"
ldap.port = 389
ldap.baseDNs = ["dc=acme,dc=com"]
ldap.bindUser = "cn=Manager,dc=acme,dc=com"
ldap.password = "*****"
ldap.directory.type = "OpenLDAP Using InetOrgPerson Schema"

Here is a sample configuration for Microsoft Active Directory.

ldap.server  = "192.168.0.5"
ldap.port = 389
ldap.baseDNs = ["CN=Users,DC=acme,DC=com","OU=Europe,DC=acme,DC=com"]
ldap.bindUser = "cn=Administrator,cn=Users,DC=acme,DC=com"
ldap.password = "*****"
ldap.directory.type = "Microsoft Active Directory"

To see how to configure a secure connection to the LDAP server, see Connection to LDAP in the Security section.

Using an Unsupported LDAP Directory Type

If you are not using one of the supported directory types, you can explicitly configure MWS to work with your LDAP schema by using the following parameters:

• ldap.user.objectClass: The name of the class used for the LDAP user object. Example:
• user
• person
• inetOrgPerson
• posixAccount
• ldap.group.objectClass: The name of the class used for the LDAP group object. Example:
• group
• groupOfNames
• posixGroup
• ldap.ou.objectClass: The name of the class used for the LDAP organizational unit object. Example:
• organizationalUnit
• ldap.user.membership.attribute: The attribute field in a user entry to use when loading the user's groups (optional if ldap.group.membership.attribute is defined). Example:
• memberOf
• ldap.group.membership.attribute: The attribute field in a group entry to use when loading the group's members (optional if ldap.user.membership.attribute is defined). Example:
• member
• memberUid
• ldap.user.name.attribute: The attribute field to use when loading the username. This field must uniquely identify a user. Example:
• sAMAccountName
• uid

For example:

ldap.server  = "myldaphostname"
ldap.port = 389
ldap.baseDNs = ["CN=Users,DC=acme,DC=com","OU=Europe,DC=acme,DC=com"]
ldap.bindUser = "cn=Administrator,cn=Users,DC=acme,DC=com"
ldap.password = "*****"
ldap.user.objectClass = "person"
ldap.group.objectClass = "group"
ldap.ou.objectClass = "organizationalUnit"
ldap.user.membership.attribute = "memberof"
ldap.group.membership.attribute = "member"
ldap.user.name.attribute = "sAMAccountName"

Here is a similar example for OpenLDAP. Note there is no user membership attribute in the OpenLDAP InetOrgPerson schema and thus ldap.user.membership.attribute is set to null. This is allowable because the ldap.group.membership.attribute is set.

ldap.server  = "myldaphostname"
ldap.port = 389
ldap.baseDNs = ["dc=acme,dc=com"]
ldap.bindUser = "cn=Manager,dc=acme,dc=com"
ldap.password = "*****"
ldap.user.objectClass = "inetOrgPerson"
ldap.group.objectClass = "groupOfNames"
ldap.ou.objectClass = "organizationalUnit"
ldap.user.membership.attribute = null
ldap.group.membership.attribute = "memberUid"
ldap.user.name.attribute = "uid"

Overriding Attributes in a Supported LDAP Directory Type

You can also override attributes in supported directory types. For example, say you are using OpenLDAP with an NIS Schema. The group objectClass for NIS defaults to "groupOfNames," but you want to use "groupOfUniqueNames" instead while retaining all other defaults for NIS. You can do this by setting ldap.directory.type to "OpenLDAP Using NIS Schema" and overriding the ldap.group.objectClass attribute as follows:

ldap.directory.type = "OpenLDAP Using NIS Schema"
ldap.group.objectClass = "groupOfUniqueNames"

• LDAP is not currently used to authenticate users to MWS. LDAP is only used to map principals to roles, as explained in Principals.
• The user class in your LDAP schema must have an attribute that uniquely identifies a user (e.g. uid, sAMAccountName).

1.6 Security

1. The connection between MWS and Moab Workload Manager (MWM)
2. The connection between MWS and MongoDB
3. The connections between clients and MWS

Connection with MWM

MWS communicates with MWM via the Moab Wire Protocol, which uses a direct connection between the two applications. The communication over this connection uses a shared secret key, which is discussed in the Quickstart Guide. However, the communication is not encrypted and is therefore susceptible to eavesdropping and replay attacks. For this reason, MWS is supported only when running on the same machine as MWM. This assures that any connections between the two applications occur internally on the server and are not exposed to external users.

Connection with MongoDB

By default, the connection between MWS and MongoDB is not authenticated. To enable authentication, follow the instructions below. For further reading, see the MongoDB tutorial Control Access to MongoDB Instances with Authentication.

• Add an administrative user to the admin database.
• Add an MWS user to the mws database.
• To support MWS API version 2, add an MWS user with read-only rights to the moab database.
• Here is an example of how to create all the required users. The users in the moab database are required only for MWS API version 2.

[root]# service mongod start
[root]# mongo
> use admin;
> db.addUser("admin_user", "secret1");
> use moab;
> db.addUser("moab_user", "secret2");
> db.addUser("mws_user", "secret3", true);
> use mws;
> db.addUser("mws_user", "secret3");
> exit;

• Add the MWS user credentials (the ones you just created) to the mws-config.groovy file. Example:

grails.mongo.username = "mws_user"
grails.mongo.password = "secret3"

• Enable authentication in the MongoDB configuration file.
• The file is called /etc/mongodb.conf on many Linux distributions.
• In that file, look for #auth = true and uncomment it.
• Restart MongoDB.
• Restart Tomcat.

The passwords used here (secret1, secret2, and secret3) are examples. Choose your own passwords for these users.

If authentication is enabled in MongoDB, but the MWS user was not properly created or configured, MWS will not start. See the log file(s) for additional information in this case.

Client Connections to MWS

All connections to MWS, except those requesting the documentation or the main page, must be authenticated properly. MWS uses a single-trusted-user authentication model, meaning a single user exists that has access to all aspects of MWS. The username and password for this user are configured with the auth.defaultUser properties in the configuration file. See the Configuration reference guide for more information.

When using the MWS user interface in a browser, the user will be prompted for username and password. For information on how to authenticate requests when not using a browser, see the Authentication section in the user guide.

The username and password in the Basic Authentication header are encoded but not encrypted. Therefore, it is strongly recommended that MWS be run behind a proxy (like Apache) with SSL enabled. The instructions below provide an example of how to do this.

Encrypting Client Connections using Apache and SSL

This section shows how to encrypt client connections to MWS using Apache and SSL. These instructions have been tested on CentOS™ 6.2 with the "Web Server" software set installed. The same ideas are applicable to other operating systems, but the details might be different. As shown in the diagram below, these instructions assume that Tomcat and Apache are running on the same server.

• Create a self-signed certificate. See http://www.openssl.org/docs/HOWTO/certificates.txt for more details if desired.

Instead of creating a self-signed certificate, you can buy a certificate from a certificate vendor. If you do, then the vendor will provide instructions on how to configure Apache with your certificate.

• Run these commands:

cd /etc/pki/tls/certs
cp -p make-dummy-cert make-dummy-cert.bak
cp -p localhost.crt localhost.crt.bak

• Edit make-dummy-cert and replace the answers() function with code similar to this:

answers() {
		echo US
		echo Utah
		echo Provo
		echo Adaptive Computing Enterprises, Inc.
		echo Engineering
		echo test1.adaptivecomputing.com
		echo
}

• Run this command:

./make-dummy-cert localhost.crt

• Configure Apache to use the new certificate and to redirect MWS requests to Tomcat. To do so, edit /etc/httpd/conf.d/ssl.conf.
• Comment out this line:

SSLCertificateKeyFile /etc/pki/tls/private/localhost.key

• Add these lines near the end, just above </VirtualHost>:

ProxyPass /mws http://127.0.0.1:8080/mws retry=5
ProxyPassReverse /mws http://127.0.0.1:8080/mws

• Configure Apache to use SSL for all MWS requests.
• Add these lines to the end of /etc/httpd/conf/httpd.conf:

RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule (/mws.*) https://%{HTTP_HOST}%{REQUEST_URI}

• Give Apache permission to connect to Tomcat.

setsebool -P httpd_can_network_connect 1

• Turn on Apache.

chkconfig httpd on
service httpd start

• Using system-config-firewall-tui, enable "Secure WWW (HTTPS)" and "WWW (HTTP)" as trusted services.

Encrypting Client Connections using Tomcat and SSL

This section shows how to encrypt client connections to MWS using Tomcat and SSL but without requiring the use of Apache. These instructions have been tested on CentOS™ 6.2 with Tomcat 6.0.

Generate a Certificate

First you must generate a certificate. To do so, use the keytool utility that is shipped with the Oracle Java Runtime Environment. As the Tomcat user, run the following

keytool -genkey -alias tomcat -keyalg RSA

Specify a password value of "changeit". This will create a .keystore file that contains the new certificate in the user's home directory.

Enable the Tomcat SSL Connector

Open the server.xml file, usually located in $CATALINA_HOME/conf/ ($CATALINA_HOME represents the directory where Tomcat is installed). Verify the SSL HTTP/1.1 Connector entry is enabled. To do so locate the SSL HTTP/1.1 Connector entry and uncomment it.

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" />

The code above enables SSL access on port 8443. The default for HTTPS is 443, but just as Tomcat uses 8080 instead of 80 to avoid conflicts, 8443 is used instead of 443.

Verify that server.xml is owned by the Tomcat user.

chown -R tomcat:tomcat server.xml

Next modify the MWS web.xml file. Add a security-constraint section to the $CATALINA_HOME/webapps/mws/WEB-INF/web.xml file found in your Tomcat directory.

<web-app>
  …
    <security-constraint>
      <web-resource-collection>
        <web-resource-name>MWS Secure URLs</web-resource-name>
        <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      </user-data-constraint>
    </security-constraint>
</web-app>

Now restart tomcat.

Connection to LDAP

MWS supports using SSL/TLS to secure connections to an LDAP server. Typically, LDAP servers reserve port 636 for SSL/TLS connections. In order to use SSL/TLS you need to place the PEM-encoded LDAP server security certificate in the MWS_HOME/etc/ssl.crt folder, and make sure the user running Tomcat either owns or has permission to read this certificate.

mkdir $MWS_HOME/etc/ssl.crt
cp ldapServerCert.pem $MWS_HOME/etc/ssl.crt
cd $MWS_HOME/etc/ssl.crt
chown tomcat:tomcat ldapServerCert.pem

To configure MWS to use SSL/TLS add the following to mws-config.groovy. (Note that ldap.security.server.certificate is the filename of a server certificate found in the MWS_HOME/etc/ssl.crt folder.)

ldap.port = 636
ldap.security.type = "SSL"
ldap.security.server.certificate = "ldapServerCert.pem"

Many LDAP servers also support the StartTLS protocol. StartTLS allows a client to connect to the standard insecure port, usually 389, and upgrade to a secure SSL/TLS connection. To configure StartTLS, set the ldap.security.type parameter to StartTLS as follows:

ldap.port = 389
ldap.security.type = "StartTLS"
ldap.security.server.certificate = "ldapServerCert.pem"

The following table lists the possible values for ldap.security.type.

By default, MWS looks for SSL certificates in the MWS_HOME/etc/ssl.crt folder. You can change this location by setting the mws.certificates.location parameter in mws-config.groovy. If the path specified is relative, MWS will resolve this path relative to the MWS_HOME directory. For example, if you set the mws.certificates.location to "etc/someOtherCertsFolder" MWS will look for certificates in MWS_HOME/etc/someOtherCertsFolder.

mws.certificates.location = "etc/someOtherCertsFolder

1.7 Version and Build Information

Browser

Using a browser, visit the MWS home page (for example, http://localhost:8080/mws/). At the bottom of the page is the MWS version information. See the screenshot below:

REST Request

Using a REST client or other HTTP client software, send a GET request to the rest/diag/about resource. Here is an example:

curl -u username:password http://localhost:8080/mws/rest/diag/about

This resource is also described under Diagnostics.

MANIFEST.MF File

If MWS fails to start, version and build information can be found in the META-INF/MANIFEST.MF file inside the MWS WAR file. The version properties begin with Implementation. Below is an excerpt of a MANIFEST.MF file:

Implementation-Build: 26
Implementation-Build-Date: 2012-06-19_14-18-59
Implementation-Revision: 376079a5e5f552f2fe25e6070fd2e84c646a98fd
Name: Grails Application
Implementation-Title: mws
Implementation-Version: 7.1.0-rc2
Grails-Version: 2.0.3

2 Access Control

2.1 Application Accounts

An application account also contains an auto-generated password that is visible only when creating the account or when resetting its password. Whenever an application sends a REST request to MWS, it needs to pass its credentials (username and password) in a Basic Authentication header. See the Authentication section for more information.

The Application Name is a human-friendly way to identify an application account, but MWS does not use it during authentication (or at any other time, for that matter).

The Enabled field is set to true automatically when an application account is created. To change the value of this field, see Modifying an Application Account.

Here is an example of how you might set the fields when creating an application account:

• Application Name: Moab Viewpoint
• Username: viewpoint
• Description: This application account grants access to Moab Viewpoint for Moab Cloud Suite.

The permissions granted to an application account may be customized while creating or modifying the account. See Creating an Application Account and Modifying an Application Account.

2.1.1 Managing Application Accounts

2.1.2 Listing Application Accounts

Each column (except Password) can be sorted in ascending or descending order by clicking on the column heading.

2.1.3 Creating an Application Account

Access to specific resources and plugin custom web services is granted or revoked by checking or unchecking the check boxes in the respective resources or plugin web services access control sections. For each resource, access may be granted to a resource for each method supported by MWS, including GET, POST, PUT, and DELETE. See the figure below for an example.

In this example, the application has access to all available methods for the Access Control Lists and Accounts resources as well as to retrieve the Events resource through the GET method, but is denied the permission to create new events through the POST method.

Access may also be granted to each plugin type's custom web service(s). When new plugin types or plugin web services are added to MWS, applications must be updated with the new access control settings. See below for an example.

In this example, the application has access to all the custom web services defined for the "Test" plugin type. Note that though Unsecured Web Services are listed, access to them cannot be denied (see Exposing Web Services for more information).

2.1.4 Displaying an Application Account

In addition to displaying the values for fields, grids are also displayed which represent the application's access control permissions defined for resources and plugin custom web services. Examples of the resources and the plugin web services access control displays are shown below.

2.1.5 Modifying an Application Account

2.1.6 Resetting an Application Password

2.1.7 Deleting an Application Account

3 API Documentation

Introduction

The Moab® Web Services (MWS) provide a set of RESTful resources that can be used to create, read, update, and delete various objects in the Moab® Workload Manager.

3.1 RESTful Web Services

In comparison to other architectures of web services which use a single HTTP method and service endpoint to perform multiple types of operations (such as a POST operation to a URL), REST utilizes all of the available HTTP methods and URLs that directly correlate to resources. For example, RESTful web services for books in a library may expose many URL endpoints and the HTTP methods available for each such as GET, POST, PUT, and DELETE. The list below gives the methods, URLs, and descriptions for a sample set of services. The number 1 represents a unique identifier for books in each case.

Note that in the cases of the POST and PUT operations, additional information may be needed to describe the resource to be created or the fields that should be modified.

Moab Web Services provides RESTful web services for many resources. The methods and URLs available are documented in the Resources section.

3.2 Data Format

{
  "number": 1,
  "decimalNumber": 1.2,
  "boolean": true,
  "string": "Any string",
  "dateString": "2013-05-23 17:32:02 UTC",
  "object": {
    "key": "value"
  },
  "array": [
    "value1",
    "value2"
  ],
  "nullValue": null
}

Dates in MWS, for both input and output, use the pattern "yyyy-MM-dd HH:mm:ss ZZZ". For more details on that pattern, see Joda-Time DateTimeFormat. For a list of valid time zone IDs, see Joda-Time Available Time Zones.

For more information on JSON, see json.org.

The data format of MWS is defined as follows:

• Input for a POST or PUT must be in JSON format. Set the Content-Type header to application/json.
• Output is in JSON format and always consists of an object with zero or more key/value pairs.
• The output may also be "pretty-printed" or formatted for human viewing by sending a URL parameter. See Global URL Parameters for more information.

3.3 Global URL Parameters

All URL parameters are optional.

API Version (api-version)

See Requesting Specific API Versions for information on this parameter and how it should be used.

Pretty (pretty)

By default, the output is easy for a machine to read but difficult for humans to read. The pretty parameter formats the output so that it is easier to read.

Field Selection (fields)

The fields parameter will include only the specified fields in the output. For list queries, the field selection acts on the objects in results and not on the totalCount or results properties themselves.

The format of the fields parameter is a comma-separated list of properties that should be included, as in id,state. Using periods, sub-objects may also be specified, and fields of these objects may be included as well. This is done with the same syntax for both single sub-objects and lists of sub-objects, as in id,requirements.requiredNodeCountMinimum,blockReason.message.

Example for a job query

GET /rest/jobs?api-version=2&fields=name,flags,requirements.taskCount,dates.createdDate

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "dates": {"createdDate": "2012-10-17 01:11:54 UTC"},
    "flags": ["GLOBALQUEUE"],
    "name": "Moab.24",
    "requirements": [{"taskCount": 1}]
  }]
}

Field Exclusion (exclude-fields)

The exclude-fields parameter is the opposite of the fields parameter. All fields will be included in the output except those that are specified. For list queries, the field exclusion acts on the objects in results and not on the totalCount or results properties themselves.

The format of the exclude-fields parameter is a comma-separated list of properties that should be excluded from the output, as in id,state. Using periods, sub-objects may also be specified, and fields of these objects may be excluded as well. This is done with the same syntax for both single sub-objects and lists of sub-objects, as in id,requirements.requiredNodeCountMinimum,blockReason.message.

Example

Suppose a query returns the following JSON:

GET /objects

{
  "id": "1",
  "listOfStrings":   [
    "string1",
    "string2"
  ],
  "listOfObjects": [  {
    "item1": "value1",
    "item2": "value2"
  }],
  "singleObject":   {
    "id": "obj1",
    "field1": "value1"
  }
}

The same query with exclude-fields would return the following output:

GET /objects?exclude-fields=id,listOfObjects.item2,singleObject.field1,listOfStrings

{
  "listOfObjects": [{"item1": "value1"}],
  "singleObject": {"id": "obj1"}
}

Sorting (sort)

Services, Service Templates, Images, and Events support sorting based on MongoDB syntax by using the sort parameter. To sort in ascending order, specify a 1 for the sorting field. To sort in descending order, specify a -1. Objects can also be sorted on nested fields by using dot notation to separate the sub-fields, such as field.subfield1.subfield2.

Examples

To sort services in ascending order by account:

http://localhost/mws/rest/services?sort={"account":1}

To sort services in descending order by account:

http://localhost/mws/rest/services?sort={"account":-1}

To sort services in descending order by processors:

http://localhost/mws/rest/services?sort={"attributes.moab.job.resources.procs":-1}

To sort service templates in ascending order by name:

http://localhost/mws/rest/service-templates?sort={"name":1}

To sort service templates in descending order by name:

http://localhost/mws/rest/service-templates?sort={"name":-1}

To sort service templates in ascending order by the nested field template:

http://localhost/mws/rest/service-templates?sort={"attributes.moab.job.template":1}

3.4 Requesting Specific API Versions

Additionally, several points should be noted:

• If no API version is requested, it will default to version 1.
• The Resources documentation contains information for the latest API version. For documentation of previous API versions, please see the table above.
• When the latest API version is requested, it resolves to the latest API version of MWS, such as 2 for MWS 7.2.

Examples

GET http://localhost:8080/mws/rest/nodes
// Data returned uses API version 1
GET http://localhost:8080/mws/rest/nodes?api-version=1
// Data returned uses API version 1
GET http://localhost:8080/mws/rest/nodes?api-version=2
// Data returned uses API version 2
GET http://localhost:8080/mws/rest/nodes?api-version=latest
// Data returned uses API version 2

3.5 Responses and Return Codes

Listing and Showing Resources

For any successful list or show operation (GET), a 200 OK response code is always returned. No additional headers beyond those typical of a HTTP response are given in the response.

The body of this response consists of the results of the list or show operation. For a list operation, the results are wrapped in metadata giving total and result counts. The result count represents the number of resource records returned in the current request, and the total count represents the number of all records available. These differ when querying or the max and offset parameters are used. The following is an example of a list operation response:

{
	"resultCount":1,
	"totalCount":5,
	"results":[
		{
			"id":"Moab.1",
			…
		}
	]
}

For a show operation, the result is given as a single object:

{
	"id":"Moab.1",
	…
}

Creating Resources

A successful creation (POST) of a resource has two potential response codes:

• If the resource was created immediately, a 201 Created response code is returned.
• If the resource is still being created, a 202 Accepted response code is returned.

In either case, a Location header is added to the response with the full URL which can be used to get more information about the newly created resource or the task associated with creating the resource (if a 202 is returned).

Additionally, the body of the response will contain the unique identifier of the newly created resource or the unique identifier for the task associated with creating the resource (if a 202 is returned).

For example, during creation or submission of a job, a 201 response code is returned with the following response headers and body:

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: /mws/rest/jobs/Moab.21
X-Moab-Status: Success
X-Moab-Code: 000
Content-Type: application/json;charset=utf-8
Content-Length: 16
Date: Wed, 21 Dec 2011 23:04:47 GMT

{"id":"Moab.21"}

For another resource that is not immediately created, such as virtual machines, the response headers and body are shown below. In this case, a job is submitted to track the progress of the VM creation. This job contains information pertaining to the VM that is being created.

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
Location: /mws/rest/jobs/vmcreate-1
X-Moab-Status: Success
X-Moab-Code: 000
Content-Type: application/json;charset=utf-8
Content-Length: 23
Date: Wed, 21 Dec 2011 23:12:50 GMT

{"jobId":"vmcreate-1"}

As can be seen, the body of the response contains only a job ID and not the ID of the virtual machine.

Modifying Resources

For any successful resource modification operation (PUT), a 200 OK or 202 Accepted response code is returned. A 200 response code signifies that the modification was immediately completed. No additional headers are returned in this case. A 202 response code is used again to signify that the modification is not yet complete and additional actions are taking place. In this case, a Location header is also returned with the full URL of the resource describing the additional actions.

In the case of a 200 response code, the body of this response typically consists of an object with a single messages property containing a list of statuses or results of the modification(s). However, a few exceptions to this rule exist as documented in the Resources section. In the case of a 202 response code, the format is the same as for a 202 during a creation operation, in that the body consists of an object with the unique identifier for the task associated with the additional action(s).

For example, when modifying a job, several messages may be returned as follows with the associated 200 response code.

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Moab-Status: Success
X-Moab-Code: 000
X-Moab-Message:
Content-Type: application/json;charset=utf-8
Content-Length: …
Date: Thu, 22 Dec 2011 16:49:43 GMT

{
	"messages":[
		"gevent processed",
		"variables successfully modified"
	]
}

When modifying a virtual machine, however, the action sometimes does not occur immediately, such as when migrating the VM to another hypervisor as described in the VM documentation. In this case, the headers and response body are as follows:

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
Location: /mws/rest/jobs/vmmigrate-1
X-Moab-Status: Success
X-Moab-Code: 000
Content-Type: application/json;charset=utf-8
Content-Length: 22
Date: Wed, 21 Dec 2011 23:12:50 GMT

{"jobId":"vmmigrate-1"}

Deleting Resources

For any successful resource deletion operation (DELETE), a 200 OK or 202 Accepted response code is returned. A 200 response code signifies that the deletion was immediately completed. No additional headers are returned in this case. A 202 response code is used again to signify that the deletion is not yet complete and additional actions are taking place. In this case, a Location header is also returned with the full URL of the resource describing the additional actions.

In the case of a 200 response code, the body of this response is empty. In the case of a 202 response code, the format is the same as for a 202 during a creation operation, in that the body consists of an object with the unique identifier for the task associated with the additional action(s).

For example, when deleting a job, a 200 response code is returned with an empty body as shown below.

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Moab-Status: Success
X-Moab-Code: 000
X-Moab-Message:
Content-Type: application/json;charset=utf-8
Content-Length: 0
Date: Thu, 22 Dec 2011 16:49:43 GMT

When deleting a virtual machine, however, the action does not occur immediately. In this case, the headers and response body are as follows:

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
Location: /mws/rest/jobs/vmdestroy-1
X-Moab-Status: Success
X-Moab-Code: 000
Content-Type: application/json;charset=utf-8
Content-Length: 22
Date: Wed, 21 Dec 2011 23:12:50 GMT

{"jobId":"vmdestroy-1"}

Moab Response Headers

In addition to the typical HTTP headers and the Location header described above, several headers are returned if the operations directly interact with Moab. These headers are described in the following table:

3.6 Error Messages

400 Bad Request

This response code is returned when the request itself is at fault, such as when trying to modify a resource with an empty PUT request body or when trying to create a new resource with invalid parameters. The response body is as follows:

{
	"messages":[
		"Message describing error",
		"Possible prompt to take action"
	]
}

401 Unauthorized

This response code is returned when authentication credentials are not supplied or are invalid. The response body is as follows:

{
	"messages":[
		"You must be authenticated to access this area"
	]
}

403 Forbidden

This response code is returned when the credentials supplied are valid, but the permissions granted are insufficient for the operation. This occurs when using Application Accounts with limited access.

{
	"messages":[
		"You are not authorized to access this area"
	]
}

404 Not Found

This response code is returned when the request specifies a resource that does not exist. The response body is as follows:

{
	"messages":[
		"The resource with id 'uniqueId' was not found"
	]
}

405 Method Not Allowed

This response code is returned when a resource does not support the specified HTTP method as an operation. The response body is as follows:

{
	"messages":[
		"The specified HTTP method is not allowed for the requested resource"
	]
}

500 Internal Server Error

This indicates that there was an internal server error while performing the request, or that an operation failed in an unexpected manner. These are the most serious errors returned by MWS. If additional information is needed, the MWS log may contain further error data. The response body is as follows:

{
	"messages":[
		"A problem occurred while processing the request",
		"A message describing the error"
	]
}

3.7 Pre and Post-Processing Hooks

The full reference for available hooks and methods available to them can be found on the Hooks page in the reference guide.

Configuring Hooks

The directory of the hooks folder may be changed by providing a value for mws.hooks.location in the configuration file. If the directory starts with a path separator (ie /path/to/hooks), it will be treated as an absolute path. Otherwise, it will be used relative to the location of the MWS home directory.

For example, if the MWS home directory is set to /opt/mws, the hooks directory by default would be in /opt/mws/hooks. Changing the mws.hooks.location property to myhooks would result in the hooks directory being located at /opt/mws/myhooks. Due to the default location of the MWS home directory, the default directory of the hooks directory is /opt/mws/hooks.

On startup, if the hooks directory does not exist, it will be created with a simple README.txt file with instructions on how to create hooks, the objects available, and the hooks available. If the folder or file is unable to be created, a message will be printed on the log with the full location of a README file, copied into a temporary directory.

Defining Hooks for a Resource

Hooks are defined for resources by creating groovy class files in the hooks directory (MWS_HOME/hooks by default). Each groovy file must be named by the resource URL it is associated with and end in ".groovy". The following table shows some possible hook files that may be created. Notice that the virtual machines hook file is abbreviated as vms, just as the URL for virtual machines is /rest/vms. In all cases, the hook file names will match the URLs.

A complete example of a hook file is as follows:

// Example before hook
def beforeList = {
	// Perform actions here
	// Return true to allow the API call to execute normally
	return true
}
def beforeShow = {
	// Perform actions here
	// Render messages to the user with a 405 Method Not Allowed 
	//	HTTP response code
	renderMessages("Custom message here", 405)
	// Return false to stop normal execution of the API call
	return false
}
// Example after hook
def afterList = { o ->
	if (!isSuccess()) {
		// Handle error here
		return false
	}
	// Perform actions here
	return o
}

As the specific format for the hooks for before and after are different, each will be explained separately.

Before Hooks

As shown above, before hooks require no arguments. They can directly act on several properties, objects, and methods as described in the Hooks reference guide. The return value is one of the most important aspects of a before hook. If it is false, a renderMessages, renderObject, renderList, render, or redirect method must first be called. This signifies that the API call should be interrupted and the render or redirect action specified within the hook is to be completed immediately.

A return value of true signifies that the API call should continue normally. Parameters, session variables, request and response variables may all be modified within a before hook.

If no return value is explicitly given, the result of the last statement in the before hook to be executed will be returned. This may cause unexpected behavior if the last statement resolves to false.

For all methods available to before hooks as well as specific examples, see the Hooks page in the reference guide.

After Hooks

After hooks are always passed one argument: the object or list that is to be rendered as JSON. This may be modified as desired, but note that the object or list value is either a JSONArray or JSONObject. Therefore, it may not be accessed and modified as a typical groovy Map.

Unlike before hooks, after hooks should not call the render* methods directly. This method will automatically be called on the resulting object or list returned. The redirect and render methods should also not be called at this point. Instead, if a custom object or list is desired to be used, the serializeObject and serializeList methods are available to create suitable results to return.

The return value of an after hook may be one of two possibilities:

1. The potentially modified object or list passed as the first argument to the hook. In this case, this value will override the output object or list unless it is null.
2. Null or false. In this case, the original, unmodified object or list will be used in the output.

The return value of the after hook, if not null or false, must be the modified object passed into the hook or an object or list created with the serialize* methods.

For all methods available to after hooks as well as specific examples, see the Hooks page in the reference guide.

Error Handling

After hooks, unlike the before hooks, have the possibility of handling errors encountered during the course of the request. Handling errors is as simple as adding a one-line check to the hook as shown above or in the following code:

if (!isSuccess()) {
	// Handle error
	return false
}

It is recommended that each after hook contain at least these lines of code to prevent confusion on what the input object or list represents or should look like.

The isSuccess() function is false if and only if the HTTP response code is 400 or higher, such as a 404 Not Found, 400 Bad Request, or 500 Internal Server Error and the cause of the error state was not in the associated before hook. In other words, objects and lists rendered in the before hook with any HTTP response code will never run the associated after hook.

When handling errors, the passed in object will always contain a messages property containing a list of Strings describing the error(s) encountered.

Defining Common Hooks

Sometimes it is beneficial to create hooks which are executed for all calls of a certain type, such as a beforeList hook that is executed during the course of listing any resource. These are possible using an all.groovy file. The format of this file is exactly the same as other hook files. The order of execution is as follows:

1. Before common hook executed
2. Before resource-specific hook executed
3. Normal API call executed
4. After resource-specific hook executed
5. After common hook executed

3.8 Authentication

• For insructions on how to set the credentials for the default User account, see the "Client Connections to MWS" section in Security.
• For insructions on how to manage Application accounts, see Application Accounts.

To use Basic Authentication, each client request must contain a header that looks like this:

Authorization: Basic YWRhcHRpdmU6YzNVU3R1bkU=

The string after the word Basic is the base64 encoding of username : password . In the example above, YWRhcHRpdmU6YzNVU3R1bkU= is the base64 encoding of adaptive:c3UStunE. See section 2 of RFC 2617 for more details.

The username and password in the Basic Authentication header are encoded but not encrypted. Therefore, it is strongly recommended that MWS be run behind a proxy (like Apache) with SSL enabled. See the section "Encrypting Client Connections using Apache and SSL" under Security.

4 Resources

This section only contains documentation for the latest API version. Please see the table in the Requesting Specific API Versions section for links to documentation for previous versions.

4.1 Access Control Lists

The ACL API contains the type and description of all fields in the ACL Rules object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

ACLs are not directly manipulated through a single URL, but with sub-URLs of the other objects such as Virtual Containers and Reservations.

4.1.1 Getting ACLs

Supported Objects

The following is a list of objects that will return ACL Rules when queried:

• Reservations
• Standing Reservations
• Virtual Containers

4.1.2 Creating or Updating ACLs

Quick Reference

PUT http://localhost/mws/rest/reservations/<rsvId>/acl-rules
PUT http://localhost/mws/rest/vcs/<vcId>/acl-rules

4.1.2.1 Create or Update ACL

URLs and Parameters

PUT http://localhost/mws/rest/reservations/<objectId>/acl-rules
PUT http://localhost/mws/rest/vcs/<objectId>/acl-rules

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available for the PUT method, along with some sample values.

{"aclRules": [{
  "affinity": "POSITIVE",
  "comparator": "LEXIGRAPHIC_EQUAL",
  "type": "USER",
  "value": "ted"
}]}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

{"messages":["Virtual container 'vc1' successfully modified"]}

Samples

Create or update multiple ACLs on a single object:

{"aclRules": [
    {
    "affinity": "POSITIVE",
    "comparator": "LESS_THAN_OR_EQUAL",
    "type": "DURATION",
    "value": "3600"
  },
    {
    "affinity": "POSITIVE",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "USER",
    "value": "ted"
  }
]}

Restrictions

• ACL Rules cannot be added to or updated on Standing Reservations.
• The affinity and comparator fields are ignored for Virtual Containers.

4.1.3 Deleting ACLs

Quick Reference

ACL Rules cannot be removed from Standing Reservations.

DELETE http://localhost/mws/rest/reservations/<rsvId>/acl-rules/<aclId>
DELETE http://localhost/mws/rest/vcs/<vcId>/acl-rules/<aclId>

4.1.3.1 Delete ACL

URLs and Parameters

DELETE http://localhost/mws/rest/reservations/<objectId>/acl-rules/<aclId>
DELETE http://localhost/mws/rest/vcs/<objectId>/acl-rules/<aclId>

See Global URL Parameters for available URL parameters.

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

{"messages":["Successfully modified virtual container 'vc1'"]}

Restrictions

• ACL Rules cannot be removed from Standing Reservations.

4.2 Accounts

This resource refers to Moab Accounting Manager accounts, not Moab Workload Manager accounts.

The Account API contains the type and description of fields that all Accounts have in common.

Supported Methods

4.2.1 Getting Accounts

Quick Reference

GET http://localhost/mws/rest/accounts

4.2.1.1 Get All Accounts

URLs and Parameters

GET http://localhost/mws/rest/accounts?proxy-user=<USER>[&custom-fields=Department][&query={"deleted":false}][&sort={"requestId":-1}]

The query parameter does not support the full Mongo query syntax. Only querying for a simple, non-nested JSON object is allowed.

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 2,
  "resultCount": 2,
  "results":   [
        {
      "id": "biology",
      "description": "Biology Dept."
    },
        {
      "id": "chemistry",
      "description": "Chemistry Dept."
    }
  ]
}

4.2.1.2 Get Single Account

URLs and Parameters

GET http://localhost/mws/rest/accounts/<id>

See Global URL Parameters for available URL parameters.

Sample Responses

{
  "id": "chemistry",
  "active": true,
  "organization": "",
  "description": "Chemistry Dept",
  "creationTime": "2012-04-11 06:56:11 UTC",
  "modificationTime": "2012-04-11 06:56:11 UTC",
  "deleted": false,
  "requestId": 94,
  "transactionId": 283,
  "users":   [
        {
      "id": "amy",
      "active": true,
      "admin": false
    },
        {
      "id": "bob",
      "active": true,
      "admin": false
    },
            {
      "id": "dave",
      "active": true,
      "admin": false
    }
   ]
}

4.3 Credentials

The Credential API is new with API version 2. The supported methods table below requires each resource to be accessed with a URL parameter of api-version=2.

See Requesting Specific API Versions for more information.

The Credential API contains the type and description of all fields in the Credential object.

Supported Methods

4.3.1 Getting Credentials

Quick Reference

GET http://localhost/mws/rest/credentials/accounts
GET http://localhost/mws/rest/credentials/classes
GET http://localhost/mws/rest/credentials/groups
GET http://localhost/mws/rest/credentials/qoses
GET http://localhost/mws/rest/credentials/users

4.3.1.1 Get All Account Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/accounts

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "account1"}
  ]
}

4.3.1.2 Get All Class Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/classes

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "class1"}
  ]
}

4.3.1.3 Get All Group Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/groups

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "group1"}
  ]
}

4.3.1.4 Get All QoS Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/qoses

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "qos1"}
  ]
}

4.3.1.5 Get All User Credentials

URLs and Parameters

GET http://localhost/mws/rest/credentials/users

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results":   [
    {"name": "user1"}
  ]
}

4.4 Diagnostics

Supported Methods

4.4.1 Version and Build Information

Quick Reference

GET http://localhost/mws/rest/diag/about

URLs and Parameters

GET http://localhost/mws/rest/diag/about

Sample Response

The response contains the application version, build number, build date, and revision.

{
  "suite":"Cloud",
  "pluginCommonsVersion":"0.9.3",
  "version":"7.1",
  "build":"100",
  "buildDate":"2012-01-01_16-00-00",
  "revision":"1000"
}

4.4.2 Diagnose Authentication

Quick Reference

GET http://localhost/mws/rest/diag/auth

URLs and Parameters

GET http://localhost/mws/rest/diag/auth

Sample Response

A successful result is indicated by the 200 response code while a failure is indicated by a 401 response code.

{}

4.4.3 Connection Health Information

Quick Reference

GET http://localhost/mws/rest/diag/health
GET http://localhost/mws/rest/diag/health/detail

4.4.3.1 Get Health Summary

URLs and Parameters

GET http://localhost/mws/rest/diag/health/summary

If the MongoDB connection is down, authenticated resources are not available. While this resource does not possess much detail beyond that of simple connection information, it is still useful as it does not require authentication and therefore can be used to determine connection problems with MongoDB.

Sample Response

The response contains the connection health for Moab Workload Manager (MWM), Moab Accounting Manager (MAM), and MongoDB. A true response value indicates that the connection is healthy and available, and a false response indicates that the connection is currently down. Likewise, the mongoConnected property for MWM signifies the state of the MWM to MongoDB connection. The possible values of this state are UP, DOWN, NOT_CONFIGURED when the MongoDB server is not configured in MWM, NOT_SUPPORTED when MWM is not compiled with MongoDB support, and UNKNOWN when MWS cannot communicate with MWM.

{
  "mam": {
    "connected": true
  },
  "mongo": {
    "connected": false
  },
  "mwm": {
    "connected": true,
    "mongoConnected": "UP"
  }
}

4.4.3.2 Get Health Detail

URLs and Parameters

GET http://localhost/mws/rest/diag/health/detail

If the MongoDB connection is down, authenticated resources such as this are not available. In this case, using the Get Health Summary instead may be required.

Sample Response

The response contains the connection health and information for Moab Workload Manager (MWM), Moab Accounting Manager (MAM), and MongoDB. A "connected": true response value indicates that the connection is healthy and available, and a false response indicates that the connection is currently down. Likewise, the mongoConnected property for MWM signifies the state of the MWM to MongoDB connection. The possible values of this state are UP, DOWN, NOT_CONFIGURED when the MongoDB server is not configured in MWM, NOT_SUPPORTED when MWM is not compiled with MongoDB support, and UNKNOWN when MWS cannot communicate with MWM. A message is also present for all down connections except MWM to MongoDB giving a reason for the error state.

{
  "mam": {
    "connected": false,
    "host": "localhost",
    "message": "There was an error connecting to MAM at 'localhost', the secret key does not match.",
    "port": 7112,
    "version": null
  },
  "mongo": {
    "connected": true,
    "databaseName": "mws",
    "host": "127.0.0.1",
    "message": null,
    "port": 27017,
    "replicaSet": null,
    "username": "mws",
    "version":"2.0.1"
  },
  "mwm": {
    "connected": true,
    "host": "localhost",
    "message": null,
    "port": 42559,
    "licensedFeatures": ["vm", "provision"],
    "state":"RUNNING",
    "mongoConnected": "DOWN",
    "mongoCredentialsSet":false,
    "mongoHost":"localhost",
    "mongoPort":27017,
    "version": "7.2"
  }
}

4.4.4 LDAP Information

Quick Reference

GET http://localhost/mws/rest/diag/ldap

URLs and Parameters

GET http://localhost/mws/rest/diag/ldap

Sample Response

{
  "server": "openldapsambaserver",
  "port": 389,
  "securityType": "SSL",
  "baseDNs": ["dc=testldap,dc=ac"],
  "bindUser": "cn=admin,dc=testldap,dc=ac",
  "userObjectClass": "posixAccount",
  "userNameAttribute": "uid"
}

4.5 Events

The Event API contains the type and description of all fields in the Event object. It also contains details regarding which fields are valid during POST actions.

Supported Methods

Configuration

Logging events to a flat file requires that you make a few changes to the configuration in the log4j section of the mws-config.groovy file so that events will be logged to the events.log file, and all other Moab Web Services logging information will be sent to the mws.log file.

Causing events.log to Roll Based on a Time Window

You can specify how often the events.log file rolls. The following example illustrates the configuration changes you will need make to mws-config.groovy to cause the events.log file to roll based on a time window. (In this example, mws-config.groovy is configured so that events.log rolls daily at midnight.)

log4j = {
  def eventAppender = new org.apache.log4j.rolling.RollingFileAppender(name: 'events', layout: pattern(conversionPattern: "%m%n"))
  def rollingPolicy = new org.apache.log4j.rolling.TimeBasedRollingPolicy(fileNamePattern: '/tmp/events.%d{yyyy-MM-dd}', activeFileName: '/tmp/events.log')
  rollingPolicy.activateOptions()
  eventAppender.setRollingPolicy(rollingPolicy)
  appenders {
      appender eventAppender
      rollingFile name: 'rootLog',
        file: '/tmp/mws.log',
        maxFileSize: '1GB'
  }
  root {
    warn 'rootLog'
  }
  trace additivity:false, events:'com.ace.mws.events.EventFlatFileWriter'
}

Note the RollingFileAppender and the TimeBasedRollingPolicy lines. These lines configure Moab Web Services to write the event log to the events.log file.

Rolled log files will have a date appended to their name in this format: 'yyyy-MM-dd' (for example, events.log.2012-02-28).

If you want the event log file to roll at the beginning of each month, change the TimeBasedRollingPolicy "fileNamePattern" date format to 'yyyy-MM'. For example:

def rollingPolicy = new org.apache.log4j.rolling.TimeBasedRollingPolicy(fileNamePattern: '/tmp/events.%d{yyyy-MM}', activeFileName: '/tmp/events.log')

If you want the event log file to roll at the beginning of each hour, change the date format to 'yyyy-MM-dd_HH:00'. For example:

def rollingPolicy = new org.apache.log4j.rolling.TimeBasedRollingPolicy(fileNamePattern: '/tmp/events.%d{yyyy-MM-dd_HH:00}', activeFileName: '/tmp/events.log')

Configuring events.log to Roll Based on File Size Threshold

You can also configure the events.log file to roll when the log size exceeds a specified threshold. The following example illustrates the configuration changes you will need to make to mws-config.groovy to cause the events.log file to roll on a size threshold. (In this example, mws-config.groovy is configured so that events.log rolls when its size exceeds 50 MB.)

log4j = {
  appenders {
      rollingFile name: 'events',
        file: '/tmp/events.log',
        maxFileSize: '50MB',
        maxBackupIndex:10
      rollingFile name: 'rootLog',
        file: '/tmp/mws.log',
        maxFileSize: '1GB'
  }
  root {
    warn 'rootLog'
  }
  trace additivity:false, events:'com.ace.mws.events.EventFlatFileWriter'
}

Note that maxFileSize is set to '50MB'. This means that when the events.log file exceeds 50 MB, it will roll.

The name for the rolled log will be "events.log.1". When the new events.log file exceeds 50 MB, it will roll and be named "events.log.1", while the old "events.log.1" file will be renamed "events.log.2". This process will continue until the optional maxBackupIndex value is met. In the example above, maxBackIndex is set to 10. This means that Moab Web Services will delete all but the ten most recent events.log files. Using this feature helps prevent hard drives from filling up.

Additivity

The additivity attribute of the EventFlatFileWriter logger can be either "true" or "false". If you specify "true", events will be logged to the events.log file and the mws.log file. If you specify "false", events will be logged to the events.log file only. (All other Moab Web Services logging information will be logged to the mws.log file, as configured by the rootLog appender.)

To log events to the mws.log file in addition to the events.log file, make this configuration: additivity:true. For example:

trace additivity:true, events:'com.ace.mws.events.EventFlatFileWriter'

For more configuration options, see Apache Extras Companion for log4j.

Deleting Old Events

By default, MWS will hold event data in MongoDB indefinitely. However, if disk space is limited, you may want to regularly delete old, unneeded events from MongoDB. This section contains some examples of how you can do this.

Let's say that you want to delete events that are older than 90 days. You could run this script. (There are 86,400,000 milliseconds in a day, so in this example, 90*86400000 corresponds to 90 days in milliseconds.)

$ mongo
MongoDB shell version: 2.0.1
connecting to: test
> use mws
> db.event.remove({eventTime:{$lt:new Date(new Date().getTime()-90*86400000)}})
> exit

#!/bin/bash
printf 'use mws_dev\ndb.event.remove({eventTime:{$lt:new Date(new Date().getTime()-90*86400000)}})\nexit' | mongo

Now say that you want to set up a cron job ($crontab -e) so that old events are automatically deleted on a certain day of the week (for example, every Sunday at 2:00 a.m.), you would add an entry like this:

00 02 * * 0 /root/deleteOldEvents.sh

4.5.1 Getting Events

Quick Reference

GET http://localhost/mws/rest/events[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/events/<id>

4.5.1.1 Get All Events

URLs and Parameters

GET http://localhost/mws/rest/events[?query={"field":"value"}&sort={"field":<1|-1>}]

See Global URL Parameters for available URL parameters.

Sample Response

{
   "totalCount":3,
   "resultCount":3,
   "results":[
      {
         "details":{
         },
         "errorMessage":{
            "errorCode":"542",
            "message":"Cannot communicate with XCAT resource manager",
            "originator":"XCAT"
         },
         "eventCategory":"failure",
         "eventTime":"2012-01-27 15:18:32 UTC",
         "eventType":"rmfailure",
         "facility":"rm",
         "primaryObject":{
            "serialization":null,
            "type":"rm",
            "id":"xcat"
         },
         "sourceComponent":"MWM",
         "status":"failure",
         "id":"4faddab8c4aa264506f8ac3d"
      },
      {
         "details":{
         },
         "eventCategory":"start",
         "eventTime":"2012-01-27 15:18:31 UTC",
         "eventType":"schedcyclestart",
         "facility":"scheduler",
         "sourceComponent":"MWM",
         "status":"success",
         "id":"4faddab8c4aa264506f8ac3c"
      },
      {
         "details":{
            "alpha":"lorem ipsum dolor sit amet",
            "bravo":"2",
            "charlie":"consectetur adipisicing elit, sed do"
         },
         "eventCategory":"start",
         "eventTime":"2012-01-27 15:18:30 UTC",
         "eventType":"jobstart",
         "facility":"job",
         "initiatedBy":{
            "proxyUser":"bob",
            "user":"tomcat6"
         },
         "primaryObject":{
            "serialization":"\n         <job JobID=\"moab.849\" ReqAWDuration=\"100000\" User=\"bob\" />\n      ",
            "type":"job",
            "id":"moab.849"
         },
         "relatedObjects":[
            {
               "type":"vm",
               "id":"vm56"
            },
            {
               "type":"service",
               "id":"lamp.211"
            }
         ],
         "sourceComponent":"MWM",
         "status":"success",
         "id":"4faddab8c4aa264506f8ac3b"
      }
   ]
}

Querying Events

It is possible to query events by one or more fields based on MongoDB query syntax. The following contains examples of simple and complex event queries and event queries by date.

Simple Queries

To see only events that are of type "jobsubmit":

http://localhost/mws/rest/events?query={"eventType":"jobsubmit"}

To see only events of type "jobsubmit" with the status of "failure":

http://localhost/mws/rest/events?query={"eventType":"jobsubmit","status":"failure"}

To see only events with the "job" facility:

http://localhost/mws/rest/events?query={"facility":"job"}

To see only events in the "start" event category:

http://localhost/mws/rest/events?query={"eventCategory":"start"}

More Complex Queries

You can query on embedded JSON objects within the event JSON. For example, to see events associated with proxyUser bob:

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":"bob"}

To see only events that are NOT associated with bob:

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":{"$ne":"bob"}}

When the field values of the desired events are a finite set, you can use the $in operator. For example, to see events that relate to either alice, bob, or charlie:

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":{"$in":["alice","bob","charlie"]}}

Querying Events by Date

To see events created before January 27, 2012 at 12:08 a.m. UTC:

http://localhost/mws/rest/events?query={"eventTime":{"$lt":"2012-01-27 12:08:00 UTC"}}

To see events created before or on January 27, 2012 at 12:08 a.m. UTC:

http://localhost/mws/rest/events?query={"eventTime":{"$lte":"2012-01-27 12:08:00 UTC"}}

To see all events created after January 27, 2012 at 12:04 a.m. UTC:

http://localhost/mws/rest/events?query={"eventTime":{"$gt":"2012-01-27 12:04:00 UTC"}}

To see all events created after or on January 27, 2012 at 12:04 a.m. UTC:

http://localhost/mws/rest/events?query={"eventTime":{"$gte":"2012-01-27 12:04:00 UTC"}}

To see events created between 12:04 a.m. and 12:08 a.m. UTC inclusive:

http://localhost/mws/rest/events?query={"eventTime":{"$gte":"2012-01-27 12:04:00 UTC","$lte":"2012-01-27 12:08:00 UTC"}}

To see events created between 12:04 a.m. and 12:08 a.m. UTC inclusive that are associated with proxyUser bob:

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":"bob","eventTime":{"$gte":"2012-01-27 12:04:00 UTC","$lte":"2012-01-27 12:08:00 UTC"}}

To see events created between 12:04 a.m. and 12:08 a.m. UTC inclusive, that are associated with proxyUser bob, and that are of type "jobsubmit":

http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":"bob","eventType":"jobsubmit","eventTime":{"$gte":"2012-01-27 12:04:00 UTC","$lte":"2012-01-27 12:08:00 UTC"}}

Sorting

See the sorting section of Global URL Parameters

Limiting the Number of Results

If you want to limit the number of results of events, you can use the max parameter. For example, to see only 10 "vmmigrate" events:

http://localhost/mws/rest/events?query={"eventType":"vmmigrate"}&sort={"eventTime":1}&max=10

To see "vmcreate" events 51-60 when sorted by eventTime in descending order, you can combine max with offset, as follows:

http://localhost/mws/rest/events?query={"eventType":"vmcreate"}&sort={"eventTime":-1}&max=51&offset=60

Retrieving a Subset of Fields

To cause only certain fields to return for each event, use the fields parameter. For example, to show only the eventTime field for each event:

http://localhost/mws/rest/events?max=3&fields=eventTime

This returns:

{
  "totalCount": 187,
  "resultCount": 3,
  "results":   [
    {"eventTime": "2012-03-05 10:01:59 UTC"},
    {"eventTime": "2012-03-05 10:02:00 UTC"},
    {"eventTime": "2012-03-05 10:02:01 UTC"}
  ]
}

To show the name, type, and status:

http://localhost/mws/rest/events?fields=name,type,status

This returns:

{
  "totalCount": 187,
  "resultCount": 3,
  "results":   [
        {
      "eventTime": "2012-03-05 10:01:59 UTC",
      "eventType": "jobsubmit",
      "status": "failure"
    },
        {
      "eventTime": "2012-03-05 10:02:00 UTC",
      "eventType": "jobstart",
      "status": "success"
    },
        {
      "eventTime": "2012-03-05 10:02:01 UTC",
      "eventType": "vmmigrate",
      "status": "success"
    }
  ]
}

4.5.1.2 Get Single Event

URLs and Parameters

GET http://localhost/mws/rest/events/<id>

See Global URL Parameters for available URL parameters.

Sample Response

{
  "details":   {
    "attribute": "walltime",
    "modifier": "increase",
    "value": "200000"
  },
  "eventCategory": "job",
  "eventTime": "2012-01-27 00:07:00 UTC",
  "eventType": "jobmodify",
  "facility": "baseline",
  "initiatedBy":   {
    "proxyUser": "bob",
    "user": "viewpoint"
  },
  "primaryObject":   {
    "serialization": null,
    "type": "job",
    "id": "moab.900"
  },
  "sourceComponent": "MWM",
  "status": "success",
  "id": "4fa46081c4aa5b896ac4b757"
}

4.5.2 Creating Events

Quick Reference

POST http://localhost/mws/rest/events

4.5.2.1 Create Event

URLs and Parameters

POST http://localhost/mws/rest/events

Request Body

Unlike most other URLs, the events URL accepts both JSON and XML. Be sure to set the Content-Type HTTP header to either application/json or application/xml.

[
   {
      "eventTime":"2012-01-27 15:18:30 UTC",
      "eventType":"jobstart",
      "eventCategory":"start",
      "sourceComponent":"MWM",
      "status":"success",
      "facility":"job",
      "initiatedBy":{
         "proxyUser":"bob",
         "user":"tomcat6"
      },
      "primaryObject":{
         "serialization":"<job JobID=\"moab.849\" ReqAWDuration=\"100000\" User=\"bob\" />",
         "type":"job",
         "id":"moab.849"
      },
      "relatedObjects":[
         {
            "type":"vm",
            "id":"vm56"
         },
         {
            "type":"service",
            "id":"lamp.211"
         }
      ],
      "details":{
         "alpha":"lorem ipsum dolor sit amet",
         "bravo":"2",
         "charlie":"consectetur adipisicing elit, sed do"
      }
   },
   {
      "eventTime":"2012-01-27 15:18:32 UTC",
      "eventType":"rmfailure",
      "eventCategory":"failure",
      "sourceComponent":"MWM",
      "status":"failure",
      "facility":"rm",
      "primaryObject":{
         "serialization":null,
         "type":"rm",
         "id":"xcat"
      },
      "errorMessage":{
         "errorCode":"542",
         "message":"Cannot communicate with XCAT resource manager",
         "originator":"XCAT"
      }
   },
   {
      "eventTime":"2012-01-27 15:18:31 UTC",
      "eventType":"schedcyclestart",
      "eventCategory":"start",
      "sourceComponent":"MWM",
      "status":"success",
      "facility":"scheduler"
   }
]

<Events>
  <Event eventTime="2012-01-27T15:18:30.000-07:00" eventType="jobstart" eventCategory="start" sourceComponent="MWM" status="success" facility="job">
    <InitiatedBy user="tomcat6" proxyUser="bob"/>     
    <PrimaryObject objectType="job" objectID="moab.849">
      <Serialization>
         <![CDATA[<job JobID="moab.849" ReqAWDuration="100000" User="bob" />]]>
      </Serialization>  
    </PrimaryObject> 
    <RelatedObjects>
      <RelatedObject objectType="vm" objectID="vm56"/>
      <RelatedObject objectType="service" objectID="lamp.211"/>
    </RelatedObjects>
    <Details>
    	<Detail name="alpha">lorem ipsum dolor sit amet</Detail>
    	<Detail name="bravo">2</Detail>
    	<Detail name="charlie">consectetur adipisicing elit, sed do</Detail>    		
    </Details>
  </Event>
  <Event eventTime="2012-01-27T15:18:31.000-07:00" eventType="schedcyclestart" eventCategory="start" sourceComponent="MWM" status="success" facility="scheduler" />
  <Event eventTime="2012-01-27T15:18:32.000-07:00" eventType="rmfailure" eventCategory="failure" sourceComponent="MWM" status="failure" facility="rm">
    <PrimaryObject objectType="rm" objectID="xcat" />
    <ErrorMessage originator="XCAT" errorCode="542">Cannot communicate with XCAT resource manager</ErrorMessage> 
  </Event>
</Events>

Sample Response

If the request was successful, the response will be an object with an id property containing the ID of the newly created events. On failure, the response is an error message.

[{"id":"4fadd83bc4aa366464599e1a"},{"id":"4fadd83bc4aa366464599e1b"},{"id":"4fadd83bc4aa366464599e1c"}]

Below is an example of events.log output for a successful event request:

2012-01-27T15:18:30.000-07:00 type="jobstart" category="start" sourceComponent="MWM" status="success" facility="job" initiatedBy.user="tomcat6" initiatedBy.proxyUser="bob" primaryObject.type="job" primaryObject.id="moab.849" relatedObject.0.type="service" relatedObject.0.id="lamp.211" relatedObject.1.type="vm" relatedObject.1.id="vm56" detail.alpha="lorem ipsum dolor sit amet" detail.bravo="2" detail.charlie="consectetur adipisicing elit, sed do" primaryObject.serialization="<job JobID=\"moab.849\" ReqAWDuration=\"100000\" User=\"bob\" />"
2012-01-27T15:18:31.000-07:00 type="schedcyclestart" category="start" sourceComponent="MWM" status="success" facility="scheduler"
2012-01-27T15:18:32.000-07:00 type="rmfailure" category="failure" sourceComponent="MWM" status="failure" facility="rm" primaryObject.type="rm" primaryObject.id="xcat" error.originator="XCAT" error.code="542" error.message="Cannot communicate with XCAT resource manager"

Note that " (double quote) characters in the input have been replaced by \" characters in the output. (For other character restrictions, see the "Restrictions" section below.)

Restrictions

Special characters, such as newline, carriage return, and " (double quote) are encoded in the output of events.log to make events.log easy to parse with scripts and third party tools. For example, if the input XML contains:

<ErrorMessage>RM says, "Cannot provision vm21"</ErrorMessage>

error.message="RM says, \"Cannot provision vm21\""

(For more information see escape sequences for Java Strings.)

Other restrictions include:

• Detail names can only contain alpha-numeric characters, colons (:), underscores (_), and dashes (-).
• primaryObject.serialization, error.message, and detail values (for example detail.someName="some value") can contain any printable ASCII character. Single quotes (') and double quotes (") cannot be contained in any other field.
• A single event cannot contain more than more than 50 details. If an event has more than 50 details, the excess details will be ignored.

4.6 Funds

The Fund API, FundBalance API, FundStatement API, and FundStatementSummary API contain the type and description of all fields in the Fund object as well as related objects and reports given in the URLs below.

Supported Methods

4.6.1 Getting Funds

Quick Reference

GET http://localhost/mws/rest/funds?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive][&query={"priority":"2"}][&sort={"id":-1}]
GET http://localhost/mws/rest/funds/<id>?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive]
GET http://localhost/mws/rest/funds/balances?proxy-user=<USER>[&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive]
GET http://localhost/mws/rest/funds/reports/statement?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>][&context=<CONTEXT>]
GET http://localhost/mws/rest/funds/reports/statement/summary?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>]

4.6.1.1 Get All Funds

URLs and Parameters

GET http://localhost/mws/rest/funds?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive][&query={"priority":"2"}][&sort={"id":-1}]

The query parameter does not support the full Mongo query syntax. Only querying for a simple, non-nested JSON object is allowed.

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": 2,
    "name": 1204,
    "allocations": [    {
      "id": 2,
      "startTime": "-infinity",
      "endTime": "2012-02-02 09:34:42 UTC",
      "amount": 9060000,
      "creditLimit": 0,
      "deposited": 9060000,
      "active": true,
      "description": ""
    }],
    "fundConstraints": [    {
      "id": 2,
      "name": "CostCenter",
      "value": 1204
    }]
  }]
}

4.6.1.2 Get Single Fund

URLs and Parameters

GET http://localhost/mws/rest/funds/<id>?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"account":"chemistry"}][&filter-type=NonExclusive]

See Global URL Parameters for available URL parameters.

Sample Responses

{
  "id": 2,
  "name": 1204,
  "priority": 0,
  "description": "R&D for Manufacturing",
  "creationTime": "2012-02-02 09:34:42 UTC",
  "amount": 9060000,
  "deposited": 9060000,
  "creditLimit": 0,
  "allocations": [  {
    "id": 2,
    "startTime": "-infinity",
    "endTime": "infinity",
    "amount": 9060000,
    "creditLimit": 0,
    "deposited": 9060000,
    "active": true,
    "description": ""
  }],
  "fundConstraints": [  {
    "id": 2,
    "name": "CostCenter",
    "value": 1204
  }]
}

4.6.1.3 Get All Fund Balances

URLs and Parameters

GET http://localhost/mws/rest/funds/balances?proxy-user=<USER>[&custom-fields=health][&filter={"project":"chemistry"}][&filter-type=NonExclusive]

See Global URL Parameters for available URL parameters.

Sample Response

The fund balances resource is an aggregation of fund data. See the FundBalance API page for more details.

{
  "totalCount": 2,
  "resultCount": 2,
  "results": [
    {
      "id": 2,
      "name": 1204,
      "priority": 0,
      "description": "R&D for Manufacturing",
      "creationTime": "2012-02-02 09:34:42 UTC",
      "amount": 9060000,
      "deposited": 9060000,
      "creditLimit": 0,
      "reserved": 0,
      "allocations": [
        {
          "id": 2,
          "amount": 9060000,
          "creditLimit": 0,
          "deposited": 9060000
        }
      ],
      "fundConstraints": [
        {
          "id": 2,
          "name": "CostCenter",
          "value": 1204
        }
      ],
      "balance": 9060000,
      "available": 9060000,
      "allocated": 9060000,
      "used": 0,
      "percentRemaining": 100,
      "percentUsed": 0
    },
    {
      "id": 5,
      "name": "",
      "priority": 0,
      "description": "",
      "creationTime": "2012-04-03 09:25:47 UTC",
      "amount": 901290219001,
      "deposited": 901290219021,
      "creditLimit": 30,
      "reserved": 84018308897.68,
      "allocations": [
        {
          "id": 6,
          "amount": 901290219001,
          "creditLimit": 30,
          "deposited": 901290219021
        }
      ],
      "fundConstraints": [],
      "balance": 817271910103.32,
      "available": 817271910133.32,
      "allocated": 901290219051,
      "used": 20,
      "percentRemaining": 100,
      "percentUsed": 0
    }
  ]
}

4.6.1.4 Get Fund Statement

URLs and Parameters

GET http://localhost/mws/rest/funds/reports/statement?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>][&context=<CONTEXT>]

The context parameter overrides the default context set for MAM using the mam.context configuration parameter. See the Configuration page for more information on this parameter.

See Global URL Parameters for available URL parameters.

Sample Response

The fund statement report provides a snapshot of the current funds. See the FundStatement API for more details.

{
  "startBalance":1234.01,
  "endBalance":1000
}

4.6.1.5 Get Fund Statement Summary

URLs and Parameters

GET http://localhost/mws/rest/funds/reports/statement/summary?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>]

See Global URL Parameters for available URL parameters.

Sample Response

The fund statement summary is slightly different from the typical fund statement in that the transactions are provided as summaries grouped by object and action. See the FundStatementSummary API for more details.

{
  "totalCredits":200.02,
  "totalDebits":-100,
  "transactions":[ {
      "action":"Deposit",
      "amount":200.02,
      "count":2
    }, {
      "action":"Charge",
      "amount":-100,
      "count":1
    }
  ]
}

4.7 Images

The Image API contains the type and description of all fields in the Image object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

4.7.1 Getting Images

Quick Reference

GET http://localhost/mws/rest/images[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/images/<id>
GET http://localhost/mws/rest/images/<name>

4.7.1.1 Get All Images

URLs and Parameters

GET http://localhost/mws/rest/images[?query={"field":"value"}&sort={"field":<1|-1>}]

It is possible to query images by one or more fields based on MongoDB query syntax.

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "4fa197e68ca30fc605dd1cf0",
    "name": "centos5-stateful"
  }]
}

Sorting and Querying

See the sorting and querying sections of Global URL Parameters.

4.7.1.2 Get Single Image

URLs and Parameters

GET http://localhost/mws/rest/images/<id>
GET http://localhost/mws/rest/images/<name>

See Global URL Parameters for available URL parameters.

You must specify either id or name, but you do not have to specify both.

Sample Response

Virtual machine image example:

{
  "active":true,
  "extensions":{
    "xcat":{
      "os":"centos",
      "architecture":"x86_64",
      "profile":"compute"
    }
  },
  "features":[],
  "hypervisor":false,
  "hypervisorType": null,
  "id":"4fa197e68ca30fc605dd1cf0",
  "name":"centos5-compute-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":false,
  "supportsVirtualMachine":true,
  "templateName":"",
  "type":"stateful",
  "version":0,
  "virtualizedImages":[]
}

Hypervisor image example:

{
  "active":true,
  "extensions":{
    "xcat":{
      "hvGroupName":"hvGroup",
      "vmGroupName":"vmGroup",
      "os":"esxi-4.1",
      "architecture":"x86_64",
      "profile":"hv"
    }
  },
  "features":[],
  "hypervisor":true,
  "hypervisorType":"ESX",
  "id":"4fa197e68ca30fc605dd1cf0",
  "name":"centos5-compute-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":true,
  "supportsVirtualMachine":false,
  "templateName":"",
  "type":"stateful",
  "version":0,
  "virtualizedImages":[]
}

The version field contains the current version of the database entry and does not reflect the version of the operating system. See Modify Image for more information.

4.7.2 Creating Images

Quick Reference

POST http://localhost/mws/rest/images

4.7.2.1 Create Single Image

URLs and Parameters

POST http://localhost/mws/rest/images

See Global URL Parameters for available URL parameters.

Request Body

Three fields are required to submit an image: name, hypervisor, and osType. Each image must also support provisioning to either a physical machine or a virtual machine by using the supportsPhysicalMachine or supportsVirtualMachine fields.

The name field must contain only letters, digits, periods, dashes, and underscores.

The array of virtualized images are themselves objects that contain image IDs or names. For more information on available fields and types, see the Image API.

The following is an example of the most basic image that can be created:

{
  "name": "centos5-stateful",
  "osType": "linux",
  "hypervisor": false,
  "supportsVirtualMachine":true
}

Note that this example does not provide any information for a provisioning manager (such as xCAT) to actually provision the machine. In order to provide this, you must add an entry to the extensions field that contains provisioning manager-specific information. Each key in the extensions field corresponds to the provisioning manager, and certain properties are required based on this key. For example, the xCAT extension key must be named xcat and must contain certain fields. These extension keys are documented in the Image API. See the following examples of creating images with xCAT-specific provisioning information below.

Sample Response

If the request was successful, the response body is the new image that was created exactly as shown in Get Single Image. On failure, the response is an error message.

Samples

The virtualizedImages field only accepts input when the image is a hypervisor and expects an array of image IDs or names, as shown in the following example:

{
  "hypervisor":true,
  "name":"esx5-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":true,
  "type":"stateful",
  "hypervisorType":"ESX",
  "virtualizedImages":   [
    {"id": "4fa197e68ca30fc605dd1cf0"},
    {"name": "centos5-stateful"}
  ]
}

The following example shows how to create an image that utilizes a cloned template for a virtual machine. (Note that the type must be set to linkedclone in order to set the templateName field.)

{
  "active": true,
  "hypervisor": false,
  "name": "centos5-compute-stateful",
  "osType": "linux",
  "type": "linkedclone",
  "supportsVirtualMachine":true,
  "templateName":"centos5-compute"
}

The following are samples of a virtual machine and a hypervisor image that can be provisioned with xCAT:

{
  "active": true,
  "features": [],
  "hypervisor": false,
  "name": "centos5-compute-stateful",
  "osType": "linux",
  "type": "stateful",
  "supportsVirtualMachine":true,
  "extensions": { 
     "xcat": { 
        "os": "centos",
        "architecture": "x86_64",
        "profile": "compute"
     }
  }
}

{
  "active": true,
  "features": [],
  "hypervisor": true,
  "name": "esxi5-base-stateless",
  "osType": "linux",
  "virtualizedImages":   [
    {"name": "centos5-compute-stateless"}
  ],
  "type": "stateless",
  "hypervisorType": "ESX",
  "supportsPhysicalMachine":true,
  "extensions": { 
     "xcat": { 
        "os": "esxi5",
        "architecture": "x86_64",
        "profile": "base",
        "hvType": "esx",
        "hvGroupName": "esx5hv",
        "vmGroupName": "esx5vm"
     }
  }
}

4.7.3 Modifying Images

Quick Reference

PUT http://localhost/mws/rest/images/<id>
PUT http://localhost/mws/rest/images/<name>

4.7.3.1 Modify Single Image

URLs and Parameters

PUT http://localhost/mws/rest/images/<id>
PUT http://localhost/mws/rest/images/<name>

See Global URL Parameters for available URL parameters.

• You must specify either id or name, but you do not have to specify both.
• The name field must contain only letters, digits, periods, dashes, and underscores.

Example Request

{
  "name": "centos5-stateful",
  "type": "stateful",
  "hypervisor": false,
  "osType": "linux",
  "virtualizedImages": []
}

The version field contains the current version of the database entry and does not reflect the version of the operating system. This field cannot be updated directly. However, if version is included in the modify request, it will be used to verify that another client did not update the object in between the time the data was retrieved and the modify request was delivered.

Sample Response

If the request was successful, the response body is the modified image as shown in Get Single Image. On failure, the response is an error message.

4.7.4 Deleting Images

Quick Reference

DELETE http://localhost/mws/rest/images/<id>
DELETE http://localhost/mws/rest/images/<name>

4.7.4.1 Delete Single Image

URLs and Parameters

DELETE http://localhost/mws/rest/images/<id>
DELETE http://localhost/mws/rest/images/<name>

See Global URL Parameters for available URL parameters.

Only one of id or name are required.

Sample Response

{}

4.8 Jobs

The Job API has changed with API version 2. The supported methods table below requires each resource to be accessed with a URL parameter of api-version=2 in order to behave as documented.

In order to access documentation for previous API versions, see Requesting Specific API Versions.

The Job API contains the type and description of all fields in the Job object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

4.8.1 Getting Job Information

Quick Reference

GET http://localhost/mws/rest/jobs/<name>?api-version=2

4.8.1.1 Get All Jobs

URLs and Parameters

GET http://localhost/mws/rest/jobs?api-version=2

It is possible to query by one or more fields based on MongoDB query syntax.

See Global URL Parameters for available URL parameters.

How to Get All Jobs

{
  "totalCount": 8,
  "resultCount": 3,
  "results":   [
        {
      "flags": ["GLOBALQUEUE"],
      "name": "Moab.1"
    },
        {
      "flags": ["GLOBALQUEUE"],
      "name": "Moab.2"
    },
        {
      "flags": ["GLOBALQUEUE"],
      "name": "Moab.4"
    }
  ]
}

How to Get a Subset of Jobs

Here are a few examples of how to query for jobs.

http://localhost/mws/rest/jobs?api-version=2&query={"isActive":true}

http://localhost/mws/rest/jobs?api-version=2&query={"isActive":false}

http://localhost/mws/rest/jobs?api-version=2&query={"credentials.user":"fred"}

Known Issues

• Some jobs are not returned if DisplayFlags UseBlocking is set in the moab.cfg file.

4.8.1.2 Get Single Job

URLs and Parameters

GET http://localhost/mws/rest/jobs/<name>?api-version=2

See Global URL Parameters for available URL parameters.

Sample Response

{
  "arrayIndex": null,
  "arrayMasterName": null,
  "attributes": [],
  "blocks": [  {
    "category": "jobBlock",
    "message": null,
    "type": null
  }],
  "bypassCount": 0,
  "cancelCount": 0,
  "commandFile": "/tmp/test.sh",
  "commandLineArgs": null,
  "completionCode": null,
  "cpuTime": 0,
  "credentials":   {
    "account": null,
    "group": "adaptive",
    "jobClass": null,
    "qos": "NONE",
    "qosRequested": null,
    "user": "adaptive"
  },
  "customName": null,
  "dates":   {
    "completedDate": null,
    "createdDate": "2012-10-11 17:58:16 UTC",
    "deadlineDate": "2037-10-24 12:26:40 UTC",
    "dispatchedDate": null,
    "earliestRequestedStartDate": null,
    "earliestStartDate": "2012-10-11 17:58:18 UTC",
    "eligibleDate": "2012-10-11 17:59:19 UTC",
    "lastCanceledDate": null,
    "lastChargedDate": null,
    "lastPreemptedDate": null,
    "lastUpdatedDate": "2012-10-11 17:59:19 UTC",
    "startDate": null,
    "submitDate": "2012-10-11 17:58:16 UTC",
    "terminationDate": "2037-10-24 12:26:40 UTC"
  },
  "deferCount": 0,
  "dependencies": [],
  "description": null,
  "duration": 8639999,
  "durationActive": 0,
  "durationQueued": 31,
  "durationRemaining": 0,
  "durationSuspended": 0,
  "emailNotifyAddresses": [],
  "emailNotifyTypes": [],
  "environmentRequested": false,
  "environmentVariables": {},
  "epilogScript": null,
  "flags": ["GLOBALQUEUE"],
  "holdDate": null,
  "holdReason": null,
  "holds": [],
  "initialWorkingDirectory": "/tmp",
  "isActive": true,
  "jobGroup": null,
  "masterNode": null,
  "memorySecondsDedicated": 0,
  "memorySecondsUtilized": 0,
  "messages": [],
  "migrateCount": 0,
  "minimumPreemptTime": 0,
  "mwmName": "Moab",
  "name": "Moab.15",
  "nodesExcluded": [],
  "nodesRequested": [],
  "nodesRequestedPolicy": null,
  "partitionAccessList":   [
    "msm",
    "SHARED"
  ],
  "partitionAccessListRequested":   [
    "msm",
    "SHARED"
  ],
  "preemptCount": 0,
  "priorities":   {
    "run": 0,
    "start": 1,
    "system": 0,
    "user": 0
  },
  "processorSecondsDedicated": 0,
  "processorSecondsLimit": 0,
  "processorSecondsUtilized": 0,
  "prologScript": null,
  "queueStatus": "blocked",
  "rejectPolicies": [],
  "requirements": [  {
    "architecture": null,
    "attributes": [],
    "features": [],
    "index": 0,
    "featuresRequested": [],
    "featuresRequestedMode": "AND",
    "featuresExcluded": [],
    "featuresExcludedMode": "AND",
    "metrics": {},
    "nodeAccessPolicy": null,
    "nodeAllocationPolicy": null,
    "nodeCount": 0,
    "nodes": [],
    "nodeSet": null,
    "image": null,
    "reservation": null,
    "resourcesPerTask":     {
      "processors":       {
        "dedicated": 1,
        "utilized": 0
      },
      "memory":       {
        "dedicated": 0,
        "utilized": 0
      },
      "disk":       {
        "dedicated": 0,
        "utilized": null
      },
      "swap":       {
        "dedicated": 0,
        "utilized": null
      }
    },
    "taskCount": 4,
    "tasksPerNode": 0
  }],
  "reservationRequested": null,
  "resourceFailPolicy": null,
  "resourceManagerExtension": null,
  "resourceManagers": [  {
    "isDestination": false,
    "isSource": true,
    "jobName": "Moab.15",
    "name": "internal"
  }],
  "rmStandardErrorFilePath": null,
  "rmStandardOutputFilePath": null,
  "standardErrorFilePath": null,
  "standardOutputFilePath": null,
  "startCount": 0,
  "states":   {
    "state": "Idle",
    "stateExpected": "Idle",
    "stateLastUpdatedDate": null,
    "subState": null
  },
  "submitHost": "0:0:0:0:0:0:0:1",
  "systemJobAction": null,
  "systemJobType": null,
  "targetedJobAction": null,
  "targetedJobName": null,
  "templates": [{"name": "DEFAULT"}],
  "triggers": [],
  "variables": {},
  "virtualContainers": [],
  "virtualMachines": [],
  "vmUsagePolicy": null
}

Job Arrays

If a job is the master of a job array, the response will have some additional fields set as shown in the following example. The name field is chosen by the Moab Workload Manager, and the customName field comes from the job array name field.

{
  "name": "Moab.5",
  "customName": "myarray",
  "flags":   [
    "ARRAYMASTER",
    "GLOBALQUEUE",
    "CANCELONFIRSTFAILURE",
    "CANCELONANYSUCCESS"
  ]
}

If a job is a sub-job of an array, the response will have other fields set as shown in the following example.

{
  "name": "Moab.5[21]",
  "customName": "myarray",
  "arrayIndex": 21,
  "arrayMasterName": "Moab.5",
  "flags":   [
    "ARRAYJOB",
    "GLOBALQUEUE",
    "CANCELONFIRSTFAILURE",
    "CANCELONANYSUCCESS"
  ]
}

4.8.2 Submitting Jobs

Quick Reference

POST http://localhost/mws/rest/jobs?api-version=2[&proxy-user=<username>]

Restrictions

• MWS must have read access to the file given in commandFile.
• No more than one virtual container can be specified in the request. The virtual container must already exist.
• The credentials.user and credentials.group properties are used to submit a job as the specified user belonging to the specified group.
• Job variables have the following restrictions:
• Variable names cannot contain equals (=), semicolon (;), colon (:), plus (+), question mark (?), caret (^), backslash (\), or white space.
• Variable values cannot contain semicolon (;), colon (:), plus (+), or caret (^).
• When submitting jobs, the only supported hold type is User.
• The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.8.2.1 Submit Job

URLs and Parameters

POST http://localhost/mws/rest/jobs?api-version=2[&proxy-user=<username>]

See Global URL Parameters for available URL parameters.

Request Body

To submit a job, only one field is required: commandFile.

The request body below shows all the fields that are available during job submission. This is a very contrived example; its purpose is simply to show sample values in the correct format.

{
  "attributes":   [
    "attr1",
    "attr2"
  ],
  "commandFile": "/tmp/test.sh",
  "commandLineArguments": "-x -v",
  "credentials":   {
    "account": "account",
    "group": "group",
    "jobClass": "BATCH",
    "qosRequested": "QOS1",
    "user": "saadmin"
  },
  "customName": "custom name for job",
  "dates":   {
    "earliestRequestedStartDate": "2012-11-08 13:18:47 UTC",
    "deadlineDate": "2014-02-17 14:00:00 UTC"
  },
  "dependencies":   [
        {
      "type": "set",
      "name": "vc1.varA"
    },
        {
      "type": "set",
      "name": "vc2.varB"
    },
        {
      "type": "set",
      "name": "vc3.varC"
    }
  ],
  "duration": 600,
  "emailNotifyAddresses":   [
    "[email protected]",
    "[email protected]"
  ],
  "emailNotifyTypes":   [
    "JobStart",
    "JobEnd"
  ],
  "environmentRequested": true,
  "environmentVariables":   {
    "var1": "val1",
    "var2": "val2"
  },
  "epilogScript": "/tmp/epilog.sh",
  "flags":   [
    "RESTARTABLE",
    "SUSPENDABLE"
  ],
  "holds": ["User"],
  "initialWorkingDirectory": "/tmp",
  "jobGroup": "job_group",
  "nodesExcluded":   [
    {"name": "node07"},
    {"name": "node08"}
  ],
  "nodesRequested":   [
    {"name": "node01"},
    {"name": "node02"}
  ],
  "nodesRequestedPolicy": "SUBSET",
  "partitionAccessListRequested":   [
    "p1",
    "p2"
  ],
  "priorities": {"user": 5},
  "prologScript": "/tmp/prolog.sh",
  "requirements": [  {
    "architecture": "x86_64",
    "attributes":     [
            {
        "name": "matlab",
        "comparator": "<=",
        "value": "7.1"
      },
            {
        "name": "soffice",
        "comparator": "=",
        "value": "3.1"
      }
    ],
    "featuresRequested":     [
      "a",
      "b",
      "c"
    ],
    "featuresRequestedMode": "OR",
    "featuresExcluded":     [
      "d",
      "e",
      "f"
    ],
    "featuresExcludedMode": "AND",
    "nodeAccessPolicy": "SINGLEJOB",
    "nodeAllocationPolicy": "PRIORITY",
    "nodeCount": 6,
    "image": "linux",
    "resourcesPerTask":     {
      "disk": {"dedicated": 1024},
      "memory": {"dedicated": 512},
      "processors": {"dedicated": 2},
      "swap": {"dedicated": 4096},
      "matlab": {"dedicated": 6},
      "intellij": {"dedicated": 2}
    },
    "taskCount": 4,
    "tasksPerNode": 14
  }],
  "reservationRequested": {"name": "rsv.1"},
  "resourceFailPolicy": "RETRY",
  "resourceManagerExtension": "x=PROC=4",
  "standardErrorFilePath": "/tmp/error",
  "standardOutputFilePath": "/tmp/out",
  "submitHost": "admin-node",
  "templates":   [
    {"name": "template1"},
    {"name": "template2"}
  ],
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  },
  "virtualContainers": [{"name": "vc1"}],
  "vmUsagePolicy": "CREATEVM"
}

Sample Response

The response of this task is one of three possibilities:

• An object with a single messages property containing a list of error messages on failure

{"messages":["Could not create job - invalid requirements"]}

• An object with a name property containing the name of the newly created job

{"name":"Moab.1"}

• An object with a name property and a virtualContainers list containing the name of the newly created virtual container

{ "name": "Moab.1", "virtualContainers": [{"name": "vc1"}] }

The virtual container will only be reported when a new virtual container has been created by Moab for the job.

4.8.2.2 Examples of Job Submission

Submit job to run on node2 and node3

{
  "commandFile": "/tmp/test.sh",
  "credentials":   {
    "group": "adaptive",
    "user": "adaptive"
  },
  "initialWorkingDirectory": "/tmp",
  "nodesRequested":   [
    {"name": "node2"},
    {"name": "node3"}
  ]
}

Submit job that requires 20 processors

{
  "commandFile": "/tmp/test.sh",
  "credentials":   {
    "group": "adaptive",
    "user": "adaptive"
  },
  "initialWorkingDirectory": "/tmp",
  "requirements": [{"taskCount": 20}]
}

Submit job to run after a certain time

{
  "commandFile": "/tmp/test.sh",
  "credentials":   {
    "group": "adaptive",
    "user": "adaptive"
  },
  "dates": {"earliestRequestedStartDate": "2012-10-11 18:36:35 UTC"},
  "initialWorkingDirectory": "/tmp",
  "requirements": [{"taskCount": 20}]
}

Submit job based on msub example

Given this msub command:

msub -l nodes=3:ppn=2,walltime=1:00:00,pmem=100 script2.pbs.cmd

Here is an equivalent MWS request:

{
  "duration": 3600,
  "commandFile": "/home/adaptive/script2.pbs.cmd",
  "credentials":   {
    "group": "adaptive",
    "user": "adaptive"
  },
  "initialWorkingDirectory": "/home/adaptive",
  "requirements": [  {
    "resourcesPerTask": {"memory": {"dedicated": 100}},
    "taskCount": 6,
    "tasksPerNode": 2
  }]
}

• To emulate what msub does, make commandFile an absolute path, and add credentials.user, credentials.group, and initialWorkingDirectory.
• As shown above, nodes=3:ppn=2 is equivalent to setting taskCount to 6 and tasksPerNode to 2.

Submit a Job Array

See the Submitting Job Arrays section for details on how to submit a job array.

4.8.3 Modifying Jobs

Quick Reference

PUT http://localhost/mws/rest/jobs/<name>[/<modifyAction>]?api-version=2[&proxy-user=<username>]

Restrictions

• The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.8.3.1 Modify Job Attributes

URLs and Parameters

PUT http://localhost/mws/rest/jobs/<name>?api-version=2[&proxy-user=<username>]

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when modifying a Job, along with some sample values.

{
  "credentials":   {
    "account": "account",
    "jobClass": "BATCH",
    "qosRequested": "QOS1"
  },
  "customName": "custom name for job",
  "dates": {"earliestRequestedStartDate": "2012-11-08 13:18:47 UTC"},
  "duration": 600,
  "flags":   [
    "RESTARTABLE",
    "SUSPENDABLE"
  ],
  "holds": ["User"],
  "messages":   [
    {"message": "Message one"},
    {"message": "Message two"}
  ],
  "partitionAccessListRequested":   [
    "p1",
    "p2"
  ],
  "priorities": {"user": 5},
  "reservationRequested": {"name": "rsv.1"},
  "variables":   {
    "var1": "val1",
    "var2": "val2"
  }
}

Sample Response

These messages may not match the messages returned from Moab exactly, but are given as an example of the structure of the response.

Not all messages are shown for the above request body.

{"messages": [
  "Account modified successfully",
  "Messages modified successfully",
  "Variables modified successfully"
]}

Restrictions

• Old messages are not removed from jobs; only new messages are added.
• Job variables have the restrictions documented in Submitting Jobs

4.8.3.2 Perform Actions on Job

URLs and Parameters

PUT http://localhost/mws/rest/jobs/<name>/<modifyAction>?api-version=2[&proxy-user=<username>]

Performing a cancel function on a job is equivalent to deleting a job.

See Global URL Parameters for available URL parameters.

Request Body

Request bodies are only required for holding or unholding jobs. All other actions do not require request bodies of any kind.

{"holds": ["User"]}

{"holds": ["User"]}

If no holds are specified when unholding a job, all holds will be removed. This is equivalent to specifying holds as a list with a single element of All.

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

{"messages": ["Job modified successfully"]}

4.8.4 Deleting (Canceling) Jobs

Quick Reference

DELETE http://localhost/mws/rest/jobs/<name>?api-version=2[&proxy-user=<username>]

Restrictions

• The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.8.4.1 Cancel Job

URLs and Parameters

DELETE http://localhost/mws/rest/jobs/<name>?api-version=2[&proxy-user=<username>]

See Global URL Parameters for available URL parameters.

Sample Response

{}

Additional information about the DELETE can be found in the HTTP response header X-MWS-Message.

4.9 Job Arrays

The JobArray API contains the type and description of all fields in the Job Array object.

Supported Methods

4.9.1 Submitting Job Arrays

Quick Reference

POST http://localhost/mws/rest/job-arrays?api-version=2[&proxy-user=<username>]

While the Job Array resource only gives access to create job arrays, job arrays are retrieved using the operations in the Getting Job Information section.

Restrictions

All restrictions present for Submitting Jobs are present for job arrays. In addition, job arrays are only supported if the ENABLEJOBARRAYS parameter is set to TRUE in the moab.cfg file. Example:

ENABLEJOBARRAYS 	TRUE

4.9.1.1 Submit Job Array

URLs and Parameters

POST http://localhost/mws/rest/job-arrays?api-version=2[&proxy-user=<username>]

See Global URL Parameters for available URL parameters.

Request Body

To submit a job array, only two fields are required: jobPrototype and one of indexValues or indexRanges. Both index ranges and values may be specified if desired.

The request body below shows all the fields that are available during job array submission, although the jobPrototype shown is a simple example and does not utilize all fields of a job submission.

The jobPrototype field has the same properties as a typical job submission. Examples of this can be seen in the Submitting Jobs section.

{
  "name": "myarray",
  "indexRanges": [  {
    "startIndex": 11,
    "endIndex": 25,
    "increment": 2
  }],
  "indexValues":   [ 2, 4, 6, 8, 10 ],
  "slotLimit": 2,
  "cancellationPolicy":   {
    "firstJob": "FAILURE",
    "anyJob": "SUCCESS"
  },
  "jobPrototype":   {
    "commandFile": "/tmp/test.sh",
    "initialWorkingDirectory": "/tmp",
    "requirements": [{"taskCount": 4}]
  }
}

Sample Response

The response of this task is the same as submitting a job.

4.10 Job Templates

The Job Template API contains the type and description of all fields in the Job Template object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

4.10.1 Getting Job Templates

Quick Reference

GET http://localhost/mws/rest/job-templates/<id>

4.10.1.1 Get All Job Templates

URLs and Parameters

GET http://localhost/mws/rest/job-templates

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 14,
  "resultCount": 14,
  "results":   [
    {"id": "DEFAULT"},
    {"id": "genericVM"},
    {"id": "genericVM-setup"},
    {"id": "genericVM-destroy"},
    {"id": "genericVM-migrate"},
    {"id": "genericPM"},
    {"id": "genericPM-setup"},
    {"id": "genericPM-destroy"},
    {"id": "OSStorage"},
    {"id": "OSStorage-setup"},
    {"id": "OSStorage-destroy"},
    {"id": "extraStorage"},
    {"id": "extraStorage-setup"},
    {"id": "extraStorage-destroy"}
  ]
}

4.10.1.2 Get Single Job Template

URLs and Parameters

GET http://localhost/mws/rest/job-templates/<id>

See Global URL Parameters for available URL parameters.

Sample Response

{
  "account": "account",
  "args": "arg1 arg2",
  "commandFile": "/tmp/script",
  "description": "description",
  "genericSystemJob": true,
  "id": "genericVM",
  "inheritResources": false,
  "jobDependencies": [  {
    "name": "genericVM-setup",
    "type": "JOBSUCCESSFULCOMPLETE"
  }],
  "jobFlags": ["VMTRACKING"],
  "jobTemplateFlags": ["SELECT"],
  "jobTemplateRequirements": [  {
    "architecture": "x86_64",
    "diskRequirement": 500,
    "genericResources": {"tape": 3},
    "nodeAccessPolicy": "SINGLEJOB",
    "operatingSystem": "Ubuntu 10.04.3",
    "requiredDiskPerTask": 200,
    "requiredFeatures": ["dvd"],
    "requiredMemoryPerTask": 1024,
    "requiredProcessorsPerTask": 2,
    "requiredSwapPerTask": 512,
    "taskCount": 4
  }],
  "priority": 20,
  "qos": "qos",
  "queue": "queue",
  "durationRequested": 600,
  "select": true,
  "trigger": null,
  "version": 0,
  "vmUsagePolicy": "REQUIREPM"
}

4.11 Metric Types

The MetricType API contains the type and description of all fields in the Metric Type object.

Supported Methods

4.11.1 Getting Metric Types

Quick Reference

GET http://localhost/mws/rest/metric-types

4.11.1.1 Get All Metric Types

URLs and Parameters

GET http://localhost/mws/rest/metric-types

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 9,
  "resultCount": 9,
  "results":   [
    {"id": "vmcount"},
    {"id": "watts"},
    {"id": "pwatts"},
    {"id": "temp"},
    {"id": "cpu"},
    {"id": "mem"},
    {"id": "io"},
    {"id": "ccores"},
    {"id": "threads"}
  ]
}

4.12 Nodes

The Node API has changed with API version 2. The supported methods table below requires each resource to be accessed with a URL parameter of api-version=2 in order to behave as documented.

In order to access documentation for previous API versions, see Requesting Specific API Versions.

The Node API contains the type and description of all fields in the Node object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

4.12.1 Getting Nodes

Quick Reference

GET http://localhost/mws/rest/nodes/<name>?api-version=2

4.12.1.1 Get All Nodes

URLs and Parameters

GET http://localhost/mws/rest/nodes?api-version=2

It is possible to query by one or more fields based on MongoDB query syntax.

See Global URL Parameters for available URL parameters.

This query will not return the DEFAULT or GLOBAL nodes from Moab Workload Manager. However, the Get Single Node task may be used to retrieve them individually if desired.

Sample Response

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"name": "node1"},
    {"name": "node2"},
    {"name": "node3"}
  ]
}

4.12.1.2 Get Single Node

URLs and Parameters

GET http://localhost/mws/rest/nodes/<name>?api-version=2

See Global URL Parameters for available URL parameters.

Sample Response

{
  "name": "hv2",
  "architecture": null,
  "classes": ["class1"],
  "featuresReported": [],
  "index": 2,
  "ipAddress": "10.0.0.4",
  "isHypervisor": true,
  "lastUpdatedDate": "2012-10-11 17:42:24 UTC",
  "migrationDisabled": false,
  "partition": "msm",
  "processorSpeed": null,
  "profilingEnabled": false,
  "rack": null,
  "slot": null,
  "type": "compute",
  "messages": [  {
    "count": 11,
    "createdDate": "2012-10-24 04:06:04 UTC",
    "expireDate": "2037-10-24 12:26:40 UTC",
    "message": "This is a message"
  }],
  "metrics":   {
    "watts": 200,
    "pwatts": 200,
    "temp": 103,
    "vmcount": 4
  },
  "variables": {},
  "states":   {
    "powerState": "On",
    "powerStateExpected": null,
    "state": "Idle",
    "stateExpected": "Idle",
    "stateLastUpdatedDate": "2012-10-11 17:15:01 UTC",
    "subState": null,
    "subStateLast": null,
    "subStateLastUpdatedDate": null
  },
  "operatingSystem":   {
    "hypervisorType": "KVM",
    "image": "hyper",
    "imageExpected": null,
    "imageLastUpdatedDate": null,
    "imagesAvailable": ["hyper"],
    "virtualMachineImages":     [
      "stateless1",
      "stateless2"
    ]
  },
  "resources":   {
    "processors":     {
      "configured": 8,
      "real": 8,
      "dedicated": 0,
      "available": 8,
      "utilized": -1
    },
    "memory":     {
      "configured": 1048576,
      "real": 1048576,
      "dedicated": 0,
      "available": 1048576,
      "utilized": 0
    },
    "disk":     {
      "configured": 1048576,
      "real": 1048576,
      "dedicated": 0,
      "available": 1048576,
      "utilized": 0
    },
    "swap":     {
      "configured": 4096,
      "real": 4096,
      "dedicated": 0,
      "available": 4096,
      "utilized": 0
    }
  },
  "resourceManagers": [  {
    "name": "msm",
    "isMaster": true,
    "stateReported": "Active"
  }],
  "jobs": [],
  "reservations":   [
        {
      "name": "system.5",
      "type": "user"
    },
        {
      "name": "system.17",
      "type": "user"
    }
  ],
  "virtualContainers": [],
  "virtualMachines":   [
    {"name": "vm3"},
    {"name": "vm4"}
  ],
  "triggers": []
}

4.12.2 Modifying Nodes

Quick Reference

PUT http://localhost/mws/rest/nodes/<name>?api-version=2[&proxy-user=<username>]

Restrictions

• The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

4.12.2.1 Modify Node

URLs and Parameters

PUT http://localhost/mws/rest/nodes/<name>?api-version=2[&proxy-user=<username>]

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when modifying a Node, along with some sample values.

{
  "messages":   [
    {"message": "Message one"},
    {"message": "Message two"}
  ],
  "metrics": {"pwatts": 211},
  "operatingSystem": {"image": "esx4.1"},
  "partition": "part1",
  "states":   {
    "powerState": "On",
    "state": "Running"
  },
  "variables":   {
    "key": "value",
    "arbitrary text key": "more value"
  }
}

Sample Response

This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.

{"messages":[
  "Successfully modified os to 'linux'",
  "Successfully powered node off"
]}

4.13 Pending Actions

The Pending Action API contains the type and description of all fields in the Pending Action object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

4.13.1 Getting Pending Actions

Quick Reference

GET http://localhost/mws/rest/pending-actions

4.13.1.1 Get All Pending Actions

URLs and Parameters

GET http://localhost/mws/rest/pending-actions

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "failureDetails": "",
    "hosts": ["hv3"],
    "id": "vmcreate-27",
    "maxDurationInSeconds": 3600,
    "migrationDestination": "",
    "migrationSource": "",
    "motivation": "requested by root",
    "pendingActionState": "RUNNING",
    "pendingActionType": "VMCREATE",
    "requester": "root",
    "serviceId": "Rhel55Vm.200",
    "startTime": "2011-11-15 21:57:55 UTC",
    "substate": "installing",
    "targetOS": "",
    "topLevelServiceId": "Lamp.132",
    "vmId": "vm8"
  }]
}

Generic vs Non-Generic Types

If generic job templates are used in Moab, MWS may be configured to translate pending actions with the generic type to the proper type such as VMCREATE. This is done in the configuration file. The Quickstart Guide provides the default mappings for this feature, as well as an example of adding a custom mapping from a custom template name to the correct type.

The default mappings are shown in the table below. The available pending action types may be seen on the PendingActionType API page.

When generic mappings are used, MWS will match the first template mapping that the pending action ID ends with. For example, an ID of Moab.1.genericVM-setup will map the type to VMCREATE.

To enable mapping for a custom template name such as myCustomVM-setup, simply add the following line to the MWS configuration file. The value of the pending action type is case insensitive.

mws.pendingActions.mappings["myCustomVM-setup"] = "vmcreate"

MWS also provides the ability to enable or disable the display of generic pending actions (or those pending actions that are not mapped). This behavior is controlled by the mws.pendingActions.displayGeneric setting as shown below. A false value will prevent generic pending actions from being displayed, while a true value will display all pending actions. By default this value is true.

mws.pendingActions.displayGeneric = false

4.14 Permissions

The Permission API contains the type and description of fields that all Permissions have in common.

Supported Methods

4.14.1 Getting Permissions

Quick Reference

GET http://localhost/mws/rest/permissions
GET http://localhost/mws/rest/permissions/<id>

4.14.1.1 Get All Permissions

URLs and Parameters

GET http://localhost/mws/rest/permissions[?query={"field":"value"}&sort={"field":<1|-1>}]

It is possible to query permissions by one or more fields based on MongoDB query syntax.

See Global URL Parameters for available URL parameters.

Sample Response

{
	"totalCount": 1,
	"resultCount": 1,
	"results": [{
		"resource" : "chart",
		"action" : "read",
		"description" : "The permission to view all charts."
		} ]
}

Sorting and Querying

See the sorting and querying sections of Global URL Parameters.

4.14.1.2 Get a User's Permissions

URLs and Parameters

GET http://localhost/mws/rest/permissions/users/<name>

See Global URL Parameters for available URL parameters.

Sample Response

[
	  {
	  "action": "read",
	  "description": "The permission to read all charts",
	  "id": "5033b842e4b09cc61bedb818",
	  "label": "",
	  "resource": "chart",
	  "resourceFilter": null,
	  "type": "custom",
	  "version": 1
	},
	  {
	  "action": "read",
	  "description": "The permission to read all pages",
	  "id": "5033b8a5e4b09cc61bedb82d",
	  "label": "",
	  "resource": "page",
	  "resourceFilter": null,
	  "type": "custom",
	  "version": 1
	},
	  {
	  "action": "update",
	  "description": "The permission to update all pages",
	  "id": "5033b8a5e4b09cc61bedb82f",
	  "label": "",
	  "resource": "page",
	  "resourceFilter": null,
	  "type": "custom",
	  "version": 1
	}
]

4.14.1.3 Get Single Permission

URLs and Parameters

GET http://localhost/mws/rest/permissions/<id>

See Global URL Parameters for available URL parameters.

Sample Response

{
	"action" : "create",
	"description" : "The permission to create all charts.",
	"id" : "50296335e4b0011b0f8394ec",
	"label" : "Create Chart",
	"resource" : "chart",
	"resourceFilter" : null,
	"type" : "custom",
	"version" : 0
}

4.14.2 Creating Permissions

Quick Reference

POST http://localhost/mws/rest/permissions

4.14.2.1 Create Single Permission

URLs and Parameters

POST http://localhost/mws/rest/permissions

See Global URL Parameters for available URL parameters.

Request Body

• The resource, action, and type are required on each Permission.
• Api permissions are permissions with the type 'api' and are the only permissions enforced by MWS.
• Api permissions must map to a valid resource. For example 'services' is valid because there is a resource /mws/rest/services.
• Api permissions must have create, read, update, or delete as the action.

The following is an example request body to create a permission:

{
			"resource" : "Chart",
			"action" : "read",
			"type" : "custom",
			"label" : "Read all charts",
			"description" : "The permissions to view all charts."
}

Sample Response

If the request was successful, the response body is the new permission that was created exactly as shown in Get Single Permission. On failure, the response is an error message.

4.14.3 Deleting Permissions

Quick Reference

DELETE http://localhost/mws/rest/permissions/<id>

4.14.3.1 Delete Single Permission

URLs and Parameters

DELETE http://localhost/mws/rest/permission/<id>

See Global URL Parameters for available URL parameters.

Sample Response

{}

4.15 Plugins

The PluginInstance API page contains the type and description of all fields in the Plugin object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

4.15.1 Getting Plugins

Quick Reference

GET http://localhost/mws/rest/plugins
GET http://localhost/mws/rest/plugins/<id>

4.15.1.1 Get All Plugins

URLs and Parameters

GET http://localhost/mws/rest/plugins

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"id": "plugin1"},
    {"id": "plugin2"},
    {"id": "plugin3"}
  ]
}

4.15.1.2 Get Single Plugin

URLs and Parameters

GET http://localhost/mws/rest/plugins/<id>

See Global URL Parameters for available URL parameters.

Sample Response

{
  "id":"plugin1",
  "pluginType":"Native",
  "pollInterval":30,
  "autoStart":true,
  "config":{
    "getJobs":"exec:///opt/moab/tools/workload.query.pl"
  },
  "state":"STARTED",
  "nextPollDate":"2011-12-02 17:28:52 UTC",
  "lastPollDate":"2011-12-02 17:28:22 UTC"
}

4.15.2 Creating Plugins

Quick Reference

POST http://localhost/mws/rest/plugins

4.15.2.1 Create Plugin

URLs and Parameters

POST http://localhost/mws/rest/plugins

See Global URL Parameters for available URL parameters.

Request Body

When creating a plugin, the id and pluginType fields are required. The request body below shows all fields that are available when creating a Plugin, along with some sample values.

{
  "id":"plugin1",
  "pluginType":"Native",
  "pollInterval":30,
  "autoStart":true,
  "config":{
    "getJobs":"exec:///opt/moab/tools/workload.query.pl"
  }
}

Sample Response

{"id": "plugin1"}

Restrictions

While it is possible to create a plugin with arbitrary nested configuration, such as:

…
"config":{
  "nestedObject":{
    "property1":"value1",
    "property2":"value2"
  },
  "nestedList:["listItem1", "listItem2"]
}

It is not recommended as the user interface does not support editing or viewing any configuration data values other than strings.

4.15.3 Modifying Plugins

Quick Reference

PUT http://localhost/mws/rest/plugins/<id>
POST http://localhost/mws/rest/plugins/<id>/poll

4.15.3.1 Modify Plugin

URLs and Parameters

PUT http://localhost/mws/rest/plugins/<id>

See Global URL Parameters for available URL parameters.

Request Body

The request body below shows all the fields that are available when modifying a Plugin, along with some sample values.

{
  "state":"STARTED",
  "pollInterval":30,
  "autoStart":true,
  "config":{
    "getJobs":"exec:///opt/moab/tools/workload.query.pl"
  },
  "state":"STARTED"
}

Sample Response

{"messages":["Plugin plugin1 updated", "Started Plugin 'plugin1'"]}

4.15.3.2 Trigger Plugin Poll

URLs and Parameters

POST http://localhost/mws/rest/plugins/<id>/poll

See Global URL Parameters for available URL parameters.

Trigger Poll

This resource call will trigger an immediate poll of the specified plugin. It is equivalent to the same operation on the Monitoring and Lifecycle Controls page.

Request Body

No request body is required.

Sample Response

{"messages":["Polled Plugin with ID 'myPlugin'"]}

4.15.4 Deleting Plugins

Quick Reference

DELETE http://localhost/mws/rest/plugins/<id>

4.15.4.1 Delete Plugin

URLs and Parameters

DELETE http://localhost/mws/rest/plugins/<id>

See Global URL Parameters for available URL parameters.

Sample Response

{}

Additional information about a successful DELETE can be found in the HTTP response header X-MWS-Message.

{"messages":["Plugin plugin1 could not be deleted", "Error message describing the problem"]}

4.15.5 Accessing Plugin Web Services

Quick Reference

GET http://localhost/mws/rest/plugins/<id>/services/<serviceName>
POST http://localhost/mws/rest/plugins/<id>/services/<serviceName>
PUT http://localhost/mws/rest/plugins/<id>/services/<serviceName>
DELETE http://localhost/mws/rest/plugins/<id>/services/<serviceName>

4.15.5.1 Access a Plugin Web Service

URLs and Parameters

GET http://localhost/mws/rest/plugins/<id>/services/<serviceName>
POST http://localhost/mws/rest/plugins/<id>/services/<serviceName>

See Global URL Parameters for available URL parameters.

Web Service IDs

Translation is done to map CamelCase web service names to hyphenated names in the URL. For example, a web service method named notifyEvent on a plugin with a name of notifications may be called with the following URLs:

// CamelCase
/rest/plugins/notifications/services/notifyEvent
// Hyphenated
/rest/plugins/notifications/services/notify-event

HTTP Method and Request Body

Because plugin Custom Web Services do not need to distinguish which HTTP method is used, it is recommended to use GET and POST when making requests to access web services unless documented otherwise. The request body and output may vary for each web service called. See the plugin type documentation for the requested plugin for available web services, request parameters, and expected output.

4.16 Plugin Types

The PluginType API page contains the type and description of all fields in the Plugin Type object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

4.16.1 Getting Plugin Types

Quick Reference

GET http://localhost/mws/rest/plugin-types/<id>

4.16.1.1 Get All Plugin Types

URLs and Parameters

GET http://localhost/mws/rest/plugin-types

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 2,
  "resultCount": 2,
  "results":   [
    {"id": "vCenter"},
    {"id": "Native"}
  ]
}

4.16.1.2 Get Single Plugin Type

URLs and Parameters

GET http://localhost/mws/rest/plugin-types/<id>

See Global URL Parameters for available URL parameters.

Sample Response

{
  "author": "Adaptive Computing Enterprises, Inc.",
  "commonsVersion": "0.9.3 > *",
  "description": "Polls a VMware® vCenter™ Server for information on the hypervisors and virtual machines it manages.",
  "documentationLink": "",
  "email": "",
  "id": "VCenter",
  "initialPlugins": { },
  "instances": [
    {"id":"vcenter"}
  ],
  "issueManagementLink": "",
  "license": "APACHE",
  "mwsVersion": "7.1.2 > *",
  "pollMethod": true,
  "scmLink": "",
  "title": "VCenter",
  "version": "1.0",
  "webServices": [ ],
  "website": "http://www.adaptivecomputing.com"
}

4.16.2 Creating or Updating Plugin Types

Quick Reference

PUT http://localhost/mws/rest/plugin-types[?reload-plugins=false]

There is a known issue with dynamically updating plugin types with typed field injection. See the Add or Update Plugin Types section for more information.

4.16.2.1 Update Plugin Type (File)

URLs and Parameters

PUT http://localhost/mws/rest/plugin-types[?reload-plugins=false]

See Global URL Parameters for available URL parameters.

Request Body

This function is idempotent, meaning it will create the Plugin Type if it does not exist or update it if it does. The request body is the actual contents of the class file to upload. This web service is an exception to most as it requires a content type of application/x-groovy or text/plain.

If the application/x-groovy or text/plain content types are not used in the request, it will be interpreted as JSON, resulting in a failure.

package test
import com.adaptc.mws.plugins.*
class UploadPlugin {
	static author = "Adaptive Computing"
	static description = "A sample plugin class"
	String id
	public void configure() throws InvalidPluginConfigurationException {
		def myConfig = config
		def errors = []
		if (!myConfig.arbitraryKey)
			errors << "Missing arbitraryKey!"
		if (errors)
			throw new InvalidPluginConfigurationException(errors)
	}
	public def customService(Map params) {
		return params
	}
}

If using the curl library to perform plugin type uploading, the equivalent of the command-line option --data-binary must be used to send the request body. Otherwise compilation errors may be encountered when uploading the plugin type.

Sample Response

The response of this task is the same as the Get All Plugin Types task. The reason that the return of this task is a list is to accommodate the possibility of uploading multiple plugin types in a single JAR file as explained in the next section.

4.16.2.2 Update Plugin Type (JAR)

URLs and Parameters

PUT http://localhost/mws/rest/plugin-types?jar-filename=<filename.jar>[&reload-plugins=false]

See Global URL Parameters for available URL parameters.

Request Body

This function is idempotent, meaning it will create the Plugin Types if they do not exist or update them if they do. The request body is the binary contents of the JAR file to upload. This web service is an exception to most as it requires a content type of application/x-jar.

If the application/x-jar content type is not used in the request, it will be interpreted as JSON, resulting in a failure.

If using the curl library to perform plugin type uploading, the equivalent of the command-line option --data-binary must be used to send the request body. Otherwise compilation errors may be encountered when uploading the plugin type.

Sample Response

The response of this task is the same as the Get All Plugin Types task. Note that when using a JAR file, multiple plugin types may be uploaded in the same request.

4.17 Policies

The Policy API contains the type and description of fields that all Policies have in common.

Supported Policies

Supported Methods

4.17.1 Getting Policies

Quick Reference

GET http://localhost/mws/rest/policies

4.17.1.1 Get All Policies

URLs and Parameters

GET http://localhost/mws/rest/policies

It is possible to query policies by one or more fields based on MongoDB query syntax.

See Global URL Parameters for available URL parameters.

Sample Response

{
  "totalCount": 2,
  "resultCount": 2,
  "results": [  {
    "conflicted": false,
    "state": "DISABLED",
    "id": "auto-vm-migration"
  },{
    "conflicted": false,
    "state": "DISABLED",
    "id": "hv-allocation-overcommit"
  },{
    "conflicted": false,
    "state": "DISABLED",
    "id": "node-allocation"
  },{
    "conflicted": false,
    "state": "DISABLED",
    "id": "migration-exclusion-list"
  }]
}

4.17.1.2 Get Single Policy

URLs and Parameters

GET http://localhost/mws/rest/policies/<id>

See Global URL Parameters for available URL parameters.

Sample Responses

{
  "conflicted": false,
  "description": "Controls how virtual machines are automatically migrated.",
  "id": "auto-vm-migration",
  "name": "Auto VM Migration",
  "potentialConflicts": [],
  "priority": 1,
  "state": "DISABLED",
  "tags": [],
  "types": [],
  "version": 0,
  "genericMetricThresholds":{
  	"GMETRIC1":1.3
  },
  "processorUtilizationThreshold":0.5,
  "memoryUtilizationThreshold":0.4
}

{
  "conflicted": false,
  "description": "Controls how hypervisors are overallocated with regards to processors and memory.",
  "id": "hv-allocation-overcommit",
  "name": "Hypervisor Allocation Overcommit",
  "potentialConflicts": [],
  "priority": 2,
  "state": "DISABLED",
  "tags": [],
  "types": [],
  "version": 0,
  "processorAllocationLimit":29.5,
  "memoryAllocationLimit":1.2
}

{
  "conflicted": false,
  "description": "Controls how nodes are selected for workload placement.",
  "id": "node-allocation",
  "name": "Node Allocation",
  "potentialConflicts": [],
  "priority": 3,
  "state": "DISABLED",
  "tags": [],
  "types": [],
  "version": 0,
  "nodeAllocationAlgorithm": "CustomPriority",
  "customPriorityFunction": "100*RSVAFFINITY - GMETRIC[numvms]"
}

{
    "conflicted": false,
    "description": "Controls which machines are excluded from automatic live migration operations.",
    "hvExclusionList": ["blade05", "blade02"],
    "name": "Migration Exclusion List",
    "potentialConflicts": [],
    "priority": 100,
    "state": "DISABLED",
    "tags": [],
    "types": [],
    "version": 1,
    "vmExclusionList": ["vm1", "vm5"],
    "id": "migration-exclusion-list"
}

4.17.2 Modifying Policies

Quick Reference

PUT http://localhost/mws/rest/policies/<id>

4.17.2.1 Modify Policy

URLs and Parameters

PUT http://localhost/mws/rest/policies/<id>[?change-mode=set]

See Global URL Parameters for available URL parameters.

Additional URL parameters

URL parameters for modifying a Migration Exclusion Lists Policy.

Request Body

In general, the fields shown in the Policy API are not available for modification. However, the state field may be modified to a valid Policy State. All other fields listed in the specific API pages may be modified unless documented otherwise.

The request body below shows all the fields that are available when modifying a Auto VM Migration Policy, along with some sample values.

{
    "genericMetricThresholds": {
        "GENERICTHRESHOLD": 5
    },
    "memoryUtilizationThreshold": 0.5,
    "processorUtilizationThreshold": 0.4
}

The request body below shows all the fields that are available when modifying a Node Allocation Policy, along with some sample values.

{
      "nodeAllocationAlgorithm" : "CustomPriority",
      "customPriorityFunction" : "100*RSVAFFINITY - GMETRIC[numvms]"
}

The request body below shows all the fields that are available when modifying a Migration Exclusion Lists Policy, along with some sample values.

{
   "vmExclusionList" : ["vm1","vm3","vm5"], 
   "hvExclusionList" : ["hv2","hv3","hv6"]
}

Sample Response

{
    "messages": ["Policy auto-vm-migration updated"]
}

Samples

Enable the Auto VM Migration Policy and set values.

{
  "state": "enabled",
  "migrationAlgorithmType": "overcommit",
  "processorUtilizationThreshold": 0.5,
  "memoryUtilizationThreshold": 0.4
}

As noted in the Auto VM Migration API documentation, if the state is set to ENABLED, then the migrationAlgorithmType must not be set to NONE.

Restrictions

All Policies

• Fields cannot be modified while the policy is disabled. Enable the policy to modify the field.

Auto VM Migration

• Arbitrary metrics can be added to genericMetricThresholds, but they cannot be removed once added.
• The migrationAlgorithmType field cannot be modified while the policy is disabled. Enable the policy to modify the field.
• Moab is configured with a default limit of 10 generic metrics. If this limit is reached, such as when arbitrary metrics are added to genericMetricThresholds, the metric will not be reported.
• To increase this limit, set the MAXGMETRIC property in the Moab configuration file.

4.18 Principals

The Principal API contains the type and description of all fields in the Principal object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods