GT 4.2.1 Index Service: User's Guide

Introduction

This guide contains information for end-users of the WS MDS Index Service. The Index Service collects information about grid resources and publishes them as service group entries.


Table of Contents

Index Service How-tos
1. Getting Information from the MDS Index Service
1. Simple usage
WS MDS Index User Commands
wsrf-query - Performs query on a resource property document
wsrf-get-property - Gets values of a single resource property
wsrf-get-properties - Gets values of multiple resource properties
globus-wsrf-query - Query a WSRF resource's Resource Property document
globus-wsrf-get-property - Get a resource property's value
globus-wsrf-get-properties - Get multiple resource property value
2. Graphical User Interface
3. Troubleshooting
1. Error Messages
2. General troubleshooting information
Glossary
Index

Index Service How-tos

G

getting information from the Index Service (end users), Getting Information from the MDS Index Service

T

troubleshooting, Troubleshooting

Chapter 1. Getting Information from the MDS Index Service

Table of Contents

1. Simple usage

To view the information contained in an Index Service, you can use either Java WS Core commands (outlined below) or WebMDS.

1. Simple usage

A typical example of using the default Index Service is with the wsrf-query Java WS Core command. For example:

$GLOBUS_LOCATION/bin/wsrf-query -s https://localhost:8443/wsrf/services/DefaultIndexService '/*'

displays all the resource properties collected by the default Index Service on your local host.

You can also use an XPath query to drill down your search as well as other Java WS Core commands such as wsrf-get-property and wsrf-get-properties. For more information, review the User's Guide.

WS MDS Index User Commands


The index service exposes information via service groups and is accessed using the same command-line tools used to query other WSRF services for information. These tools are part of Java WS Core .

A set of functionally equivalent tools exist written using WS C core. They tend to be faster alternatives to the above java programs. These tools are part of C WS Core .

The following commands are originally documented under their respective component guides, but are reproduced here for convenience.

Table of Contents

wsrf-query - Performs query on a resource property document
wsrf-get-property - Gets values of a single resource property
wsrf-get-properties - Gets values of multiple resource properties
globus-wsrf-query - Query a WSRF resource's Resource Property document
globus-wsrf-get-property - Get a resource property's value
globus-wsrf-get-properties - Get multiple resource property value

Name

wsrf-query — Performs query on a resource property document

Synopsis

wsrf-query

Tool description

Queries the resource property document of a resource. By default, a simple XPath query is assumed that returns the entire resource property document.

Command syntax

wsrf-query [options] [query expression] [dialect]

Table 1. Common options

-h, --help

Displays help information about the command.

-d, --debug

Enables debug mode. For example, full stack traces of errors will be displayed.

-e, --eprFile <file>

Specifies an XML file that contains the WS-Addressing endpoint reference.

-s, --service <url>

Specifies the service URL.

-k, --key <name value>

Specifies the resource key. The name is the QName of the resource key in the string form: {namespaceURI}localPart, while the value is the simple value of the key. For complex keys, use the --eprFile option. Example:

-k "{http://www.globus.org}MyKey"
       123

-f, --descriptor <file>

Specifies a client security descriptor. Overrides all other security settings.

-a, --anonymous

Enables anonymous authentication. Only supported with transport security or the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.

-m, --securityMech <type>

Specifies the authentication mechanism. type can be 'msg' for GSI Secure Message, or 'conv' for GSI Secure Conversation.

-c, --serverCertificate <file>

Specifies the server's certificate file used for encryption. Only needed for the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Examples:

 $ wsrf-query -s https://127.0.0.1:8443/wsrf/services/DefaultIndexService \
    "count(//*[local-name()='Entry'])"

 $ wsrf-query -s https://127.0.0.1:8443/wsrf/services/DefaultIndexService \
    "number(//*[local-name()='GLUECE']/glue:ComputingElement/glue:State/@glue:FreeCPUs)=0"

 $ wsrf-query -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    "/*/*/*/*[local-name()='Address']"

