(Quick Reference)
2Access Control >>

1 Introduction

Table of Contents

1.1Moab® Web Services Overview
1.2Upgrading from Previous Versions
1.3Installation Guide
1.3.1Requirements
1.3.2Quickstart Guide
1.4Troubleshooting
1.5Configuration
1.6Security
1.7Version and Build Information

1 Introduction

1.1 Moab® Web Services Overview

Moab Web Services (MWS) is a component of Adaptive Computing Suites that enables programmatic interaction with Moab Workload Manager via a RESTful interface. MWS allows you to create and interact with Moab objects and properties such as jobs, nodes, virtual machines, and reservations. MWS is the preferred method for those wishing to create custom user interfaces for Moab and is the primary method by which Moab Viewpoint communicates with Moab.

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

In order to upgrade from previous versions of MWS, the following steps must be completed. MWS is capable of detecting and performing necessary database updates, but this process must be triggered manually (see steps 3 and 4 below) by the admin user. It is not always necessary to perform database updates even when MWS is upgraded to a new version.

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.

You will see some sample queries and a few other actions.

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

The credentials are the values of auth.defaultUser.username and auth.defaultUser.password set in the MWS configuration file.

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

These instructions describe how to install Moab® Web Services (MWS).

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.

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.

You will see some sample queries and a few other actions.

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

The credentials are the values of auth.defaultUser.username and auth.defaultUser.password that you set above.

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

1.4 Troubleshooting

If something goes wrong with MWS, look in the following files:
  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 is most likely not running, or the host and port are misconfigured. Start MongoDB or reconfigure MWS and restart MWS.

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

This section describes the location of the Moab Web Services configuration files. It also shows some examples of how to configure logging.

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.

Minimal Logging Configuration
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.

Console Logging Configuration
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".

Sample OpenLDAP Configuration
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.

Sample Active Directory Configuration
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:

Advanced Active Directory Configuration
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.

Advanced OpenLDAP Configuration
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:

Advanced OpenLDAP Configuration
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

When running MWS in production environments, security is a major concern. This section focuses on securing the three kinds of connections with MWS:
  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.

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" />
Save the server.xml file.
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.)

Configuring an SSL/TLS connection to LDAP
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:

Configuring a StartTLS connection to LDAP
ldap.port = 389
ldap.security.type = "StartTLS"
ldap.security.server.certificate = "ldapServerCert.pem"

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

ldap.security.typeDefault PortNotes
None389This is the default if no security type is configured. All data is sent in plain text.
SSL636Requires server certificate. All data is encrypted.
StartTLS389Starts as an insecure connection and is upgraded to an SSL/TLS connection. Requires server certificate. After upgrade all data is encrypted.

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.

Changing the SSL/TLS security certificates location
mws.certificates.location = "etc/someOtherCertsFolder

1.7 Version and Build Information

To get detailed version information about MWS, use one of the following three methods:

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
2Access Control >>