Name

wsrf-get-property — Gets values of a single resource property

Synopsis

wsrf-get-property

Tool description

Gets a single resource property from a resource.

Command syntax

wsrf-get-property [options] <property>

The <property> is a QName of the resource property in the string form: {namespaceURI}localPart.

Table 2. Common options

-h, --help

Displays help information about the command.

-d, --debug

Enables debug mode. For example, full stack traces of errors will be displayed.

-e, --eprFile <file>

Specifies an XML file that contains the WS-Addressing endpoint reference.

-s, --service <url>

Specifies the service URL.

-k, --key <name value>

Specifies the resource key. The name is the QName of the resource key in the string form: {namespaceURI}localPart, while the value is the simple value of the key. For complex keys, use the --eprFile option. Example:

-k "{http://www.globus.org}MyKey"
       123

-f, --descriptor <file>

Specifies a client security descriptor. Overrides all other security settings.

-a, --anonymous

Enables anonymous authentication. Only supported with transport security or the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.

-m, --securityMech <type>

Specifies the authentication mechanism. type can be 'msg' for GSI Secure Message, or 'conv' for GSI Secure Conversation.

-c, --serverCertificate <file>

Specifies the server's certificate file used for encryption. Only needed for the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

 $ wsrf-get-property -s http://localhost:8080/wsrf/services/CounterService \ -k
    "{http://counter.com}CounterKey" 123 \
    "{http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}CurrentTime"

Name

wsrf-get-properties — Gets values of multiple resource properties

Synopsis

wsrf-get-properties

Tool description

Gets multiple resource properties from a resource.

Command syntax

wsrf-get-properties [options] <property1> [<property2>...
    <propertyN>]

Each <propertyN> is a QName of the resource property in the string form: {namespaceURI}localPart.

Table 3. Common options

-h, --help

Displays help information about the command.

-d, --debug

Enables debug mode. For example, full stack traces of errors will be displayed.

-e, --eprFile <file>

Specifies an XML file that contains the WS-Addressing endpoint reference.

-s, --service <url>

Specifies the service URL.

-k, --key <name value>

Specifies the resource key. The name is the QName of the resource key in the string form: {namespaceURI}localPart, while the value is the simple value of the key. For complex keys, use the --eprFile option. Example:

-k "{http://www.globus.org}MyKey"
       123

-f, --descriptor <file>

Specifies a client security descriptor. Overrides all other security settings.

-a, --anonymous

Enables anonymous authentication. Only supported with transport security or the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.

-m, --securityMech <type>

Specifies the authentication mechanism. type can be 'msg' for GSI Secure Message, or 'conv' for GSI Secure Conversation.

-c, --serverCertificate <file>

Specifies the server's certificate file used for encryption. Only needed for the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

 $ wsrf-get-properties -s http://localhost:8080/wsrf/services/CounterService \ -k
    "{http://counter.com}CounterKey" 123 \
    "{http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}CurrentTime"
    \
    "{http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}TerminationTime"

Name

globus-wsrf-query — Query a WSRF resource's Resource Property document

Synopsis

globus-wsrf-query [OPTIONS]... SERVICE-SPECIFIER QUERY-EXPRESSION

Tool description

Perform an XPATH query on a resource property document.

Command syntax

globus-wsrf-query [OPTIONS]... SERVICE-SPECIFIER QUERY-EXPRESSION

Table 4. Application-specific options

-n | ----nsMapFile FILENAME.

Use the namespace map entries in FILENAME in the XPATH context.

-N | --namespace PREFIX=NAMESPACE-URI

Create a namespace mapping in the XPATH context for the PREFIX string to resolve to the NAMESPACE-URI namespace.

-D | --dialect DIALECT-URI

Set query dialect to DIALECT-URI. The value targeted will be interpreted as http://wsrf.globus.org/core/query/targetedXPath (default: http://www.w3.org/TR/1999/REC-xpath-19991116).

Table 5. Common options

-a | --anonymous

Use anonymous authentication. Requires either -m 'conv' or transport (https) security.

-d, --debug

Enables debug mode. In debug mode, all SOAP messages will be displayed to stderr and full WSRF Fault messages will be displayed.

-e | --eprFile FILENAME

Load service EPR from FILENAME. This EPR is used to contact the WSRF service.

-h | --help

Displays help information about the command.

-k | --key KEYNAME VALUE

Set resource key in the service EPR to be named KEYNAME with VALUE as its value. This can be combined with -s to construct an EPR without having an xml file on hand. The KEYNAME is a QName string in the format {namespaceURI}localPart. while the VALUE is a literal string to place in the element. For example, the option -k '{http://www.globus.org}MyKey' 128 would be rendered as <MyKey xmlns="http://www.globus.org">128</MyKey>

-m, --securityMech TYPE

Set authentication mechanism. TYPE is one of msg for WS-SecureMessage or conv for WS-SecureConversation.

-p, --protection LEVEL

Set message protection level. LEVEL is one of sig for digital signature or enc for encryption. The default is 'sig'.

-s | --service ENDPOINT

Set ENDPOINT the service URL to use. Will be composed with the -k parameter if present to add ReferenceProperties to the ENDPOINT

-t | --timeout SECONDS

Set client timeout to SECONDS.

-u | --usage

Print short usage message.

-V | --version

Show version information and exit.

-v | --certKeyFiles CERTIFICATE-FILENAME KEY-FILENAME

Use credentials located in CERTIFICATE-FILENAME and KEY-FILENAME. The key file must be unencrypted.

-x | --proxyFilename FILENAME

Use proxy credentials located in FILENAME.

-z | --authorization TYPE

Set authorization mode. TYPE can be self, host, none, or a string specifying the identity of the remote party. The default is self.

--versions

Show version information for all loaded modules and exit.

SERVICE-SPECIFIER: [-s URI [-k KEY VALUE] | -e FILENAME]

QUERY-EXPRESSION: XPath-Expression-String

Examples:

% globus-wsrf-query -e widget.epr "//*[local-name() = 'CurrentTime']"
<ns02:CurrentTime 
    xmlns:ns00="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:ns01="http://www.w3.org/2001/XMLSchema" 
    xmlns:ns02="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd" 
    ns00:type="ns01:dateTime">2006-05-30T13:53:15Z</ns02:CurrentTime>
       
% globus-wsrf-query -e widget.epr "//*[local-name() = 'CurrentTime']/text()"
2006-05-30T13:53:35Z
       
% globus-wsrf-query -e widget.epr \
       -N wsrl=http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd \
       "//wsrl:CurrentTime/text()"
2006-05-30T13:54:36Z
       

Contents of widget.epr:

<ns01:EndpointReference xmlns:ns01="http://schemas.xmlsoap.org/ws/2004/03/addressing">
  <ns01:Address>http://globus.my.org:8080/wsrf/services/WidgetService</ns01:Address>
  <ns01:ReferenceProperties>
    <ResourceID xmlns:ns02="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns03="http://www.w3.org/2001/XMLSchema" ns02:type="ns03:string">7f554f7c-efd9-11da-97a5-00096b86f788</ResourceID>
  </ns01:ReferenceProperties>
</ns01:EndpointReference>

Limitations

  • The namespace mapping option and use of namespace prefixes in the XPath-Expression-String does not work when communicating with the Java container unless the http://wsrf.globus.org/core/query/targetedXPath dialect is used.

Output and Exit Code

If the query is successful, the program displays the output of the query to stdout and terminates with exit code 0. In the case of an error, the type of error will be displayed to stderr and the program will terminate with a non-0 exit code.

Name

globus-wsrf-get-property — Get a resource property's value

Synopsis

globus-wsrf-get-property [OPTIONS]... SERVICE-SPECIFIER PROPERTY-NAME

Tool description

Get the value of a resource property from a WSRF resource.

Command syntax

globus-wsrf-get-property [OPTIONS]... SERVICE-SPECIFIER PROPERTY-NAME

Table 6. Common options

-a | --anonymous

Use anonymous authentication. Requires either -m 'conv' or transport (https) security.

-d, --debug

Enables debug mode. In debug mode, all SOAP messages will be displayed to stderr and full WSRF Fault messages will be displayed.

-e | --eprFile FILENAME

Load service EPR from FILENAME. This EPR is used to contact the WSRF service.

-h | --help

Displays help information about the command.

-k | --key KEYNAME VALUE

Set resource key in the service EPR to be named KEYNAME with VALUE as its value. This can be combined with -s to construct an EPR without having an xml file on hand. The KEYNAME is a QName string in the format {namespaceURI}localPart. while the VALUE is a literal string to place in the element. For example, the option -k '{http://www.globus.org}MyKey' 128 would be rendered as <MyKey xmlns="http://www.globus.org">128</MyKey>

-m, --securityMech TYPE

Set authentication mechanism. TYPE is one of msg for WS-SecureMessage or conv for WS-SecureConversation.

-p, --protection LEVEL

Set message protection level. LEVEL is one of sig for digital signature or enc for encryption. The default is 'sig'.

-s | --service ENDPOINT

Set ENDPOINT the service URL to use. Will be composed with the -k parameter if present to add ReferenceProperties to the ENDPOINT

-t | --timeout SECONDS

Set client timeout to SECONDS.

-u | --usage

Print short usage message.

-V | --version

Show version information and exit.

-v | --certKeyFiles CERTIFICATE-FILENAME KEY-FILENAME

Use credentials located in CERTIFICATE-FILENAME and KEY-FILENAME. The key file must be unencrypted.

-x | --proxyFilename FILENAME

Use proxy credentials located in FILENAME.

-z | --authorization TYPE

Set authorization mode. TYPE can be self, host, none, or a string specifying the identity of the remote party. The default is self.

--versions

Show version information for all loaded modules and exit.

SERVICE-SPECIFIER: [-s URI [-k KEY VALUE] | -e FILENAME]

PROPERTY-NAME: [{Namespace-URI}]Property-Name

Example:

% globus-wsrf-get-property -e widget.epr \
       '{http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}CurrentTime'

<ns02:CurrentTime 
    xmlns:ns00="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:ns01="http://www.w3.org/2001/XMLSchema" 
    xmlns:ns02="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd" 
    ns00:type="ns01:dateTime">2006-05-30T14:26:35Z</ns02:CurrentTime>
        

Output and Exit Code

If the property exists, its values (if any) are displayed to stdout and the program terminates with exit code 0. In the case of an error, the type of error will be displayed to stderr and the program will terminate with a non-0 exit code.

Name

globus-wsrf-get-properties — Get multiple resource property value

Synopsis

globus-wsrf-get-properties [OPTIONS]... SERVICE-SPECIFIER PROPERTY-NAME...

Tool description

Get the value of multiple resource properties from a WSRF resource.

Command syntax

globus-wsrf-get-properties [OPTIONS]... SERVICE-SPECIFIER PROPERTY-NAME...

Table 7. Common options

-a | --anonymous

Use anonymous authentication. Requires either -m 'conv' or transport (https) security.

-d, --debug

Enables debug mode. In debug mode, all SOAP messages will be displayed to stderr and full WSRF Fault messages will be displayed.

-e | --eprFile FILENAME

Load service EPR from FILENAME. This EPR is used to contact the WSRF service.

-h | --help

Displays help information about the command.

-k | --key KEYNAME VALUE

Set resource key in the service EPR to be named KEYNAME with VALUE as its value. This can be combined with -s to construct an EPR without having an xml file on hand. The KEYNAME is a QName string in the format {namespaceURI}localPart. while the VALUE is a literal string to place in the element. For example, the option -k '{http://www.globus.org}MyKey' 128 would be rendered as <MyKey xmlns="http://www.globus.org">128</MyKey>

-m, --securityMech TYPE

Set authentication mechanism. TYPE is one of msg for WS-SecureMessage or conv for WS-SecureConversation.

-p, --protection LEVEL

Set message protection level. LEVEL is one of sig for digital signature or enc for encryption. The default is 'sig'.

-s | --service ENDPOINT

Set ENDPOINT the service URL to use. Will be composed with the -k parameter if present to add ReferenceProperties to the ENDPOINT

-t | --timeout SECONDS

Set client timeout to SECONDS.

-u | --usage

Print short usage message.

-V | --version

Show version information and exit.

-v | --certKeyFiles CERTIFICATE-FILENAME KEY-FILENAME

Use credentials located in CERTIFICATE-FILENAME and KEY-FILENAME. The key file must be unencrypted.

-x | --proxyFilename FILENAME

Use proxy credentials located in FILENAME.

-z | --authorization TYPE

Set authorization mode. TYPE can be self, host, none, or a string specifying the identity of the remote party. The default is self.

--versions

Show version information for all loaded modules and exit.

SERVICE-SPECIFIER: [-s URI [-k KEY VALUE] | -e FILENAME]

PROPERTY-NAME: [{Namespace-URI}]Property-Name

Example:

% globus-wsrf-get-properties \
        -s http://grid.example.org:8080/wsrf/services/WidgetService \
        -k "{http://www.globus.org/namespaces/2004/06/core}WidgetKey" 123 \
        "{http://widgets.com}foo" \
        "{http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}CurrentTime"
<ns02:foo
    xmlns:ns00="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ns01="http://www.w3.org/2001/XMLSchema"
    xmlns:ns02="http://widgets.com"
    ns00:type="ns01:string">
Foo Value String
</ns02:foo><ns03:CurrentTime
    xmlns:ns00="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ns01="http://www.w3.org/2001/XMLSchema"
    xmlns:ns03="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd"
    ns00:type="ns01:dateTime">2006-05-30T16:04:15Z</ns03:CurrentTime>
        

Output and Exit Code

If the properties exist, their values (if any) are displayed to stdout and the program terminates with exit code 0. In the case of an error, the type of error will be displayed to stderr and the program will terminate with a non-0 exit code.

Chapter 2. Graphical User Interface

There is no GUI specifically for the Index Service. The release contains WebMDS" which can be used to display monitoring information collected in an Index Service in a normal web browser.

Chapter 3.  Troubleshooting

General troubleshooting information is based on Java WS Core and is included below.

For a list of common errors in GT, see Error Codes.

1. Error Messages

Table 3.1. WS MDS Index Service Error Messages

Error CodeDefinitionPossible Solutions
error what causes this possible solutions
WS MDS is built on Java WS Core, please see Java WS Core Error Codes for more error code documentation.

2. General troubleshooting information

  • In general, if you want to investigate a problem on your own please see Chapter 10, Debugging for details on how to turn on debugging.

  • Most of the command line clients have a -debug option that will display more detailed error messages, including the error stack traces.

  • Search the mailing lists such as gt-user@globus.org or jwscore-user@globus.org (before posting a message).

  • If you think you have found a bug please report it in our Bugzilla system. Please include as much as detail about the problem as possible.

Glossary

C

certificate

A public key plus information about the certificate owner bound together by the digital signature of a CA. In the case of a CA certificate, the certificate is self signed, i.e. it was signed using its own private key.

W

Web Services Addressing (WSA)

The WS-Addressing specification defines transport-neutral mechanisms to address web services and messages. Specifically, it defines XML elements to identify web service endpoints and to secure end-to-end endpoint identification in messages. See the W3C WS Addressing Working Group for details.

X

XML

Extensible Markup Language (XML) is standard, flexible, and extensible data format used for web services. See the W3C XML site for details.