OGSI defined a standard create method for creating new grid services. The follow on, the WS Resource Framework, no longer defines such a mechanism. This does not mean that the factory pattern is not valuable. Rather, it was removed because any non-trivial create method tends to be application specific, a observation that leads to the conclusion that there is little value in standardizing this operation. We recommend the use of the factory pattern for dynamic creation of resources. In particular we recommend writing a factory service that provides a way to create new resources and allows users to inspect state information about the aggregation of all resources created by the factory service, e.g. the number of resources managed. In addition to the factory service one would write a service that interacts with the resource instances created by the factory service.

1.2. Scalability, recovery and resource persistence

Writing scalable (in the number of resources) and recoverable, i.e. give it the ability to survive a server crash and restart, resources takes a bit of careful planning. There are several potential pitfalls:

Since scalability relies upon using Java soft references it is important that resource do not keep hard references to any objects that would prevent the soft reference mechanism from working.
When recovering resources after a container restart it is often important to re-establish the current state of the process the resource represents, e.g. if the resource is monitoring a external entity via notifications it should query for the current state of the external entity upon restart.
Persisted resources need to be carefully written to avoid the following problem: If a service currently holds a hard reference to the resource and the resource is destroyed, i.e. the soft reference to the resource is removed from the resource home and the resource is removed from persistent storage, then the service holding the resource reference can still cause a call to the store persistence callback. Unless the store callback was written to prevent this, calling it will restore the destroyed resource.
For example: during a typical service operation, a service will lookup a resource using its resource home. At that point in time, the service holds a hard reference to the resource object. If another client of the service concurrently invokes a destroy operation on the same resource, thus removing the resource from the resource home and its state from persistent storage, the resource essentially becomes invalid. When this occurs it is important that the first service operation not invoke the resource's store method since doing so would inadvertently recreate (or resurrect) the resource.
To prevent this consider writing the resource's store and remove methods in such a way as to prevent recreating resource state that has been previously destroyed by another caller.
Resource implementers need to be careful when storing objects created by axis as part of the web service operation invocation and containing fields resulting from a xsd:any in the corresponding schema. These complex types have references to sizable objects associated with the Axis deserialization/data-binding process. To remove these reference replace the object by calling org.globus.wsrf.encoding.ObjectSerializer.clone(originalObject) and drop the reference to the original object.

1.3. Concurrent invocations and synchronization

The container does not provide automatic synchronization of concurrent requests. This means that service implementors need to write their services to deal with potential synchronization problems. If you service itself is stateless this means that if you will need to synchronize around access to the state captured in the resource. That being said, in a lot of scenarios you can expect a single client to drive most interactions with a given resource, in which case synchronization may not be an issue.

1.4. Lease-based lifetime management

We recommend that you make use of lease based resource lifetime management to avoid orphaned resources due to network outage and other failures. Lease based lifetime management is accomplished by specifying a initial lifetime in the resource creation operation followed by periodic updates to the lifetime using the setTerminationTime operation specified in the WS Resource Lifetime specification.

1.5. Resource Types and Services

Any given WSRF service can only have a single resource properties document schema associated with it. This implies a constraint on the type of resource a service can expose, i.e. resources exposed by a service must conform to the resource properties document schema associated with the service. Note that this does not necessarily mean that services can only expose resources of a single implementation type. There may of course be multiple implementation types as long as all of these types conform to the interface dictated by the resource property document schema. Also, the resource property document schema may have extensibility elements, allowing more flexibility in the resource implementation at the expense of reducing discoverability and implicitly predictability of interactions against resources exposed by such a service. That said, the Java WS Core implementations of the Resource Home interface only allow a single resource type.

In addition, services may interact with any type of resource, unconstrained by the resource property document schema, as long as these resources are not expose by the service. This occurs frequently in the standard factory pattern, where the factory creates and manipulates a resource, but the resource itself is exposed through a different service.

1.6. Messaging granularity

Our current performance profile for the Java WS Core component currently only allows for fairly coarse grained operations at a reasonable level of performance. While this statement is in relation to Java WS Core performance it is in reality relevant to any distributed applications: Remote invocations always cost more than local invocation (give infinite CPU power/memory) and should thus be treated differently than local invocations.

1.7. Choosing an authentication mechanism

GT4 provides a implementer with a choice of 4 authentication mechanisms: HTTPS (ie SSL/TLS), WS-Security with X.509 certificates, WS-Security Username/Password authentication and a GSSAPI based WS-Trust/SecureConversation/Security based mechanism. We recommend that service implementors try to support the greatest number of mechanisms possible. Generally, services that need both authentication and message protection should always allow any mechanism other than the username/password one.

The story is somewhat different on the client end of things. Whereas server side security configuration is mostly policy driven, clients actually have to pick a specific mechanism to implement. We recommend that clients use HTTPS whenever available, i.e. whenever the service URL indicates a HTTPS transport, but are able to fall back on WS-Security with X.509 certificates should the transport be a non-https one. This recommendation is based upon performance comparisons of HTTPS vs. WS-Security based mechanisms, which have shown HTTPS to be much higher performance, especially as the message payload grows.

GT 4.2.0 Resource Properties Overview

Table of Contents

1. Introduction

2. Security

2.1. Resource properties
2.2. CAS Resource Properties
2.3. Delegation Service Resource properties

3. Data Management

3.1. RFT Resource Properties
3.2. WS RLS Resource Properties
3.3. Data Replication Service (DRS) Resource properties

4. Information Services

4.1. WS MDS Aggregator Framework Resource Properties

5. Execution Management

5.1. Resource properties

1. Introduction

This page aggregates information about resource properties currently available throughout GT 4.2.0.

2. Security

2.1. Resource properties

supportedPolicies: Contains identifiers for any or all access control policies that the authorization service is capable of rendering decisions regarding.
supportsIndeterminate: Indicates whether the authorization service may return an "indeterminate" authorization decision. If set to flase, only permit or deny is returned.
signatureCapable: Indicates if the authorization service is capable of signing the decision returned. If not, only unsigned decisions are returned.

2.2. CAS Resource Properties

ServerDN: The DN from the credentials used by the CAS Service
VODescription: This is a string that describes the VO relevant to CAS Service.

2.3. Delegation Service Resource properties

2.3.1. Delegation Factory Service

CertificateChain: This resource property is used to expose the certificate used by delegation service.

3. Data Management

3.1. RFT Resource Properties

The resource properties of RFT Factory (which acts both as a resource and a service at the same time) and RFT Resource are found below:

3.1.1. RFT Factory Resource Properties

ActiveResourceInstances: A dynamic resource property of the total number of active RFT resources in the container at a given point of time.
TotalNumberOfTransfers: A dynamic resource property of the total number of transfers/deletes performed since the RFT service was deployed in this container.
TotalNumberOfActiveTransfers: A dynamic resource property of the number of active transfers across all rft resources in a container at a given point of time.
TotalNumberOfBytesTransferred: A dynamic resource property of the total number of bytes transferred by all RFT resources created since the deployment of the service.
RFTFactoryStartTime: Time when the service was deployed in the container. Used to calculate uptime.
DelegationServiceEPR: The end point reference of the Delegation resource that holds the delegated credential used in executing the resource.

3.1.2. RFT Resource Properties

OverallStatus: This is a complex type providing the overall status of an RFT resource by providing the number of transfers pending, active, finished, retrying, failed, and cancelled. Each of these values can be obtained by invoking getTransfers(Finished/Active/Failed/Restarted/Pending/Cancelled) on OverallStatus Resource Property. Note that this Resource Property gets updated every time one of the transfers changes state, so there can be and will be more than one update in the life time of a RFT resource if you subscribe to this RP. This Resource Property also includes the last fault (if thrown) from a transfer and can be accessed by invoking getFault on OverallStatus. This will indicate why a transfer has failed.
RequestStatus: This is a complex type resource property providing the status of an RFT resource in the form of Pending/Active/Done/Failed. The status can be obtained from RequestStatusType by invoking getRequestStatus(). This will result in one of four status strings (Pending/Active/Done/Failed/Cancelled). This RP also contains a fault that denotes the last fault in a RFT resource and can be accessed by invoking getFault(). If a client is subscribed to this RP, there will be only be 2 updates in the life time of an RFT resource (Pending->Active->Done, Pending->Active->Failed, Pending->Active->Cancelled, and Pending->Cancelled).
TotalBytes: This provides the total number of bytes transferred by the resource.
TotalTime: This provides the total time taken to transfer the above-mentioned total bytes.

3.2. WS RLS Resource Properties

The resource properties for the ReplicaLocationCatalog ReplicaLocatoinIndex port types are listed below:

	Note
	As a preview component the current WS-RLS specifies the following RPs but in most cases does not implement them in the current release. The developers of the component are providing the interfaces for review.

3.2.1. ReplicaLocationCatalog Resource Properties

configuration: A listing of the configuration settings for the underlying RLS service.
diagnostics: A listing of diagnostics (e.g., status) from the underlying RLS service.
catalog: A resource property sytle representation of the catalog contexts (i.e., attribute definitions, attributes, and mappings) of the underlying RLS service.

3.2.2. ReplicaLocationIndex Resource Properties

configuration: A listing of the configuration settings for the underlying RLS service.
diagnostics: A listing of diagnostics (e.g., status) from the underlying RLS service.
catalog: A resource property sytle representation of the index contexts (i.e., attribute definitions, attributes, and mappings) of the underlying RLS service.

3.3. Data Replication Service (DRS) Resource properties

Supported resource properties for DataRep include:

status: The status of the resource, such as Pending, Active, Suspended, Terminated, Destroyed, etc.
stage: The current stage or activity of the resource, such as Discover, Transfer, and Register.
result: The final result (if any) of the resource, such as Finished, Failed, and Exception.
errorMessage: A verbose description of an error (if any) encountered by the resource. The message may include error or exception information returned by one of the dependent components, such as RLS or RFT.
count: An element containing counts of individual replication items pertaining to total, finished, failed, and terminated replication items.

4. Information Services

4.1. WS MDS Aggregator Framework Resource Properties

4.1.1. AggregatorServiceGroup Resource Properties

Entry: This resource property publishes details of each registered resource, including both an EPR to the resource, the Aggregator Framework configuration information, and data from the sink.
RegistrationCount: This resource property publishes registration load information (the total number of registrations since service startup and decaying averages)

5. Execution Management

5.1. Resource properties

5.1.1. Managed Job Factory Port Type

{http://www.globus.org/namespaces/2008/03/gram/job}condorArchitecture
Condor architecture label.
{http://www.globus.org/namespaces/2008/03/gram/job}condorOS
Condor OS label.
{http://www.globus.org/namespaces/2008/03/gram/job}delegationFactoryEndpoint
The endpoint reference to the delegation factory used to delegated credentials to the job.
{http://mds.globus.org/glue/ce/1.1}GLUECE
GLUE data
{http://mds.globus.org/glue/ce/1.1}GLUECESummary
GLUE data summary
{http://www.globus.org/namespaces/2008/03/gram/job}globusLocation
The location of the Globus Toolkit installation that these services are running under.
{http://www.globus.org/namespaces/2008/03/gram/job}hostCPUType
The job host CPU architecture (i686, x86_64, etc...)
{http://www.globus.org/namespaces/2008/03/gram/job}hostManufacturer
The host manufacturer name. May be "unknown".
{http://www.globus.org/namespaces/2008/03/gram/job}hostOSName
The host OS name (Linux, Solaris, etc...)
{http://www.globus.org/namespaces/2008/03/gram/job}hostOSVersion
The host OS version.
{http://www.globus.org/namespaces/2008/03/gram/job}localResourceManager
The local resource manager type (i.e. Condor, Fork, LSF, Multi, PBS, etc...)
{http://www.globus.org/namespaces/2008/03/gram/job}availableLocalResourceManager
All local resource managers that are configured in this GRAM4 instance
{http://www.globus.org/namespaces/2008/03/gram/job}jobTTLAfterProcessing
Time in seconds a job resource will stay alive after a job finished processing in GRAM4 (including fileStageOut, fileCleanUp). When this time elapsed the job resource is destroyed and no longer be available for a client. A negative values means that the job resource will never be destroyed.
{http://www.globus.org/namespaces/2008/03/gram/job}maxJobLifetime
Max time in seconds a user can set as initial lifetime in job submission or in subsequent setTerminationTime calls. A negative value means that there is no limit.
{http://mds.globus.org/metadata/2005/02}ServiceMetaDataInfo
service start time, Globus Toolkit(R) version, service type name
{http://www.globus.org/namespaces/2008/03/gram/job}scratchBaseDirectory
The directory recommended by the system administrator to be used for temporary job data.
{http://www.globus.org/namespaces/2008/03/gram/job}stagingDelegationFactoryEndpoint
The endpoint reference to the delegation factory used to delegated credentials to the staging service (RFT).

5.1.2. Managed Job Port Type

{http://www.globus.org/namespaces/2008/04/rendezvous}Capacity
Used for Rendezvous.
{http://docs.oasis-open.org/wsrf/rl-2}CurrentTime
Time of creation.
{http://docs.oasis-open.org/wsrf/rp-2}QueryExpressionDialect
From the QueryResourceProperties port type.
{http://www.globus.org/namespaces/2008/03/gram/job/faults}fault
Faults (if generated) that happen along job processing and that cause a job to fail.
{http://www.globus.org/namespaces/2008/03/gram/job/types}holding
Indicates whether a hold has been placed on this job.
{http://www.globus.org/namespaces/2008/03/gram/job/types}localUserId
The job owner's local user account name.
{http://www.globus.org/namespaces/2008/04/rendezvous}RegistrantData
Used for Rendezvous.
{http://www.globus.org/namespaces/2008/04/rendezvous}RendezvousCompleted
Used for Rendezvous.
{http://www.globus.org/namespaces/2008/03/gram/job/description}serviceLevelAgreement
A wrapper around fields containing the single-job and multi-job descriptions or RSLs. Only one of these sub-fields shall have a non-null value.
{http://www.globus.org/namespaces/2008/03/gram/job/types}state
The current state of the job.
{http://docs.oasis-open.org/wsrf/rl-2}TerminationTime
Time when the resource expires.
{http://www.globus.org/namespaces/2008/03/gram/job/types}userSubject
The GSI certificate DN of the job owner.

5.1.3. Managed Executable Job Port Type

{http://docs.oasis-open.org/wsrf/rl-2}CurrentTime
Time of creation.
{http://docs.oasis-open.org/wsrf/rl-2}TerminationTime
Time when the resource expires.
{http://www.globus.org/namespaces/2008/03/gram/job/exec}credentialPath
The path (relative to the job process) to the file containing the user proxy used by the job to authenticate out to other services.
{http://www.globus.org/namespaces/2008/03/gram/job/types}exitCode
The exit code generated by the job process.
{http://www.globus.org/namespaces/2008/03/gram/job/faults}fault
The fault (if generated) indicating the reason for failure of the job to complete.
{http://www.globus.org/namespaces/2008/03/gram/job/types}holding
Indicates whether a hold has been placed on this job.
{http://www.globus.org/namespaces/2008/03/gram/job/types}localUserId
The job owner's local user account name.
{http://www.globus.org/namespaces/2008/03/gram/job/exec}localJobId
The job id(s) of the job in the local resource manager. Note that for Fork jobs these id's are prefixed with the uuid of the job.
{http://www.globus.org/namespaces/2008/03/gram/job/description}serviceLevelAgreement
A wrapper around fields containing the single-job and multi-job descriptions or RSLs. Only one of these sub-fields shall have a non-null value.
{http://www.globus.org/namespaces/2008/03/gram/job/types}state
The current state of the job.
{http://www.globus.org/namespaces/2008/03/gram/job/exec}stderrURL
A GridFTP URL to the file generated by the job which contains the stderr.
{http://www.globus.org/namespaces/2008/03/gram/job/exec}stdoutURL
A GridFTP URL to the file generated by the job which contains the stdout.
{http://www.globus.org/namespaces/2008/03/gram/job/types}userSubject
The GSI certificate DN of the job owner.
{http://www.globus.org/namespaces/2008/04/rendezvous}Capacity
Used for Rendezvous.
{http://www.globus.org/namespaces/2008/04/rendezvous}RegistrantData
Used for Rendezvous.
{http://www.globus.org/namespaces/2008/04/rendezvous}RendezvousCompleted
Used for Rendezvous.
{http://docs.oasis-open.org/wsrf/rp-2}QueryExpressionDialect
From the QueryResourceProperties port type.

5.1.4. Managed Multi-Job Port Type

{http://docs.oasis-open.org/wsrf/rl-2}CurrentTime
Time of creation.
{http://docs.oasis-open.org/wsrf/rl-2}TerminationTime
Time when the resource expires.
{http://www.globus.org/namespaces/2008/03/gram/job/faults}fault
The fault (if generated) indicating the reason for failure of the job to complete.
{http://www.globus.org/namespaces/2008/03/gram/job/types}holding
Indicates whether a hold has been placed on this job.
{http://www.globus.org/namespaces/2008/03/gram/job/types}localUserId
The job owner's local user account name.
{http://www.globus.org/namespaces/2008/03/gram/job/description}serviceLevelAgreement
A wrapper around fields containing the single-job and multi-job descriptions or RSLs. Only one of these sub-fields shall have a non-null value.
{http://www.globus.org/namespaces/2008/03/gram/job/types}state
The current state of the job.
{http://www.globus.org/namespaces/2008/03/gram/job/multi}subJobEndpoint
A set of endpoint references to the sub-jobs created by this multi-job.
{http://www.globus.org/namespaces/2008/03/gram/job/types}userSubject
The GSI certificate DN of the job owner.
{http://www.globus.org/namespaces/2008/04/rendezvous}Capacity
Used for Rendezvous.
{http://www.globus.org/namespaces/2008/04/rendezvous}RegistrantData
Used for Rendezvous.
{http://www.globus.org/namespaces/2008/04/rendezvous}RendezvousCompleted
Used for Rendezvous.
{http://docs.oasis-open.org/wsrf/rp-2}QueryExpressionDialect
From the QueryResourceProperties port type.

GT 4.2.0 Guide to Samples

This page contains links to samples currently available throughout GT 4.2.0.

Common Runtime Components
- Java WS Core
- C WS Core
WS MDS

Asynchronous Event Handling with Examples

Table of Contents

GT 4.2.0: Asynchronous Event Handling

1. Examples
2. Event Models
3. Callback Library
4. Thread Abstraction
5. Asynchronous Model
6. Conclusion
7. References

Asynchronous Event Handling: Example 1

Asynchronous Event Handling: Example 2

Asynchronous Event Handling: Example 3

GT 4.2.0: Asynchronous Event Handling

Table of Contents

1. Examples

2. Event Models

2.1. Blocking Event Model
2.2. Non-blocking Event Model
2.3. Asynchronous Event Model

3. Callback Library

4. Thread Abstraction

5. Asynchronous Model

5.1. Blocking in Callbacks

6. Conclusion

7. References

The Globus Toolkit contains several APIs written in C for creating grid applications. Each of these components is built on a coherent asynchronous event model. This text will introduce and explain the philosophy behind the model and its basic concepts.

1. Examples

Example 1 - Demonstrates basic use of globus_callback_register_oneshot()
Example 2 - An example of globus_callback_register_oneshot() using condition variables
Example 3 - Game of Craps example demonstrates a more complex use of the asynchronous event model

2. Event Models

The Globus Toolkit uses an asynchronous event model. Details of this model are contained in the remainder of this text but it will be helpful to take a few examples of other popular models.

Applications existing in event heavy environments, such as graphical user interfaces (GUIs), IO, or inter-process signaling, must implement some event model. Events are characterized by changes in the environment at an undetermined time. There are several different popular models used to handle such events. We provide examples of them here, and then describe in detail the asynchronous event model used by the Globus Toolkit.

2.1. Blocking Event Model

In a blocking API, an event is serviced, delaying all processing in the current thread of execution until the event completes. This has the obvious disadvantage that no processing can be done while waiting on the IO. Typically this is solved by forking additional processes or creating additional threads to service each event. However, more processes and more threads make a more resource intensive application.

Example: Blocking Event Model

main()
{
    while(!done)
    {
        ~ other processing ~
        data = ReadData();
        ~ process event ~
    }
}

2.2. Non-blocking Event Model

A non-blocking model follows the same in-line procedural model as blocking except that events are polled for completion. Instead of blocking all processing until the event completes, the user asks if the event is complete. If so, the event is processed. If not, other processing may resume.

Example: Non-blocking Event Model

main()
{
    while(!done)
    {
        if(EventIsReady())
        {
            ~ process event ~
        }
        else
        {
            ~other processing ~
        }
    }
}

Unlike the blocking model, this approach allows for simultaneous processing while waiting for the event. However, it can become cumbersome as more and more events are added. Further, if there is no other processing to be done, it results in tight spin loops that use the CPU simply to poll for events.

2.3. Asynchronous Event Model

The asynchronous approach does not follow the in-line procedure. Instead events are given handler functions. A user registers for an event with the system, giving it a handler function. When the event occurs the system calls the user's handler function.

Example: Asynchronous Event Model

event_handler()
{
    process event
    register_next_event();
}

main()
{
    ~ other processing ~
     resiter_event()
      ~ other processing ~
    while(!done)
    {
        wait_for_events();
    }
}

Like the non-blocking model, this allows simultaneous event and data processing. In this model, programs are designed as a series of events rather than a serial execution of instructions. A programmer registers events and when they occur the necessary processing is done. Additional events may then be registered and the program goes back to waiting for events. This is the approach taken by the Globus Toolkit.

3. Callback Library

The heart of the Globus event model is the callback library. This API provides a user with functionality for asynchronous time events. In order to use the API for events, the user must implement a function (the callback) that is called when the event has occurred and processes it.

There are two fundamental functions that explain the API:

globus_result_t
globus_callback_register_oneshot(
    globus_callback_handle_t *          callback_handle,
    const globus_reltime_t *            delay_time,
    globus_callback_func_t              callback_func,
    void *                              callback_user_args);

globus_result_t
globus_poll();

The first function is fairly clear. It registers the callback callback_func with the system that will be called once the time specified by delay_time has expired.

The more interesting of the two is globus_poll(). Semantically this function is used to briefly turn control over to the Globus event system for processing. What this means is that globus_poll() must be called often enough for the Globus event system to function. This is recognized as a rather ambiguous statement. Therefore, a look at what happens with globus_poll() should assist in explanation. In threaded builds of Globus this globus_poll() simply results in a call to thread_yield() where control can be switched to a background thread dedicated to event processing. In non-threaded builds, a list of events is maintained by the system. A call to globus_poll() finds ready events in the list and dispatches the associated callback to the user within the same call stack.

In Example 1 a use of these two functions is displayed. The function user_callback is registered for execution after 1 second has elapsed.

In a non-threaded build, there is a single thread of execution. In the main loop, the call to globus_poll() invokes the Globus event process code. The code checks internal data structures for any ready events. If found, the user callbacks associated with the events will be called in the same call stack.

In a threaded build a user would see two threads (possibly more, but for the sake of clarity two will be used): the main thread that is executing the loop in main() and an internal Globus thread that is handling polling of events. The Globus thread is created when the user calls globus_module_activate(GLOBUS_COMMON_MODULE). This function must be called before any API function in the the globus_common package can be used. This is another common theme in Globus: all modules must be activated before use and deactivated when finished. The event thread polls all events and as they become ready the functions associated with them are dispatched.

Another important concept to note in this API is the use of the void * user_arg parameter. This is a simple but important part of the model. On registration of an event, a user can pass in a void pointer and this pointer will be threaded through to their event callback. The pointer can point to any bit of memory the user likes. Typically it points to some structure that allows the user to maintain state throughout a series of event callbacks. This memory is completely managed by the user, so if the memory is used in the event callback the user needs to be careful to not free the memory until the callback occurs. For a more complicated example of this see Example 2.

4. Thread Abstraction

The first thing to look at in understanding the Globus event model is the thread abstraction layer. Globus can be built in a variety of ways with regard to the underlying thread system. It can be built with pthreads, win32 threads, or non threaded depending on the user's preferences and the available packages on the system. All builds present the same API. This thread API is very much akin to pthreads. If the reader is not familiar with pthreads, we recommend reading the pthread manual. The more notable API interface is presented below:

int
globus_thread_create(
    globus_thread_t *           thread,
    globus_threadattr_t *       attr,
    globus_thread_func_t        func,
    void *              user_arg);

int
globus_mutex_lock(
    globus_mutex_t *            mutex);

int
globus_mutex_unlock(
    globus_mutex_t *            mutex);

int
globus_cond_wait(
    globus_cond_t *         cond,
    globus_mutex_t *            mutex);

int
globus_cond_signal(
    globus_cond_t *         cond);

It is important to note that this is not a complete set of necessary functions to properly use the threaded API. However, for the purposes of this text, they will serve for an explanation.

globus_thread_create() will start a new thread of execution with a new call stack running beginning at the parameter func.
globus_mutex_lock() and globus_mutex_unlock() provide mutual exclusive among threads over critical sections of code.
globus_cond_wait() and globus_cond_signal() provide a means of thread synchronization.
wait() will delay the thread that calls it until some other thread calls signal().

In most cases the thread layer abstraction is a very thin pass through to the underlying thread package.

The notable exception is the non-threaded build. The Globus Toolkit has created a non-threaded, semantically equivalent implementation of all the functions described above (and of most in the pthreads API) with the exception of globus_thread_create(). In the non-threaded case this is a no-op. However the model of asynchronous programming used in the Globus Toolkit, globus_thread_create() is rarely needed or used.

In the Globus model, the callback code and the thread abstraction are coupled. Example 2 shows how this coupling works:

An event is registered in the main thread, then globus_cond_wait() is called.
When the event has been processed, the handler is called.
The handler signals the wait that it may continue, then exits.
The signal awakens the wait so the main thread may continue.
The main thread then exits.

In the threaded build, globus_cond_wait() and globus_cond_signal() are simple passes through to the underlying thread packages, and as described previously, a background thread delivers the event.

In the non-threaded build, globus_cond_wait() will call globus_poll() and the non-threaded polling code takes over. For this reason, it is often not necessary to call globus_poll() in non-threaded builds. globus_cond_wait() tends to be used often enough to satisfy the needs of the event system.

5. Asynchronous Model

In many ways, the asynchronous programming model is the most difficult of the three presented. The blocking model is clearly the easiest, because everything happens in-line, and when the event function (like a read or a write) returns, the event has completed and all data is available. Events in this model are treated just like any other function call and are therefore easily dealt with by programmers with modest logic skills.

The non-blocking model is a bit more complicated than blocking, but not much. The only twist is that a user must check to see if the event completed and, if so, how much of it completed. This still allows for in-line processing; it only requires an additional if statement. Even when event polling is multiplexed (for example, posix select) the processing is still inline. The user must add some branches to determine what event is ready and then process it. The most difficult challenge of the non-blocking model is making use of the idle time when no events are ready.

In both non-blocking and blocking, the user has easy, in-line control over when an event is processed. If there is any logic that must occur before the event, the user simply needs to complete that processing before calling either the blocking function or the non-blocking function which checks for ready events. The asynchronous model removes this luxury. In the asynchronous model events can occur at any time. This can complicate the logic of keeping critical sections of code safe. Further complication is caused by the fact that they come in via their own handlers. This removes the luxury of maintaining state on the local stack. Instead all state must be packed into heap allocated structures which are passed to the callbacks via void * pointers (see the monitor structure in Example 2).

The upside to the asynchronous model is that it forces cleaner, more well thought out code. The non-blocking model does not scale well. As more events are managed, the event processing code becomes unmanageable, typically resulting in a single function that is far too long and far too interdependent for practical maintenance. Since users can use local variables, the tendency is to use many different flags to control state instead of a clean, well thought out state machine. This is especially true with software that evolves over time, growing in complexity.

In contrast the asynchronous model scales very well. Every event has a clean separation of being scoped to a user handler function. All shared states among events must be encapsulated into a data structure. A side effect of these two characteristics is that it is easier for a user to define and follow a state machine then it is to create spaghetti logic based on many flags.

Example 3 shows a proper use of the asynchronous model. This example simulates the game of Craps. Craps is a dice game, the rules of which can be found with a simple web search, but the following state diagram should explain the rules well enough for this example.

Figure 1. State Diagram

Example 3 follows this state diagram. In the example rolls of the dice are considered events. For the sake of simplicity the example only uses a one shot event and then gets the data by calling random(); If this were a real world event, the values for the dice would come in as part of the event function. Notice how each time the event occurs the state is checked and, if needed, advanced to the next state. In the main function the program waits until the state machine comes to the final stage, where it signals the wait and allows for the program to end.

5.1. Blocking in Callbacks

What happens if an event handler blocks? The correct answer to this question is: They never should. This answer is of course a bit naive. There will be times when blocking in a callback is the only solution, and there will be even more times when it is the chosen solution, albeit the wrong one. Therefore, the Globus Toolkit does have mechanisms to allow this. That said, a user should make every effort to find alternative solutions to blocking in event callbacks. If the only solution is to block in a callback it could be an indication that the state machine is erroneous.

If an event callback is going to block, it must call the following function: void globus_thread_blocking_will_block(); If globus_cond_wait() is called, this function is implied.

In the threaded build of Globus there is a background thread that handles the polling of events and dispatching of the handler functions. When a handler function blocks, it prevents this process. globus_thread_blocking_will_block() starts a new thread to handle event processing and allows the user to take over the current thread without stopping the processing of other threads. The user must also call globus_poll() in order to ensure that event processing continues.

This is needed:

in the threaded case to yield the user's processing thread to the system event thread.
in the non threaded case so that the only thread can make a non-blocking run through of any ready events.

6. Conclusion

The Globus Toolkit is middleware for the grid. Because grid infrastructure often depends heavily on both push and pull notifications (remote events), the callback style event handling model the Globus Toolkit provides is essential. It allows entire APIs within the toolkit to be designed with asynchronous functions that use the event handling model. Once an API provides that asynchronous functionality (such as XIO), software that builds on top of it can leverage this functionality. This eases the burden of the application programmer, as they need only to implement a callback function to handle possibly many notification events efficiently, instead of stopping execution until one is received, or managing multiple threads.

In the Globus Toolkit, because of the thread abstraction it provides, threads are managed by the underlying code base, so that the developer can be ignorant of using threads but still be able to get their benefits, simply by specifying a compile time switch. Overall, this flexibility is quite powerful, which is why we encourage the use of this model when designing and developing your own software components using the Globus Toolkit.

7. References

GT 4.2.0: Asynchronous Event Handling: Example 1

#include <globus_common.h>

void
user_callback(
    void *                              user_arg)
{
    int *                               count;

    count = (int *) user_arg;
    fprintf(stdout, "User callback, count = %d\n", *count);
    exit(0);
}

int
main(
    int                                 argc,
    char **                             argv)
{
    globus_reltime_t                    delay;
    int                                 count = 0;

    globus_module_activate(GLOBUS_COMMON_MODULE);

    GlobusTimeReltimeSet(delay, 1, 0);
    globus_callback_register_oneshot(
        NULL,
        &delay,
        user_callback,
        &count);

    while(1)
    {
        usleep(10000);
        globus_poll_nonblocking();
        fprintf(stdout, "After poll\n");
        count++;
    }

    globus_module_deactivate(GLOBUS_COMMON_MODULE);

    return 0;
}

GT 4.2.0: Asynchronous Event Handling: Example 2

#include <globus_common.h>

struct test_monitor_s
{
    globus_mutex_t                      mutex;
    globus_cond_t                       cond;
    globus_bool_t                       done;
};

void
user_callback(
    void *                              user_arg)
{
    struct test_monitor_s *              monitor;

    monitor = (struct test_monitor_s *) user_arg;

    globus_mutex_lock(&monitor->mutex);
    {
        fprintf(stdout, "Signaling the wait\n");
        monitor->done = GLOBUS_TRUE;
        globus_cond_signal(&monitor.cond);
    }
    globus_mutex_unlock(&monitor->mutex);
}

int
main(
    int                                 argc,
    char **                             argv)
{
    struct test_monitor_s               monitor;
    globus_reltime_t                    delay;

    globus_module_activate(GLOBUS_COMMON_MODULE);

    globus_mutex_init(&monitor.mutex, NULL);
    globus_cond_init(&monitor.cond, NULL);
    monitor.done = GLOBUS_FALSE;

    globus_mutex_lock(&monitor.mutex);
    {
        GlobusTimeReltimeSet(delay, 1, 0);
        globus_callback_register_oneshot(
            NULL,
            &delay,
            user_callback,
            &monitor);

        while(!monitor.done)
        {
            fprintf(stdout, "waiting...\n");
            globus_cond_wait(&monitor.cond, &monitor.mutex);
        }
    }
    globus_mutex_unlock(&monitor.mutex);

    globus_module_deactivate(GLOBUS_COMMON_MODULE);

    fprintf(stdout, "Done\n");

    return 0;
}

GT 4.2.0: Asynchronous Event Handling: Example 3

#include <globus_common.h>
#include <stdlib.h>


typedef enum game_state_e
{
    FIRST_ROLL,
    ROLLING,
    LOST_GAME,
    WON_GAME
} game_state_t;

typedef struct game_context_s
{
    globus_mutex_t                      mutex;
    globus_cond_t                       cond;
    game_state_t                        state;
    int                                 rolls;
    int                                 point;
} game_context_t;

void
event_callback(
    void *                              user_arg)
{
    int                                 die1;
    int                                 die2;
    game_context_t *                    game_context;

    game_context = (game_context_t *) user_arg;

    die1 = rand() % 6 + 1;
    die2 = rand() % 6 + 1;

    globus_mutex_lock(&game_context->mutex);
    {
        game_context->rolls++;
        fprintf(stdout, "you rolled %d and %d, total is %d\n", 
            die1, die2, die1+die2);
        switch(game_context->state)
        {
            case FIRST_ROLL:
                if(die1+die2 == 7 || die1+die2 == 11)
                {
                    game_context->state = WON_GAME;
                    globus_cond_signal(&game_context->cond);
                }
                else if(die1+die2 == 2 || die1+die2 == 3 || die1+die2 == 12)
                {
                    game_context->state = LOST_GAME;
                    globus_cond_signal(&game_context->cond);
                }
                else
                {
                    game_context->state = ROLLING;
                    game_context->point = die1+die2;
                    fprintf(stdout, "The point is: %d\n", game_context->point);
                    globus_callback_register_oneshot(
                        NULL,
                        NULL,
                        event_callback,
                        game_context);
                }
                break;

            case ROLLING:
                if(die1+die2 == 7)
                {
                    game_context->state = LOST_GAME;
                    globus_cond_signal(&game_context->cond);
                }
                else if(die1+die2 == game_context->point)
                {
                    game_context->state = WON_GAME;
                    globus_cond_signal(&game_context->cond);
                }
                else
                {
                    globus_callback_register_oneshot(
                        NULL,
                        NULL,
                        event_callback,
                        game_context);
                }
                break;

            default:
                globus_assert(0 && "should never reach this state");
                break;
        }
    }
    globus_mutex_unlock(&game_context->mutex);
}

int
main(
    int                                 argc,
    char **                             argv)
{
    game_context_t                      game_context;

    globus_module_activate(GLOBUS_COMMON_MODULE);

    globus_mutex_init(&game_context.mutex, NULL);
    globus_cond_init(&game_context.cond, NULL);
    game_context.rolls = 0;
    game_context.state = FIRST_ROLL;

    srandom(time(NULL));

    globus_mutex_lock(&game_context.mutex);
    {
        globus_callback_register_oneshot(
            NULL,
            NULL,
            event_callback,
            &game_context);

        while(game_context.state != LOST_GAME && 
                game_context.state != WON_GAME)
        {
            globus_cond_wait(&game_context.cond, &game_context.mutex);
        }
    }
    globus_mutex_unlock(&game_context.mutex);

    fprintf(stdout, "%s, game over in %d rolls.\n", 
        game_context.state == LOST_GAME ? "You LOSE" : "You WIN", 
        game_context.rolls);

    globus_module_deactivate(GLOBUS_COMMON_MODULE);
    return 0;
}

Globus Toolkit 4.2.0 Commandline Tools

Table of Contents

Java WS Core Commands

globus-start-container - Starts standalone container
globus-stop-container - Stops standalone container
globus-start-container-detached - Starts standalone container detached from controlling TTY
globus-stop-container-detached - Stops standalone container detached from controlling TTY
wsrf-destroy - Destroys a resource
wsrf-set-termination-time - Sets termination time of a resource
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
wsrf-insert-property - Inserts values into a resource property
wsrf-update-property - Updates value of a resource property
wsrf-delete-property - Deletes a resource property
wsn-get-current-message - Gets a current message associated with a topic
wsn-pause-subscription - Pauses a subscription
wsn-resume-subscription - Resumes a subscription
wsn-subscribe - Subscribes to a topic
globus-deploy-gar - Deploys a GAR file (locally)
globus-undeploy-gar - Undeploys a GAR file (locally)
globus-check-environment - Displays component version information and validates JVM version.
globus-check-remote-environment - Displays remote component version information.
globus-update-client-config - Merges client-config.wsdd files from deployed modules into the global client-config.wsdd configuration file
globus-validate-descriptors - Validate configuration files of all services
globus-reload-container - Reinitializes standalone container
globus-remote-undeploy-gar - Undeploys a GAR file (remotely)
globus-remote-deploy-gar - Deploys a GAR file (remotely)
ws-enumerate-start - Starts an enumeration
ws-enumerate - Retrieves enumeration data
ws-enumerate-end - Stops an enumeration
globus-xpath-query - Performs XPath query on a resource property document
Common Java Client Options - list of common options across commands

C WS Core Commands

globus-wsc-container - Host C web services
globus-wsrf-cgen - Generate Stubs/Skeletons in C
globus-wsrf-destroy - Set the scheduled termination time for a WSRF resource.
globus-wsrf-set-termination-time - Set the scheduled termination time for a WSRF resource.
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
globus-wsrf-insert-property - Insert a resource property value
globus-wsrf-update-property - Update a resource property value
globus-wsrf-delete-property - Delete a resource property
globus-wsn-get-current-message - Get the current message associated with a specified topic
globus-wsn-pause-subscription - Pause a WSRF notification subscription.
globus-wsn-resume-subscription - Resume a WSRF notification subscription.
globus-wsn-subscribe - Subscribe for notification for a specified topic.

GSI Commands

grid-cert-diagnostics - Print diagnostic information about certificates and keys
grid-cert-info - Display certificate information
grid-cert-request - Create a certificate request
grid-default-ca - Set the default CA to use for certificate requests
grid-change-pass-phrase - Change the pass phrase on a private key
grid-proxy-init - Generate a new proxy certificate
grid-proxy-destroy - Destroy the current proxy certificate (previously created with grid-proxy-init)
grid-proxy-info - Display information obtained from a proxy certificate
grid-mapfile-add-entry - Add an entry to a grid map file
grid-mapfile-check-consistency - Check the internal consistency of a grid map file
grid-mapfile-delete-entry - Delete an entry from a grid map file

CAS Query Commands

cas-whoami - Getting a user's CAS identity.
cas-list-object - Getting object list
cas-get-object - Getting CAS object
cas-group-list-entries - Getting group members
cas-find-policies - Getting policy information
query-cas-service - Query CAS Service (using OGSA AuthZ interface)

CAS Admin Commands

cas-proxy-init - Generate a CAS proxy
cas-wrap - Runs program with CAS credentials
cas-enroll - Enroll a CAS Object
cas-remove - Remove a CAS object from the database
cas-action - Maintains service types
cas-group-admin - Maintains user groups, object groups, or serviceAction groups
cas-group-add-entry - Adds CAS objects to CAS groups
cas-group-remove-entry - Removing CAS objects from CAS groups
cas-rights-admin - Granting or revoking permissions

Delegation Service Commands

globus-credential-delegate - Delegation client
globus-credential-refresh - Delegation refresh client
globus-delegation-client - C Delegation client

GridFTP Commands

globus-url-copy - Multi-protocol data movement
globus-gridftp-server - Configures the GridFTP Server

RFT Commands

rft - Submit and monitor a 3rd party GridFTP transfer
globus-crft - Command-line client to transfer files using RFT
rft-delete - Command-line client to delete files using RFT

Replica Location Service (RLS) Commands

globus-rls-admin - RLS administration tool
globus-rls-cli - RLS client tool
globus-rls-server - RLS server tool

WS RLS Commands

globus-replicalocation-createmappings - This tool is used to create mappings between logical names and target names. The create semantic implies that the logical name does not exist at the time of invocation.
globus-replicalocation-addmappings - This tool is used to add mappings between logical names and target names. The add semantic implies that the logical name does exist at the time of invocation.
globus-replicalocation-deletemappings - This tool is used to delete mappings between logical names and target names.
globus-replicalocation-defineattributes - This tool is used to define attributes.
globus-replicalocation-undefineattributes - This tool is used to undefine attributes.
globus-replicalocation-addattributes - This tool is used to add attributes.
globus-replicalocation-modifyattributes - This tool is used to modify attributes.
globus-replicalocation-removeattributes - This tool is used to remove existing attributes.

WS MDS Commands

mds-servicegroup-add - Registering grid resources to aggregating MDS services such as the Index, Archive and Trigger services
mds-set-multiple-termination-time - Administering the termination time of grid resources created by aggregating MDS services such as the Index and Trigger services

GRAM4 Commands

globusrun-ws - Official job submission client for GRAM4

Java WS Core Commands

These command line tools are available on Unix and Windows platforms and will work in the same way (of course within the platform rules - the path syntax, variable definitions, etc.).

The wsrf-* and wsn-* clients should work against any service that supports the given WSRF or WSN operations.

Table of Contents

globus-start-container - Starts standalone container
globus-stop-container - Stops standalone container
globus-start-container-detached - Starts standalone container detached from controlling TTY
globus-stop-container-detached - Stops standalone container detached from controlling TTY
wsrf-destroy - Destroys a resource
wsrf-set-termination-time - Sets termination time of a resource
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
wsrf-insert-property - Inserts values into a resource property
wsrf-update-property - Updates value of a resource property
wsrf-delete-property - Deletes a resource property
wsn-get-current-message - Gets a current message associated with a topic
wsn-pause-subscription - Pauses a subscription
wsn-resume-subscription - Resumes a subscription
wsn-subscribe - Subscribes to a topic
globus-deploy-gar - Deploys a GAR file (locally)
globus-undeploy-gar - Undeploys a GAR file (locally)
globus-check-environment - Displays component version information and validates JVM version.
globus-check-remote-environment - Displays remote component version information.
globus-update-client-config - Merges client-config.wsdd files from deployed modules into the global client-config.wsdd configuration file
globus-validate-descriptors - Validate configuration files of all services
globus-reload-container - Reinitializes standalone container
globus-remote-undeploy-gar - Undeploys a GAR file (remotely)
globus-remote-deploy-gar - Deploys a GAR file (remotely)
ws-enumerate-start - Starts an enumeration
ws-enumerate - Retrieves enumeration data
ws-enumerate-end - Stops an enumeration
globus-xpath-query - Performs XPath query on a resource property document
Common Java Client Options - list of common options across commands

Name

globus-start-container — Starts standalone container

Synopsis

globus-start-container

Tool description

Starts a standalone container. By default a secure container is started on port 8443 and is accessible via HTTPS. On successful startup a list of services will be displayed on the console. By default the non secure (HTTP) container is started on port 8080.

Command syntax

 globus-start-container [options]

Table 1. Options

-help	Displays help information about the command.
-p <port>	Sets the port number for the container.
-i <address>	Binds container to the specified network address.
-quiet	Does not show a list of services at startup.
-debug	Enables debug mode.
-nosec	Starts a non secure (HTTP) container. Please note that this option only disables transport security. Message security can still be used.
-containerDesc <file>	Specifies a container security descriptor file.
-profile <name>	Specifies a configuration profile name for the container.

Name

globus-stop-container — Stops standalone container

Synopsis

globus-stop-container

Tool description

Stops a standalone container. By default this command will attempt to stop a container running on localhost:8443 and perform a soft shutdown.

The globus-stop-container command invokes a ShutdownService running in the container. By default that service is configured to perform self authorization and therefore the globus-stop-container must be executed with the same credentials as the container it is running with. Alternatively, the service can be configured with a gridmap file to allow a subset of users (with their own credentials) to invoke the service (please see the service security deployment descriptor for details).

Command syntax

globus-stop-container [options] ['soft' | 'hard']

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.

Table 3. Shutdown options

'soft'	This option lets the threads die naturally.
'hard'	This option forces an immediate JVM shutdown.

Example:

 $ globus-stop-container soft

Please see the troubleshooting section if you are having problems with globus-stop-container.

Name

globus-start-container-detached — Starts standalone container detached from controlling TTY

Synopsis

globus-start-container-detached

Tool description

Starts a standalone container detached from the controlling TTY. This can be useful for long running containers or when started from init.d scripts. Container log goes to $GLOBUS_LOCATION/var/container.log and a PID file is written to $GLOBUS_LOCATION/var/container.pid. globus-start-container-detached is just a wrapper around globus-start-container so see globus-start-container for more information and options.

	Note
	Note that this tool is only available after doing a full Globus install. It is not available in Java WS Core only installs.

Command syntax

 globus-start-container-detached [options] | [arguments to container]

Table 4. Options

-logfile <file>	Specifies an alternate container log file.
-append	Do not overwrite the existing log file.
-pidfile <file>	Specifies an alternate PID file location.

Name

globus-stop-container-detached — Stops standalone container detached from controlling TTY

Synopsis

globus-stop-container-detached

Tool description

Stops a standalone container detached from the controlling TTY. $GLOBUS_LOCATION/var/container.pid is used to find the PID of the running container and signals are sent to stop the container.

	Note
	Note that this tool is only available after doing a full Globus install. It is not available in Java WS Core only installs.

Command syntax

 globus-stop-container-detached [options]

Table 5. Options

-pidfile <file>

Specifies an alternate PID file location.

Name

wsrf-destroy — Destroys a resource

Synopsis

wsrf-destroy

Tool description

Destroys a resource.

Command syntax

wsrf-destroy [options]

Table 6. 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-destroy -s http://localhost:8080/wsrf/services/CounterService \ -k
    "{http://counter.com}CounterKey" 123

Name

wsrf-set-termination-time — Sets termination time of a resource

Synopsis

wsrf-set-termination-time

Tool description

Sets a termination time of a resource.

Command syntax

wsrf-set-termination-time [options] <seconds> | 'infinity'

The following are command-specific options in addition to the common options:

Table 7. Command-specific options

-u, --utc

Display time in UTC.

Table 8. 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-set-termination-time -s http://localhost:8080/wsrf/services/CounterService \ -k
    "{http://counter.com}CounterKey" 123 30

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 9. 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 10. 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 11. 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

wsrf-insert-property — Inserts values into a resource property

Synopsis

wsrf-insert-property

Tool description

Inserts a property into the resource property document of a resource.

Command syntax

wsrf-insert-property [options] <propertyValueFile>

The <propertyValueFile> is an XML file that contains the value of the resource property. The QName of the property is the outer most element.

Table 12. 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: Contents of in.xml:

 <doc> <ns1:Foo xmlns:ns1="http://widgets.com"> Value1
    </ns1:Foo> <ns1:Foo xmlns:ns1="http://widgets.com"> Value2
    </ns1:Foo> </doc>

 $ wsrf-insert-property -s http://localhost:8080/wsrf/services/WidgetService \ -k
    "{http://www.globus.org/namespaces/2004/06/core}WidgetKey" 123 \ in.xml

Name

wsrf-update-property — Updates value of a resource property

Synopsis

wsrf-update-property

Tool description

Updates the property value in the resource property document of a resource.

Command syntax

wsrf-update-property [options] <propertyValueFile>

The <propertyValueFile> is an XML file that contains the value of the resource property. The QName of the property is the outermost element.

Table 13. 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: Contents of in.xml:

 <doc> <ns1:Foo xmlns:ns1="http://widgets.com"> Value
    </ns1:Foo> </doc>

 $ wsrf-update-property -s http://localhost:8080/wsrf/services/WidgetService \ -k
    "{http://www.globus.org/namespaces/2004/06/core}WidgetKey" 123 \ in.xml

Name

wsrf-delete-property — Deletes a resource property

Synopsis

wsrf-delete-property

Tool description

Deletes a resource property from the resource property document of a resource.

Command syntax

wsrf-delete-property [options] <property>

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

Table 14. 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-delete-property -s http://localhost:8080/wsrf/services/WidgetService \ -k
    "{http://www.globus.org/namespaces/2004/06/core}WidgetKey" 123 \
   "{http://widgets.com}Foo"

Name

wsn-get-current-message — Gets a current message associated with a topic

Synopsis

wsn-get-current-message

Tool description

Gets the current message associated with the specified topic.

Command syntax

wsn-get-current-message [options] <topic>

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

Table 15. 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:

 $ wsn-get-current-message -s
     http://localhost:8080/wsrf/services/CounterService \ -k "{http://counter.com}CounterKey" 123 \
     "{http://counter.com}Value"

Name

wsn-pause-subscription — Pauses a subscription

Synopsis

wsn-pause-subscription

Tool description

Pauses a subscription (notifications on that subscription will not be sent out until it is resumed).

Command syntax

wsn-pause-subscription [options]

Table 16. 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:

 $ wsn-pause-subscription -s
    http://localhost:8080/wsrf/services/SubscriptionManagerService \ -k
    "{http://www.globus.org/namespaces/2004/06/core}acc271c0-4df9-11d9-ab19-87da3bc7cf28"

Name

wsn-resume-subscription — Resumes a subscription

Synopsis

wsn-resume-subscription

Tool description

Resumes a subscription (notifications on that subscription will be sent out again).

Command syntax

wsn-resume-subscription [options]

Table 17. 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:

 $ wsn-resume-subscription -s
    http://localhost:8080/wsrf/services/SubscriptionManagerService \ -k
    "{http://www.globus.org/namespaces/2004/06/core}acc271c0-4df9-11d9-ab19-87da3bc7cf28"

Name

wsn-subscribe — Subscribes to a topic

Synopsis

wsn-subscribe

Tool description

Subscribes to a topic.

Command syntax

wsn-subscribe [options] <topic>

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

The following are subscribe-specific options in addition to the common options:

Table 18. Command-specific options

-r, --resDescFile <file>	Specifies a file containing a resource security descriptor for the notification consumer resource.
-b, --subEpr <file>	Specifies a file to which the subscription resource EPR will be saved.

Table 19. 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:

 $ wsn-subscribe -s http://localhost:8080/wsrf/services/CounterService \ -k
    "{http://counter.com}CounterKey" 123 \ "{http://counter.com}Value"

Name

globus-deploy-gar — Deploys a GAR file (locally)

Synopsis

globus-deploy-gar

Tool description

Deploys a GAR file (locally) into Java WS Core or Apache Tomcat container.

Command syntax

globus-deploy-gar [options] <gar.file>

The <gar.file> is the path to the GAR file to be deployed.

Table 20. Options

-help	Displays help information about the command.
-debug	Enables debug mode.
-verbose	Enables verbose mode.
-backup	Creates backup of existing configuration files.
-overwrite	Overwrite existing deployment.
-profile <name>	Specifies the profile name under which the configuration files in the GAR will be deployed. Please see "Configuration Profiles" under Configuring Java WS Core for details.
-tomcat <dir>	Deploys a GAR file to Apache Tomcat. The `<dir>` argument must point to the Tomcat installation directory. Note: Java WS Core must be already deployed in Tomcat. Please see Deploying into Tomcat section for details.
-D<property>=<value>	Passes arbitrary property-value pairs. See below for the list of currently supported properties.

Table 21. Supported property-value pairs

-Dall.scripts=true	Causes Windows and Unix launcher scripts to be generated.
-DdoValidation=false	Turns off automatic validation of service configuration files.

	Note
	Since GT 4.2, globus-deploy-gar command will NOT overwrite the existing deployment unless `-overwrite` option is specified. It is recommended to undeploy the existing deployment first. The container must be off to deploy a GAR file.

Example I:

 $ globus-deploy-gar /tmp/gars/globus_wsrf_core_samples_counter.gar

The above command will deploy the globus_wsrf_core_samples_counter.gar into Java WS Core installation directory. The above command invokes the deployGar task in the build-packages.xml Ant build file. The above example is equivalent to running:

 $ ant -f $GLOBUS_LOCATION/share/globus_wsrf_common/build-packages.xml deployGar \
    -Dgar.name=/tmp/gars/globus_wsrf_core_samples_counter.gar

The profile name can be passed using the -Dprofile Ant option. To enable back up of the existing configuration files add the -DcreateBackup=true Ant option. Make sure to use the absolute path name for the gar file when using Ant directly.

Example II:

 $ globus-deploy-gar -tomcat /soft/tomcat-5.5.20 \
    /tmp/gars/globus_wsrf_core_samples_counter.gar

The above command will deploy the globus_wsrf_core_samples_counter.gar into Apache Tomcat. The above command invokes the deployGar task in the tomcat-service.xml Ant build file. The above example is equivalent to running:

 $ ant -f $GLOBUS_LOCATION/share/globus_wsrf_common/tomcat/tomcat-service.xml deployGar \
    -Dgar.name=/tmp/gars/globus_wsrf_core_samples_counter.gar \ -Dtomcat.dir=/soft/tomcat-5.5.20

By default the GAR file will be deployed under the "wsrf" web application. To specify a different web application name use -Dwebapp.name=<name> option.

Name

globus-undeploy-gar — Undeploys a GAR file (locally)

Synopsis

globus-undeploy-gar

Tool description

Undeploys a GAR file (locally) from Java WS Core or Apache Tomcat container.

Command syntax

 globus-undeploy-gar [options] <gar.id>

The <gar.id> is the base name of the GAR file without the .gar extension to undeploy. For example if the GAR file is "foo.gar", then the GAR id is "foo". The directory names under $GLOBUS_LOCATION/etc/globus_packages/ are the GAR ids of the undeployable items.

Table 22. Options

-help	Displays help information about the command.
-debug	Enables debug mode.
-verbose	Enables verbose mode.
-tomcat <dir>	Undeploy a GAR file from Apache Tomcat. The `<dir>` argument must point to the Tomcat installation directory.
-D<property>=<value>	Passes arbitrary property-value pairs.

	Note
	The container must be off to undeploy a GAR file.

Example I:

 $ globus-undeploy-gar globus_wsrf_core_samples_counter

The above command will undeploy globus_wsrf_core_samples_counter GAR from Java WS Core installation directory. The above command invokes the undeployGar task in the build-packages.xml Ant build file. The above example is equivalent to running:

 $ ant -f $GLOBUS_LOCATION/share/globus_wsrf_common/build-packages.xml undeployGar \
    -Dgar.id=globus_wsrf_core_samples_counter

Example II:

 $ globus-undeploy-gar -tomcat /soft/tomcat-5.5.20 \ globus_wsrf_core_samples_counter

The above command will undeploy globus_wsrf_core_samples_counter GAR from Apache Tomcat. The above command invokes the undeployGar task in the tomcat-service.xml Ant build file. The above example is equivalent to running:

 $ ant -f $GLOBUS_LOCATION/share/globus_wsrf_common/tomcat/tomcat-service.xml undeployGar
    \ -Dgar.id=globus_wsrf_core_samples_counter \ -Dtomcat.dir=/soft/tomcat-5.5.20

By default the GAR file will be undeployed under the "wsrf" web application. To specify a different web application name use -Dwebapp.name=<name> option.

Name

globus-check-environment — Displays component version information and validates JVM version.

Synopsis

globus-check-environment

Tool description

Displays component version information and validates the JVM version. This tool is primarily used for debugging purposes.

Name

globus-check-remote-environment — Displays remote component version information.

Synopsis

globus-check-remote-environment

Tool description

Displays remote component version information.

Command syntax

 globus-check-environment [-help] -s endpoint -z authz

Table 23. Options

-help	Displays help information about the command.
-s endpoint	Remote endpoint to print vesion information about. It should be of the format protocol://host:port, example https://localhost:8443.
-z authz	Sets authorization, can be 'self', 'host', 'hostOrSelf' or 'none' or a string specifying the expected identity of the remote party. Defaults to no authorization.

Name

globus-update-client-config — Merges client-config.wsdd files from deployed modules into the global client-config.wsdd configuration file

Synopsis

globus-update-client-config

Tool description

Merges multiple client-config.wsdd files from deployed modules into the global configuration file. Scans each $GLOBUS_LOCATION/etc/<modulename>/client-config.wsdd and merges the contents into $GLOBUS_LOCATION/client-config.wsdd This tool is primarily intended for use by administrators and automation tools to facilitate the adding and removing of module specific type-mapping and/or other client-side configuration from the global client-config.wsdd file used by the Globus installation.

Command syntax

 globus-update-client-config [<filename>]

Table 24. Options

<filename>

Optional argument that specifies an alternate path to write the result client-config.wsdd file. By default, running the program with no arguments will write the file to $GLOBUS_LOCATION/client-config.wsdd

Name

globus-validate-descriptors — Validate configuration files of all services

Synopsis

globus-validate-descriptors

Tool description

Validates the Web Services Deployment Descriptor (.wsdd) files, JNDI configuration files (jndi-config.xml), and security descriptors for all services.

Command syntax

 globus-validate-descriptors [options]

Table 25. Options

-help	Displays help information about the command.
-debug	Enables debug mode.
-verbose	Enables verbose mode.
-D<property>=<value>	Passes arbitrary property-value pairs.

Name

globus-reload-container — Reinitializes standalone container

Synopsis

globus-reload-container

Tool description

Invokes the reload() operation on the DeployService running in the remote container. It tells the container to reinitialize all of its services, re-read its and service configuration files, etc. For example, the administrator can change the security descriptor of a service and then use the globus-reload-container command to force the container to load the updated configuration without restarting the container.

By default the DeployService is configured to perform self authorization and therefore the globus-reload-container must be executed with the same credentials as the container it is running with. Alternatively, the service can be configured with a gridmap file to allow a subset of users (with their own credentials) to invoke the service (please see the service security deployment descriptor for details).

	Note
	This command only works with the standalone container. Please see the Java WS Core Dynamic Deploy Design Document for more information.

Command syntax

globus-reload-container [options]

Table 26. 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:

 $ globus-reload-container

Name

globus-remote-undeploy-gar — Undeploys a GAR file (remotely)

Synopsis

globus-remote-undeploy-gar

Tool description

The globus-remote-undeploy-gar command undeploys a GAR file remotely. It invokes the undeploy() operation on the DeployService running in the remote container. It works just like the globus-undeploy-gar command but the GAR file is undeployed remotely.

By default the DeployService is configured to perform self authorization and therefore the globus-remote-undeploy-gar must be executed with the same credentials as the container it is running with. Alternatively, the service can be configured with a gridmap file to allow a subset of users (with their own credentials) to invoke the service (please see the service security deployment descriptor for details).

	Note
	This command only works with the standalone container. Please see the Java WS Core Dynamic Deploy Design Document for more information.

Command syntax

globus-remote-undeploy-gar [options] <gar.id>

The <gar.id> is the base name of the GAR file without the .gar extension to undeploy. For example if the GAR file is "foo.gar", then the GAR id is "foo".

Table 27. 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:

 $ globus-remote-undeploy-gar globus_wsrf_core_samples_counter

To see what GAR files can be undeployed on the remote container run the following query on the DeployService, for example:

 $ wsrf-query -z hostSelf -s https://127.0.0.1:8443/wsrf/services/DeployService

Name

globus-remote-deploy-gar — Deploys a GAR file (remotely)

Synopsis

globus-remote-deploy-gar

Tool description

The globus-remote-deploy-gar command deploys a GAR file remotely. It first transfers the GAR file to the DeployService running in the remote container and then it deploys it using the deploy() operation of the service (the tool can also perform these two operations separately).

By default the DeployService is configured to perform self authorization and therefore the globus-remote-deploy-gar must be executed with the same credentials as the container it is running with. Alternatively, the service can be configured with a gridmap file to allow a subset of users (with their own credentials) to invoke the service (please see the service security deployment descriptor for details).

	Note
	This command only works with the standalone container. Please see the Java WS Core Dynamic Deploy Design Document for more information.

Command syntax

globus-remote-deploy-gar [options] <gar>

The <gar> can be either an URL or a file location. If a file location is passed to the tool, it will transfer the file to the service via SOAP with Attachments (the upload() function) using the MTOM format. If an URL is passed, the tool will call the download() function of the service, and let the service download the GAR file.

The following are command-specific options in addition to the common options:

Table 28. Command-specific options

-n, --transfer	Transfer GAR file only.
-y, --deploy	Deploy GAR file only (assumes the GAR is already transferred to the DeployService.
-o, --overwrite	Overwrite existing deployment.
-b, --backup	Creates backup of existing configuration files

Table 29. 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:

 $ globus-remote-deploy-gar /tmp/myServie.gar

 $ globus-remote-deploy-gar gsiftp://localhost/tmp/myServie.gar

To see what GAR files haven been transfered but not yet deployed on the remote container run the following query on the DeployService, for example:

 $ wsrf-query -z hostSelf -s https://127.0.0.1:8443/wsrf/services/DeployService

Name

ws-enumerate-start — Starts an enumeration

Synopsis

ws-enumerate-start

Tool description

Creates a new enumeration context and prints it out to the console.

	Note
	The remote service must support the enumerate operation of the WS-Enumeration specification.

Command syntax

ws-enumerate-start [options]

Table 30. 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:

 $ ws-enumerate-start -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    > enum.context

The created enumeration context will be stored in the enum.context file which then can be passed to ws-enumerate and ws-enumerate-end command line clients.

Name

ws-enumerate — Retrieves enumeration data

Synopsis

ws-enumerate

Tool description

Retrieves the next set of enumeration data and prints it out to the console.

	Note
	The remote service must implement the WS-Enumeration specification.

Command syntax

ws-enumerate [options] <enumContextFile>

The <enumContextFile> is a file that contains the enumeration context.

The following are command-specific options in addition to the common options:

Table 31. Command-specific options

-i, --items <int>	Specifies the total number of enumeration items to retrieve. The parameter value can be 'all' to retrieve the all the enumeration data. By default, only one element is retrieved.
-r, --maxCharacters <int>	Specifies the maximum number of characters (in Unicode) of the enumeration data that the client can accept at a time. By default, there is no limit on the size of the elements.
-n, --maxElements <int>	Specifies the maximum number of enumeration items to fetch at a time. By default, one element is retrieved at a time.
-o, --maxTime <int>	Specifies the maximum amount of time (in milliseconds) in which the enumeration data must be assembled. By default, there is no time limit.

Table 32. 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:

 $ ws-enumerate -s http://localhost:8080/wsrf/services/ContainerRegistryService \ -i 10
    -n 5 enum.context

This command will display 10 elements of the enumeration data obtaining 5 elements at a time from the service.

Name

ws-enumerate-end — Stops an enumeration

Synopsis

ws-enumerate-end

Tool description

Releases an enumeration context.

	Note
	The remote service must implement the WS-Enumeration specification.

Command syntax

ws-enumerate-end [options] <enumContextFile>

The <enumContextFile> is a file that contains the enumeration context.

Table 33. 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:

 $ ws-enumerate-end -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    enum.context

Name

globus-xpath-query — Performs XPath query on a resource property document

Synopsis

globus-xpath-query

Tool description

The globus-xpath-query uses a custom query dialect implementation called TargetedXPath to query the resource property document of a resource. Please see the querying resource properties using XPath section for more details.

Command syntax

globus-xpath-query [options] [query expression] [rpQName]

The query expression is an XPath expression. The rpQName is a resource property QName. If a resource property is specified only that resource property within the resource property document will be queried. Otherwise, the entire resource property document will be queried. By default, a simple XPath query is assumed that returns the entire resource property document.

Table 34. Command-specific options

-n, --nsMapFile <file>	Specifies a file that contains namespace mappings. By default, the `etc/globus_wsrf_core/namespace-mappings.xml` file is used.
-u, --enumerate	Enumerate the query results. The query response will contain an enumeration context through which the actual query results can be obtained. The returned enumeration context can be used with the ws-enumerate command line tool. Also, please note that by default the enumeration context will expire in 30 minutes.

Table 35. 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:

 $ globus-xpath-query -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    "//wssg:MemberServiceEPR/wsa:Address"

The above command will query the entire resource property document of the service.

 $ globus-xpath-query -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    "//wssg:MemberServiceEPR/wsa:Address" wssg:Entry

The above command will query only the wssg:Entry resource property of the resource property document of the service.

 $ globus-xpath-query -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    -u "//wssg:MemberServiceEPR/wsa:Address" > enum.context $ ws-enumerate
    -s http://localhost:8080/wsrf/services/ContainerRegistryService \ -i all enum.context

The first command will create an enumeration for the query results and store the returned enumeration context in a file. The second command will use the enumeration context stored in that file to retrieve the actual query results.

Name

Common Java Client Options — list of common options across commands

Common Java Client Options

Table 36. 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.

C WS Core Commands

Table of Contents

globus-wsc-container - Host C web services
globus-wsrf-cgen - Generate Stubs/Skeletons in C
globus-wsrf-destroy - Set the scheduled termination time for a WSRF resource.
globus-wsrf-set-termination-time - Set the scheduled termination time for a WSRF resource.
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
globus-wsrf-insert-property - Insert a resource property value
globus-wsrf-update-property - Update a resource property value
globus-wsrf-delete-property - Delete a resource property
globus-wsn-get-current-message - Get the current message associated with a specified topic
globus-wsn-pause-subscription - Pause a WSRF notification subscription.
globus-wsn-resume-subscription - Resume a WSRF notification subscription.
globus-wsn-subscribe - Subscribe for notification for a specified topic.

Name

globus-wsc-container — Host C web services

Synopsis

globus-wsc-container [-help] [-usage] [-version]
[-bg] [-pidfile PID]
[-max MAX-SESSIONS]
[-port PORT]
[-log LOGPATH]
[-nosec]

Description

The globus-wsc-container is a stand-alone SOAP service hosting container. It listens for SOAP / HTTP operation requests on a network port and dispatches those to dynamically loaded service modules. By default, globus-wsc-container will process SOAP messages until it receives a SIGINT or SIGTERM signal. In interactive usage, it typically runs until the user enters Ctrl+C on the keyboard.

The full set of command-line options to globus-wsc-container are:

-help	Display a help message and exit
-usage	Display a short usage message and exit
-version	Display the program version and exit
-bg	Run the program as a daemon
-pid `PIDFILE`	Write the process ID of the program to `PIDFILE`
-max `MAX-SESSIONS`	Allow at most `MAX-SESSIONS` concurrent sessions to be processed by the program
-port `PORT`	Listen for SOAP/HTTP(s) connections on TCP port `PORT`
-log `LOGPATH`	Log container information to `LOGPATH`
-nosec	Disable TLS

By default, the globus-wsc-container program picks an anonymous TCP port within values specified by the GLOBUS_TCP_PORT_RANGE environment variable, if present. To choose a specific port to listen on, pass the option -port PORT on the command-line of the process.

The globus-wsc-container program can also be run in the background as a daemon. This is done by passing the -bg command-line option. This can be combined with the -pidfile PID option to run in the background and record the PID of the process in a file, so that the daemon can be easily terminated.

By default, the container uses TLS for SOAP requests over https. This can be disabled to use unprotected http by passing the -nosec command-line option to this program. Message-level security may be enabled on a per-service basis if this is used.

To enable CEDPs "best practices" logging, pass the -log LOGPATH option to the container. The log file will contain name=value pairs for all events that the container processes.

By default the container will accept as many SOAP connections as the operating system will allow. To throttle the number of outstanding connections that can be processed in parallel, use the -max MAX-SESSIONS command-line option.

Services

The container looks for services in dynamic modules located in the $GLOBUS_LOCATION/lib/globus_service_modules directory. The Globus Toolkit ships with a number of sample services, test services, and implementations of the core WSRF services for implementing Resource Properties, Resource Lifetime, Service Groups, and Notifications. The globus-wsrf-cgen command parses WSDL schemas and generates service skeletons which can be used to implement additional web services.

Examples

Start a container in the foreground on port 8443:

% globus-wsc-container -port 8443

Contact: https://grid.example.org:8443/

Star a container as a daemon on an anonymous port, with a maximum of 64 parallel sessions, recording the port number to a file and logging to another file.

% globus-wsc-container \
    -bg \
    -pidfile $GLOBUS_LOCATION/var/globus-wsc-container.pid \
    -log $GLOBUS_LOCATION/var/globus-wsc-container.log \
    -max 64
    > $GLOBUS_LOCATION/var/globus-wsc-container.contact


% cat $GLOBUS_LOCATION/var/globus-wsc-container.contact

Contact: https://grid.example.org:18332/

% cat $GLOBUS_LOCATION/var/globus-wsc-container.log


ts=2008-06-19T22:43:21.645807Z id=21475 event=globus_service_engine.start engine_id=40235 contact=https://grid.example.org:18332/

Name

globus-wsrf-cgen — Generate Stubs/Skeletons in C

Synopsis

globus-wsrf-cgen [-help] [-dr]
[-s PACKAGE-NAME] [-sn SERVICE-NAME] [-d DIRECTORY] [-flavor FLAVOR] [-lang [ c | cpp ]]
[-p PREFIX-MAP-FILE] [-P NAMESPACE=PREFIX]
[-n NAMESPACE-FILE] [-N NAMESPACE]
[-g NAMESPACE-FILE] [-G NAMESPACE] [-gg]
[-np] [-nb] [-nk] [-ns] [-nc] [-no-sources] [-nt] [-nf FUNCTION]
[-extra-cppflags CPPFLAGS] [-extra-ldflags LDFLAGS] [-extra-libs LIBS]
SCHEMA-FILENAME...

Description

The globus-wsrf-cgen tool generates C-language bindings from WSDL and XML Schema files. The input SCHEMA-FILENAME value should be either a WSDL document containing a service description or an XML schema file containing type definitions.

If a WSDL Schema file is specified as input, globus-wsrf-cgen generates a GPT source package containing client stubs, service skeleton and stubs, and type bindings for included schema types. If an XML Schema file is specified as input, it generates a GPT source package containing type bindings. A full description of the generated files is part of the WSDL to C mapping document.

The full set of command-line options to globus-wsrf-cgen are:

-help	Display a help message and exit
-dr	Dry-run: parse the command-line options and display the command-line arguments to the globus-wsdl-parser program.
-s `PACKAGE-NAME`	Use `PACKAGE-NAME`_bindings as the name for the generated GPT package
-sn `SERVICE-NAME`	Use `SERVICE-NAME` as the name of the service instead of the name in the WSDL schema document.
-d `DIRECTORY`	Generate the GPT source package in `DIRECTORY`, creating it if does not exist.
-flavor `FLAVOR`	Build the package using the `FLAVOR` GPT flavor
-lang `LANG`	Create the service implementation file with the extension matching `LANG`, either "c" or "cpp". See the limitations section for more details.
-p `PREFIX-MAP-FILE`	Use the contents of `PREFIX-MAP-FILE` to define the set of strings to prepend to elements, attributes, and types in various XML namespaces. See the namespace handling section of this document for more details.
-P `NAMESPACE=PREFIX`	Prepend element, attribute, and type names in the XML namespace `NAMESPACE` with the string `PREFIX`. See the namespace handling section of this document for more details.
-n `NAMESPACE-FILE`	Generate bindings for schemas in the XML namespaces contained in the `NAMESPACE-FILE`. See the namespace handling section of this document for more details.
-N `NAMESPACE`	Generate bindings for schemas in the XML namespace `NAMESPACE`. See the namespace handling section of this document for more details.
-g `NAMESPACE-FILE`	Do not generate bindings for schemas in the XML namespaces contained in the `NAMESPACE-FILE`. See the namespace handling section of this document for more details.
-G `NAMESPACE`	Do not generate bindings for schemas in the XML namespace `NAMESPACE`. See the namespace handling section of this document for more details.
-gg	Do not generate bindings for core WSRF namespaces. (Used internally only)
-np	Do not generate a GPT package. Only create source files from the schemas. Implies -nb.
-nb	Do not attempt to run configure and make dist on the generated GPT source package.
-nk	Do not generate a skeleton service implementation. Used in Makefiles for packages that want to generate the types at build time, but already contain a full implementation of the service.
-ns	Do not generate service bindings and skeletons. Useful for creating types- or client-only packages.
-nc	Do not generate client bindings. Useful for creating types- or service-only packages.
-nt	Do not generate type bindings. Useful for creating separate service or client bindings that depend on a common types package.
-no-sources	Delay generating C source files until the package is built. By default the package Makefile contains a list of source files. This option delays the creation of the files and the list until build time. This can be used to avoid storing dynamic files in a version control system.
-nf `FUNCTION`	Do not generate an implementation of `FUNCTION`. This is useful if extra semantic information is needed to serialize or deserialize a particular data type (for example, the wsnt:TopicExpressionType requires different processing based on the value of the Dialect
-extra-cppflags `CPPFLAGS`	Add `CPPFLAGS` to the preprocessor command-line for this package.
-extra-ldflags `LDFLAGS`	Add `LDFLAGS` to the linker command-line for this package.
-extra-libs `LIBS`	Add `LIBS` to the libraries to link with this package.

Namespace Handling

XML and WSDL schemas generally contain a targetNamespace attribute which distinguishes operations, elements, attributes, type, etc from others with the same name. The C language does not define namespaces. globus-wsrf-cgen instead uses prefixes to distinguish similarly-named data types and functions. There are two ways to define a namespace prefix with globus-wsrf-cgen. The -P command-line option defines a single namespace prefix, and the -p command-line option instructs globus-wsrf-cgen to load a set of prefix definitions from a file (one per line).

For example, consider the namepace http://counter.com from the sample CounterService. In the schema for that service, there is an element named Value. the command-line option -P http://counter.com=counter_ will cause globus-wsrf-cgen to generate bindings for that element with the name counter_Value.

If a service is built from several namespaces it might make sense instead to use the -P parameter instead. Using the same service as the previous example, we could instead create a file containing

http://counter.com=counter_
http://another.counter.com=another_counter_

to generate C prefixes for multiple namespaces.

A service may be composed of operations and data types from multiple namespaces. By default globus-wsrf-cgen generates bindings for all namespaces except those used by the core WSRF specifications. These are (along with their C prefixes):

Table 37. WSRF Core Namespaces and C Prefixes

http://www.w3.org/XML/1998/namespace	xml_
http://www.w3.org/2001/XMLSchema	xsd_
http://www.w3.org/2005/08/addressing	wsa_
http://docs.oasis-open.org/wsrf/r-2	wsr_
http://docs.oasis-open.org/wsrf/rw-2	wsrw_
http://docs.oasis-open.org/wsrf/bf-2	wsbf_
http://docs.oasis-open.org/wsrf/rp-2	wsrp_
http://docs.oasis-open.org/wsrf/rpw-2	wsrpw_
http://docs.oasis-open.org/wsrf/rl-2	wsrl_
http://docs.oasis-open.org/wsrf/rlw-2	wsrlw_
http://docs.oasis-open.org/wsrf/sg-2	wssg_
http://docs.oasis-open.org/wsrf/sgw-2	wssgw_
http://docs.oasis-open.org/wsn/b-2	wsnt_
http://docs.oasis-open.org/wsn/bw-2	wsntw_
http://docs.oasis-open.org/wsn/t-1	wstop_
http://schemas.xmlsoap.org/ws/2002/12/policy	wsp_
http://schemas.xmlsoap.org/ws/2002/07/utility	wsu_
http://schemas.xmlsoap.org/ws/2004/04/trust	wst_
http://www.w3.org/2000/09/xmldsig#	ds_
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd	wsse_
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd	wsseu_
http://schemas.xmlsoap.org/ws/2004/04/sc	wsc_
http://schemas.xmlsoap.org/ws/2004/09/enumeration	wsen_

Often it is enough for a package to contain bindings for the namespaces unique to the service and compile against other packages which contain the bindings for the other namespaces. This control can be done positively via the -N and -n command-line options.

For example, to generate bindings for the http://counter.com namespace only, pass the command-line option -N http://counter.com. To generate for both the http://counter.com nd http://another.counter.com namespaces, either pass multiple -N options with one namespace each, or create a file containing:

http://counter.com
http://another.counter.com

and pass the name of the file to globus-wsrf-cgen as the parameter to the -n command-line option.

Examples

Here is a brief example of the globus-wsrf-cgen command. For more details, see the tutorials in the C WS Core developer documentation.

Create bindings for a service in the http://counter.com namespace:

% globus-wsrf-cgen -d counter \
    -N http://counter.com \
    -s counter \
    -P http://counter.com=counter_ \
    $GLOBUS_LOCATION/share/schemas/core/samples/counter_service.wsdl















Creating Bindings Package

A new package has been created at /home/griduser/counter/counter_bindings-1.2.tar.gz
To install, use the following command:

$GLOBUS_LOCATION/sbin/gpt-build /Users/bester/tmp/foo/counter/counter_bindings-1.2.tar.gz <flavor>

%

Limitations

This program only generates bindings from document/literal style WSDL schemas. IBM developerworks has an article describing the different WSDL schema styles.
The bindings generated when -lang cpp is used are ANSI-C. However, all C++ keywords are avoided and no constructs that differ between C and C++ are used. This command-line option merely creates a makefile which compiles the service implementation with the C++ compiler.
Not all XML Schema constructs are supported. In particular, abstract types, substitution groups, and nested sequences are not implemented.

Name

globus-wsrf-destroy — Set the scheduled termination time for a WSRF resource.

Synopsis

globus-wsrf-destroy [OPTIONS]... SERVICE-SPECIFIER

Tool description

Set the scheduled termination time for a WSRF resource.

Command syntax

globus-wsrf-destroy [OPTIONS]... SERVICE-SPECIFIER

Table 38. 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]

Examples:

% globus-wsrf-destroy -e widget.epr
Resource destroyed

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>

Output and Exit Code

If the resource is destroyed successfull, the string Resource destroyed will be displayed to stdout and the program will terminate 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-set-termination-time — Set the scheduled termination time for a WSRF resource.

Synopsis

globus-wsrf-set-termination-time [OPTIONS]... SERVICE-SPECIFIER TERMINATION-TIME

Tool description

Set the scheduled termination time for a WSRF resource.

Command syntax

globus-wsrf-set-termination-time [OPTIONS]... SERVICE-SPECIFIER TERMINATION-TIME

Table 39. 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]

TERMINATION-TERMINATION: [SECONDS | 'infinity']

Examples:

           % globus-wsrf-set-termination-time -e widget.epr `expr 24 \* 60 \* 60`
           Termination time set to 2006-05-31T20:18:43Z

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>

Output and Exit Code

If the termination time is set successfully, the string Termination time set to YYYY-MM-DD-THH:MM:SS[.MSEC]Z will be displayed to stdout and the program will terminate 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-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 40. 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 41. 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 42. 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 43. 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.

Name

globus-wsrf-insert-property — Insert a resource property value

Synopsis

globus-wsrf-insert-property [OPTIONS]... SERVICE-SPECIFIER PROPERTY-VALUE-FILENAME

Tool description

Insert a resource property into a WSRF resource's Resource Properties document. The new property will be read from the XML file specified by PROPERTY-VALUE-FILENAME.

Command syntax

globus-wsrf-insert-property [OPTIONS]... SERVICE-SPECIFIER PROPERTY-VALUE-FILENAME...

Table 44. 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]

Example:

% globus-wsrf-insert-property -e widget.epr widget:foo.xml

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>

Contents of widget:foo.xml:

<doc>
    <foo xmlns="http://widgets.com"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:type="xsd:string">
    Foo Value String
    </foo>
</doc>

Output and Exit Code

If the property is inserted successfully, 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-update-property — Update a resource property value

Synopsis

globus-wsrf-update-property [OPTIONS]... SERVICE-SPECIFIER PROPERTY-VALUE-FILENAME

Tool description

Update a resource property in a WSRF resource's Resource Properties document. The property's new value will be read from the XML file specified by PROPERTY-VALUE-FILENAME. An update operation will replace the value(s) of the resource property with the new value(s) in the property file.

Command syntax

globus-wsrf-update-property [OPTIONS]... SERVICE-SPECIFIER PROPERTY-VALUE-FILENAME

Table 45. 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]

Example:

% globus-wsrf-update-property -e widget.epr widget:foo.xml

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>

Contents of widget:foo.xml:

<doc>
   <foo xmlns="http://widgets.com"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="xsd:string">
   Foo Value String
   </foo>
</doc>

Output and Exit Code

If the property update is successful without any output, then 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-delete-property — Delete a resource property

Synopsis

globus-wsrf-delete-property [OPTIONS] SERVICE-SPECIFIER PROPERTY-NAME

Tool description

Delete a resource property from a WSRF resource.

Command syntax

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

Table 46. 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-delete-property \
       -s http://grid.example.org:8080/wsrf/services/WidgetService \
       -k "{http://www.globus.org/namespaces/2004/06/core}WidgetKey" 123 \
       "{http://widgets.com}foo"

Output and Exit Code

If the property is successfully deleted, globus-wsrf-delete-property will not print out any output and will terminate with the 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-wsn-get-current-message — Get the current message associated with a specified topic

Synopsis

globus-wsn-get-current-message [OPTIONS] SERVICE-SPECIFIER TOPIC-EXPRESSION

Tool description

Get the current message associated with a specified topic.

Command syntax

globus-wsn-get-current-message [OPTIONS]... SERVICE-SPECIFIER TOPIC-EXPRESSION

Table 47. Application-specific options

-N | --namespace PREFIX=NAMESPACE-URI

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

-D | --dialect DIALECT-URI

Set the Topic Expression dialect to DIALECT-URI. If not specified, the dialect is chosen automatically between http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple, http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Concrete, and http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Full based on the presence of substrings '*', '//', '|', and '/' in the Topic Expression string.

Table 48. 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]

TOPIC-EXPRESSION: [{Namespace-URI} | prefix ':']RootTopic[/ChildTopic]...
                 TOPIC-EXPRESSION [ '|' TOPIC-EXPRESSION]
                 RootChild or ChildTopic may contain '*' (wildcard) and/or
                 '//' (all descendents)

Example:

% globus-wsn-get-current-message \
       -e widget.epr \
       -N wsrl=http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd \
       'wsrl:TerminationTime'

<ns00:ResourcePropertyValueChangeNotification 
  xmlns:ns00="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd" 
  xmlns:ns01="http://www.w3.org/2001/XMLSchema-instance" 
  ns01:type="ns00:ResourcePropertyValueChangeNotificationType">
    <ns00:NewValue 
      ns01:type="ns00:NewValueType">
        <ns03:TerminationTime
          xmlns:ns02="http://www.w3.org/2001/XMLSchema"
          xmlns:ns03="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd"
          ns01:type="ns02:dateTime">2006-05-31T20:10:08Z</ns03:TerminationTime>
    </ns00:NewValue>
</ns00:ResourcePropertyValueChangeNotification>

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>

Output and Exit Code

If the Topic exists and has a current message, globus-wsn-get-current-message will print the current message value to stdout and then terminate with the 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-wsn-pause-subscription — Pause a WSRF notification subscription.

Synopsis

globus-wsn-pause-subscription [OPTIONS] SERVICE-SPECIFIER

Tool description

Pause a WSRF notification subscription.

Command syntax

globus-wsn-pause-subscription [OPTIONS]... SERVICE-SPECIFIER TOPIC-EXPRESSION

Table 49. 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]

Example:

% globus-wsn-pause-subscription \
       -e subscription.epr

Contents of subscription.epr:

<ns00:EndpointReference
    xmlns:ns00="http://schemas.xmlsoap.org/ws/2004/03/addressing">
  <ns00:Address>http://globus.my.org:8080/wsrf/services/SubscriptionManagerService</ns00:Address>
  <ns00:ReferenceProperties>
    <ns03:ResourceID
        xmlns:ns01="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:ns02="http://www.w3.org/2001/XMLSchema"
        xmlns:ns03="http://www.globus.org/docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd"
        ns01:type="ns02:string">7d6430e4-f019-11da-a1b9-00096b86f788</ns03:ResourceID>
  </ns00:ReferenceProperties>
</ns00:EndpointReference>

Output and Exit Code

If the subscription is successfully paused, globus-wsn-pause-subscription will terminate with the exit code 0. No further notifications should be expected on the Subscription resource until it is resumed again. 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-wsn-resume-subscription — Resume a WSRF notification subscription.

Synopsis

globus-wsn-resume-subscription [OPTIONS] SERVICE-SPECIFIER

Tool description

Resume a subscription.

Command syntax

globus-wsn-resume-subscription [OPTIONS]... SERVICE-SPECIFIER TOPIC-EXPRESSION

Table 50. 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]

Example:

% globus-wsn-resume-subscription \
       -e subscription.epr

Contents of subscription.epr:

<ns00:EndpointReference
    xmlns:ns00="http://schemas.xmlsoap.org/ws/2004/03/addressing">
  <ns00:Address>http://globus.my.org:8080/wsrf/services/SubscriptionManagerService</ns00:Address>
  <ns00:ReferenceProperties>
    <ns03:ResourceID
        xmlns:ns01="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:ns02="http://www.w3.org/2001/XMLSchema"
        xmlns:ns03="http://www.globus.org/docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd"
        ns01:type="ns02:string">7d6430e4-f019-11da-a1b9-00096b86f788</ns03:ResourceID>
  </ns00:ReferenceProperties>
</ns00:EndpointReference>

Output and Exit Code

If the subscription is successfully resumed, globus-wsn-resume-subscription will terminate with the exit code 0. Notifications should again flow to the Subscription resource. 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-wsn-subscribe — Subscribe for notification for a specified topic.

Synopsis

globus-wsn-subscribe [OPTIONS] SERVICE-SPECIFIER TOPIC-EXPRESSION

Tool description

Subscribe for notification for a specified topic.

Command syntax

globus-wsn-subscribe [OPTIONS]... SERVICE-SPECIFIER TOPIC-EXPRESSION

Table 51. Application-specific options

-b \| --subEpr FILENAME	Save the Subscription Manager EPR in FILENAME. This EPR file can be used with the globus-wsn-pause-subscription and globus-wsn-resume-subscription commands
-N \| --namespace PREFIX=NAMESPACE-URI	Create a namespace mapping in the XPATH context for the PREFIX string to resolve to the NAMESPACE-URI namespace in the Topic Expression.
-D \| --dialect DIALECT-URI	Set the Topic Expression dialect to DIALECT-URI. If not specified, the dialect is chosen automatically between http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple, http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Concrete, and http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Full based on the presence of substrings '*', '//', '\|', and '/' in the Topic Expression string.

Table 52. 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]

Example:

% globus-wsn-subscribe \
       -e counter.epr \
       -N counter=http://www.counter.com \
       'counter:Value'
<ns02:Value
  xmlns:ns00="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:ns01="http://www.w3.org/2001/XMLSchema"
  xmlns:ns02="http://counter.com" ns00:type="ns01:int">10</ns02:Value>
<ns02:Value
  xmlns:ns00="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:ns01="http://www.w3.org/2001/XMLSchema"
  xmlns:ns02="http://counter.com"
  ns00:type="ns01:int">20</ns02:Value>

Contents of counter.epr:

<ns01:EndpointReference
  xmlns:ns01="http://schemas.xmlsoap.org/ws/2004/03/addressing">
  <ns01:Address>http://globus.my.org:8080//wsrf/services/CounterService</ns01:Address>
  <ns01:ReferenceProperties>
    <ns04:CounterKey
      xmlns:ns02="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:ns03="http://www.w3.org/2001/XMLSchema"
      xmlns:ns04="http://counter.com/service"
      ns02:type="ns03:string">1804289383</ns04:CounterKey>
  </ns01:ReferenceProperties>
</ns01:EndpointReference>

Output and Exit Code

globus-wsn-subscribe will print the the contents of notification message to stdout. If the message is a ResourcePropertyValueChangedNotification message, then only the NewValue subelement will be displayed. Otherwise, the entire message will be displayed. This program will run until terminated by a signal. 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.

GSI Commands

Table of Contents

grid-cert-diagnostics - Print diagnostic information about certificates and keys
grid-cert-info - Display certificate information
grid-cert-request - Create a certificate request
grid-default-ca - Set the default CA to use for certificate requests
grid-change-pass-phrase - Change the pass phrase on a private key
grid-proxy-init - Generate a new proxy certificate
grid-proxy-destroy - Destroy the current proxy certificate (previously created with grid-proxy-init)
grid-proxy-info - Display information obtained from a proxy certificate
grid-mapfile-add-entry - Add an entry to a grid map file
grid-mapfile-check-consistency - Check the internal consistency of a grid map file
grid-mapfile-delete-entry - Delete an entry from a grid map file

Name

grid-cert-diagnostics — Print diagnostic information about certificates and keys

Synopsis

grid-cert-diagnostics [-h] [-p]

Description

The grid-cert-diagnostics command displays information about the current user's security environment, including information about security-related environment variables, security directory search path, personal key and certificates, and trusted certificates. It is intended to provide information to help diagnose problems using GSI security.

The full set of command-line options to grid-cert-diagnostics consists of:

-h	Display a help message and exit
-p	Display information about the personal certificate and key that is the current user's default credential.

Examples

In this example, we see the default mode of checking the default security environment for the system, without processing the user's key and certificate. Note the user receives a warning about a cog.properties and about an expired CA certificate.

% grid-cert-diagnostics

Checking Environment Variables
==============================
Checking if X509_CERT_DIR is set... no
Checking if X509_USER_CERT is set... no
Checking if X509_USER_KEY is set... no
Checking if X509_USER_PROXY is set... no

Checking Security Directories
=======================
Determining trusted cert path... /etc/grid-security/certificates
Checking for cog.properties... found
    WARNING: If the cog.properties file contains security properties, 
             Java apps will ignore the security paths described in the GSI
             documentation

Checking trusted certificates...
================================
Getting trusted certificate list...
Checking CA file /etc/grid-security/certificates/1c4f4c48.0... ok
Verifying certificate chain for "/etc/grid-security/certificates/1c3f2ca8.0"... ok
Checking CA file /etc/grid-security/certificates/9d8788eb.0... ok
Verifying certificate chain for "/etc/grid-security/certificates/9d8753eb.0"... failed
    globus_credential: Error verifying credential: Failed to verify credential
    globus_gsi_callback_module: Could not verify credential
    globus_gsi_callback_module: The certificate has expired:
    Credential with subject: /DC=org/DC=example/OU=grid/CN=CA has expired.

In this example, we show a user with a mismatched private key and certificate:

% grid-cert-diagnostics -p

Checking Environment Variables
==============================
Checking if X509_CERT_DIR is set... no
Checking if X509_USER_CERT is set... no
Checking if X509_USER_KEY is set... no
Checking if X509_USER_PROXY is set... no

Checking Security Directories
=======================
Determining trusted cert path... /etc/grid-security/certificates
Checking for cog.properties... not found

Checking Default Credentials
==============================
Determining certificate and key file names... ok
Certificate Path: "/home/juser/.globus/usercert.pem"
Key Path: "/home/juser/.globus/userkey.pem"
Reading certificate... ok
Reading private key...
ok
Checking Certificate Subject...
"/O=Grid/OU=Example/OU=User/CN=Joe User"
Checking cert... ok
Checking key... ok
Checking that certificate contains an RSA key... ok
Checking that private key is an RSA key... ok
Checking that public and private keys have the same modulus... failed
Private key modulus: D294849E37F048C3B5ACEEF2CCDF97D88B679C361E29D5CB5
219C3E948F3E530CFC609489759E1D751F0ACFF0515A614276A0F4C11A57D92D7165B8
FA64E3140155DE448D45C182F4657DA13EDA288423F5B9D169DFF3822EFD81EB2E6403
CE3CB4CCF96B65284D92592BB1673A18354DA241B9AFD7F494E54F63A93E15DCAE2
Public key modulus : C002C7B329B13BFA87BAF214EACE3DC3D490165ACEB791790
600708C544175D9193C9BAC5AED03B7CB49BB6AE6D29B7E635FAC751E9A6D1CEA98022
6F1B63002902D6623A319E4682E7BFB0968DCE962CF218AAD95FAAD6A0BA5C42AA9AAF
7FDD32B37C6E2B2FF0E311310AA55FFB9EAFDF5B995C7D9EEAD8D5D81F3531E0AE5
Certificate and and private key don't match

Name

grid-cert-info — Display certificate information

Synopsis

grid-cert-info [-help] [-version]
[-file CERTIFICATE-FILENAME]
[-all] [-subject] [-issuer] [-issuerhash] [-startdate] [-enddate]

Description

The grid-cert-info displays information from a user's credential, or from any X.509 certificate if the -file CERTIFICATE-FILENAME is used. By default, a text representation of the entire certificate is displayed. If more than one display option is present on the command line, the output is generated in the order the options occur on the command line.

The following search order is used to locate the default certificate:

$X509_USER_CERT
$HOME/.globus/usercert.pem
$HOME/.globus/usercred.p12

If the certificate is encoded in pkcs12, grid-cert-info will prompt for the password used to protect the .p12 file.

The full set of command-line options to grid-cert-info is:

`-help`	Print help information and exit
`-version`	Print version information and exit
`-file CERTIFICATE-FILENAME`	Read credential from `CERTIFICATE-FILENAME` instead of the default location. The file must have a `.pem` or `.p12` extension.
`-all`	Print all information from the certificate. This is the default unless any of the following options are given.
`-subject`	Print the subject name of the certificate.
`-issuer`	Print the subject name of the issuer of the certificate. This is the subject name of the Certificate Authority which signed the certificate.
`-issuerhash`	Print the hash of the name of the issuer of the certificate. This is the hash of the Certificate Authority which signed the certificate.
`-startdate`	Print the date and time from which the certificate is valid
`-enddate`	Print the date and time when the certificate expires.

Examples

Print out the date range when a certificate is valid:

% grid-cert-info -startdate -enddate

Oct 29 13:09:42 2007 GMT
Oct 28 13:09:42 2008 GMT

Note that in this example, the start date is printed first, based on the order of the command-line options.

Limitations

The -issuerhash fails with some versions of OpenSSL.

Name

grid-cert-request — Create a certificate request

Synopsis

grid-cert-request [-help] [-version] [-verbose] [-force]
[-commonname NAME] [-service SERVICE] [-host FQDN] [-interactive]
[-dir DIRECTORY] [-prefix PREFIX] [-ca [HASH]] [-nopw]

Description

grid-cert-request generates a public/private key pair an X.509 certificate request containing the public key and a subject name. By default, it generates a request for a user certificate for the invoking user. grid-cert-request can also be used to create host or service certificates based on command-line options. At least one Certificate Authority must be configured to use with the Globus Toolkit in order for this command to succeed.

Complete set of options to grid-cert-request is:

`-help`	Print help information and exit
`-version`	Print version information and exit
`-verbose`	Don't clear screen after running OpenSSL
`-force`	Overwrite an existing certificate request if present.
`-commonname NAME`	Construct a subject name with `NAME` as the final name component. By default, the subject name is inferred from the output of the finger program. If that fails, grid-cert-request will prompt of a name.
`-service SERVICE`	Construct a subject name with the common name constructed from the `SERVICE` name and the hostname joined by the `/` character. The `-service` requires that the `-host` option also be used. The private key created for a service certificate request is not encrypted.
`-host FQDN`	Construct a subject name with `FQDN` as the name of the host. This must be a fully-qualified name in dotted string notation (e.g. `grid.example.org`). If no service is specified by the `-service` option, the subject name will be `host/``FQDN`.The private key created for a host certificate request is not encrypted. By default the host certificate request and key are created in `/etc/grid-security`.
`-interactive`	Interactively prompt for the components of the certificate subject name.
`-dir DIRECTORY`	Write the certificate request and key to `DIRECTORY`, creating it if the directory does not exist. By default, the certificate request and key are placed in `$HOME/.globus`
`-prefix PREFIX`	Prepend the string `PREFIX` to the certificate, key, and request filenames. The default prefix is `user` for user certificates and `host` for host certificates.
`-ca HASH`	Choose a non-default Certificate Authority configuration to construct the certificate request. If `HASH` is present on the command line, then grid-cert-request will use that certificate authority's configuration. Otherwise, it will prompt the user for a CA to choose from the list of configured CAs.
`-nopw`	Create a private key without a password. This may be a security risk if the file permissions of the private key are not carefully maintained.

Examples

Request a user certificate:

% grid-cert-request

A certificate request and private key is being created.
You will be asked to enter a PEM pass phrase.
This pass phrase is akin to your account password, 
and is used to protect your key file.
If you forget your pass phrase, you will need to
obtain a new certificate.

Generating a 1024 bit RSA private key
.....................++++++
........++++++
writing new private key to '/home/juser/.globus/userkey.pem'
Enter PEM pass phrase:

A private key and a certificate request has been generated with the subject:

/O=Grid/OU=Example/OU=User/CN=Joe User

If the CN=Joe User is not appropriate, rerun this
script with the -force -cn "Common Name" options.

Your private key is stored in /home/juser/.globus/userkey.pem
Your request is stored in /home/juser/.globus/usercert_request.pem

Please e-mail the request to the Globus Certificate Service ca@grid.example.org
You may use a command similar to the following:

  cat /home/juser/.globus/usercert_request.pem | mail ca@grid.example.org

Only use the above if this machine can send AND receive e-mail. if not, please
mail using some other method.

Your certificate will be mailed to you within two working days.
If you receive no response, contact Globus Certificate Service at ca@grid.example.org

Request a host certificate, putting the request and key files in the $HOME/.globus/host directory.

% grid-cert-request -host grid.example.org -dir $HOME/.globus/host


A private host key and a certificate request has been generated
with the subject:

/O=Grid/OU=Example/OU=User/CN=host/grid.example.org

----------------------------------------------------------

The private key is stored in /tmp/examplegrid/hostkey.pem
The request is stored in /tmp/examplegrid/hostcert_request.pem

Please e-mail the request to the Globus Certificate Service ca@grid.example.org
You may use a command similar to the following:

 cat /tmp/examplegrid/hostcert_request.pem | mail ca@grid.example.org

Only use the above if this machine can send AND receive e-mail. if not, please
mail using some other method.

Your certificate will be mailed to you within two working days.
If you receive no response, contact Globus Certificate Service at ca@grid.example.org

Limitations

Only supports PEM-encoded keys, certificates and certificate requests.

Name

grid-default-ca — Set the default CA to use for certificate requests

Synopsis

grid-default-ca [-help] [-list] [-ca CA-HASH] [-dir SECURITY-DIRECTORY]

Description

The grid-default-ca program sets the default CA used by grid-cert-request. Based on the default CA choice, grid-cert-request will create a certificate request that matches the CA's naming policies.

If the -ca option is not provided on the command-line, grid-default-ca will display a list of available Certificate Authorities and prompt the user to choose one.

The full set of command-line options to grid-default-ca are:

-help	Display a help message and exit
-list	List the available CAs but do not alter the default
-ca `CA-HASH`	Select the default CA whose subject name hash matches `CA-HASH`.
-dir `SECURITY-DIRECTORY`	Search `SECURITY-DIRECTORY` for additional CA certificates.

Examples

Show what certificate authorities are in the trusted cert directory:

%  grid-default-ca -list

The available CA configurations installed on this host are:

Directory: /etc/grid-security/certificates

1) 1c3f2ca8 -  /DC=org/DC=DOEGrids/OU=Certificate Authorities/CN=DOEGrids CA 1
2) 3d8e6ce8 -  /O=Grid/CN=Example CA
3) 6349a761 -  /O=DOE Science Grid/OU=Certificate Authorities/CN=Certificate Manager
4) b38b4d8c -  /C=US/O=Globus Alliance/CN=Globus Certificate Service


The default CA is: /C=US/O=Globus Alliance/CN=Globus Certificate Service
         Location: /etc/grid-security/certificates/b38b4d8c.0

Change the default CA to be DOEGrids CA 1:

%  grid-default-ca

The available CA configurations installed on this host are:

Directory: /etc/grid-security/certificates

1) 1c3f2ca8 -  /DC=org/DC=DOEGrids/OU=Certificate Authorities/CN=DOEGrids CA 1
2) 3d8e6ce8 -  /O=Grid/CN=Example CA
3) 6349a761 -  /O=DOE Science Grid/OU=Certificate Authorities/CN=Certificate Manager
4) b38b4d8c -  /C=US/O=Globus Alliance/CN=Globus Certificate Service


The default CA is: /C=US/O=Globus Alliance/CN=Globus Certificate Service
         Location: /etc/grid-security/certificates/b38b4d8c.0


Enter the index number of the CA to set as the default [q to quit]: 1

setting the default CA to: /DC=org/DC=DOEGrids/OU=Certificate Authorities/CN=DOEGrids CA 1

linking /etc/grid-security/certificates/grid-security.conf.1c3f2ca8 to
        /etc/grid-security/grid-security.conf

linking /etc/grid-security/certificates/globus-host-ssl.conf.1c3f2ca8 to
        /etc/grid-security/globus-host-ssl.conf

linking /etc/grid-security/certificates/globus-user-ssl.conf.1c3f2ca8 to
        /etc/grid-security/globus-user-ssl.conf


...done.

Limitations

Displays all CAs in the output, even those where the globus-user-ssl.conf and globus-host-ssl.conf files are not installed in the trusted certificate directory. If one of those is chosen, grid-default-ca displays an error and exits.

Name

grid-change-pass-phrase — Change the pass phrase on a private key

Synopsis

grid-change-pass-phrase

Tool description

grid-change-pass-phrase allows one to change the passphrase that protects the private key.

Command syntax

grid-change-pass-phrase [-help] [-version] [-file private_key_file]

Changes the passphrase that protects the private key. Note that this command will work even if the original key is not password protected. If the -file argument is not given, the default location of the file containing the private key is assumed:

The location pointed to by X509_USER_KEY
If X509_USER_KEY not set, $HOME/.globus/userkey.pem

Options

Table 53. Command line options

help, -usage	Displays usage.
-version	Displays version.
-file location	Changes the passphrase on the key stored in the file at the non-standard location 'location'.

Limitations

Nothing applicable

Name

grid-proxy-init — Generate a new proxy certificate

Synopsis

grid-proxy-init

Tool description

grid-proxy-init generates X.509 proxy certificates.

By default, this command generates RFC 3820 Proxy Certificates.

There are also options available for generating other types of proxy certificates, including limited, independent and legacy. For more information about proxy certificate types and their compatibility in GT, see http://dev.globus.org/wiki/Security/ProxyCertTypes.

Command syntax

 grid-proxy-init [-help][-pwstdin][-limited][-valid H:M] ...

Options

Table 54. Command line options

-help, -usage	Displays usage.
-version	Displays version.
-debug	Enables extra debug output.
-q	Quiet mode, minimal output.
-verify	Verifies the certificate to make the proxy for.
-pwstdin	Allows passphrase from stdin.
-limited	Creates a limited globus proxy.
-independent	Creates an independent globus proxy.
-draft	Creates a draft (GSI-3) proxy.
-old	Creates a legacy globus proxy.
-valid <h:m>	Proxy is valid for h hours and m minutes (default:12:00).
-hours <hours>	Deprecated support of hours option.
-bits <bits>	Number of bits in key {512\|1024\|2048\|4096}.
-policy <policyfile>	File containing the policy to store in the ProxyCertInfo extension.
-pl <oid>, -policy-language <oid>	OID string for the policy language used in the policy file.
-path-length <l>	Allows a chain of at most 1 proxies to be generated from this one.
-cert <certfile>	Non-standard location of user certificate.
-key <keyfile>	Non-standard location of user key.
-certdir <certdir>	Non-standard location of trusted cert directory.
-out <proxyfile>	Non-standard location of new proxy cert.

Creating a Proxy Certificate

Proxies are certificates signed by the user, or by another proxy, that do not require a password to submit a job. They are intended for short-term use, when the user is submitting many jobs and cannot be troubled to repeat his password for every job.

The subject of a proxy certificate is the same as the subject of the certificate that signed it, with /CN=proxy added to the name. The gatekeeper will accept any job requests submitted by the user, as well as any proxies he has created.

Proxies provide a convenient alternative to constantly entering passwords, but are also less secure than the user's normal security credential. Therefore, they should always be user-readable only, and should be deleted after they are no longer needed (or after they expire).

To create a proxy with the default expiration (12 hours), run the grid-proxy-init program. For example:

% grid-proxy-init

The grid-proxy-init program can also take arguments to specify the expiration and proxy key length. For example:

% grid-proxy-init -hours 8 -bits 512

Limitations

Nothing applicable

Name

grid-proxy-destroy — Destroy the current proxy certificate (previously created with grid-proxy-init)

Synopsis

grid-proxy-destroy

Tool description

grid-proxy-destroy removes X.509 proxy certificates.

Command syntax

grid-proxy-destroy [-help][-dryrun][-default][-all][--] [file1...]

Options

Table 55. Command line options

-help, -usage	Displays usage.
-version	Displays version.
-debug	Displays debugging information.
-dryrun	Prints what files would have been destroyed.
-default	Destroys file at default proxy location.
-all	Destroys any user (default) and delegated proxies that are found.
--	Ends processing of options.
file1 file2 ...	Destroys the files listed.

Limitations

Nothing applicable

Name

grid-proxy-info — Display information obtained from a proxy certificate

Synopsis

grid-proxy-info

Tool description

grid-proxy-info extracts information from X.509 proxy certificates.

Command syntax

grid-proxy-info [-help][-f proxyfile][-subject][...][-e [-h H][-b B]]

Options

Table 56. Command line options

-help, -usage	Displays usage.
-version	Displays version.
-debug	Displays debugging output.
-file <proxyfile> (-f)	Non-standard location of proxy.
[printoptions]	See Table 58, “Print options”.
-exists [options] (-e)	Determine whether a valid proxy exists. `options` may contain any validition options described below. If a proxy exists, and meets any criteria defined by the validity options, then grid-proxy-info will terminate with the exit code `0`. Otherwise, grid-proxy-info will terminate with the exit code `1`. If no validity options are specified, the program will terminate with 0 if a currently-valid proxy file exists.

Table 57. Print options

-subject (-s)	Distinguished name (DN) of the subject.
-issuer (-i)	DN of the issuer (certificate signer).
-identity	DN of the identity represented by the proxy.
-type	Type of proxy (full or limited).
-timeleft	Time (in seconds) until proxy expires.
-strength	Key size (in bits).
-all	All above options in a human readable format.
-text	All of the certificate.
-path	Pathname of the proxy file.

Table 58. Validity options

-valid H:M (-v)	Time requirement for the proxy to be valid.
-hours H (-h)	Time requirement for the proxy to be valid (deprecated, use -valid instead).
-bits B (-b)	Strength requirement for the proxy to be valid.

Limitations

Nothing applicable

Name

grid-mapfile-add-entry — Add an entry to a grid map file

Synopsis

grid-mapfile-add-entry

Tool description

grid-mapfile-add-entry adds entries to grid map files.

Command syntax

grid-mapfile-add-entry -dn DN -ln LN  [-help] [-d] [-f mapfile FILE]

Options:

Table 59. Command line options

-help, -usage	Displays help.
-version	Displays version.
-dn DN	Distinguished Name (DN) to add. Remember to quote the DN if it contains spaces.
-ln LN1 [LN2...]	Local login name(s) to which the DN is mapped.
-dryrun, -d	Shows what would be done but will not add the entry.
-mapfile FILE, -f FILE	Path of the grid map file to be used.

Limitations

Nothing applicable.

Name

grid-mapfile-check-consistency — Check the internal consistency of a grid map file

Synopsis

grid-mapfile-check-consistency

Tool description

grid-mapfile-check-consistency checks that the given grid mapfile conforms to the expected format as well as checking for common subject name problems.

Command syntax

grid-mapfile-check-consistency [-help] [-mapfile FILE]

Options:

Table 60. Command line options

-help, -usage	Displays help.
-version	Displays version.
-mapfile FILE, -f FILE	Path of the grid map file to be used.

Limitations

Nothing applicable

Name

grid-mapfile-delete-entry — Delete an entry from a grid map file

Synopsis

grid-mapfile-delete-entry

Tool description

grid-mapfile-delete entry deletes a grid map file entry from the given file.

Command syntax

grid-mapfile-delete-entry [-help] [-dn <DN>] [-ln <local name>] [-d] [-f file]

Options:

Table 61. Command line options

-help, -usage	Displays help.
-version	Displays version.
-dn <DN>	Distinguished Name (DN) to delete.
-ln <local name>	Local Login Name (LN) to delete.
-dryrun, -d	Shows what would be done but will not delete the entry.
-mapfile file, -f file	Path of the grid map file to be used.

Limitations

Nothing applicable.

CAS Query Commands

The CAS Query commands do not alter the state of the database and any CAS user who has cas/query permissions may use the commands to retrieve data from the CAS server.

The following queries can be run against the CAS server. These are typically used by CAS clients (who may not be administrators).

The user need cas/query permissions to perform these operations—that is, the user must have permission to query on the cas server object.

Table of Contents

cas-whoami - Getting a user's CAS identity.
cas-list-object - Getting object list
cas-get-object - Getting CAS object
cas-group-list-entries - Getting group members
cas-find-policies - Getting policy information
query-cas-service - Query CAS Service (using OGSA AuthZ interface)

Name

cas-whoami — Getting a user's CAS identity.

Synopsis

cas-whoami [options]

Tool description

The cas-whoami command returns the CAS user nick of the client.

Command options

Important

If you have an asterisk (*) in your command, you might need to escape it with a backslash ( \ ).

-a, --anonymous

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

-c, --serverCertificate <file>

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

-debug

Runs the client with debug message traces and error stack traces.

-f, --descriptor <file>

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

-help

Prints the usage message for the client.

-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. The value type can be:

msg for GSI Secure Message, or
conv for GSI Secure Conversation.

-p, --protection <type>

Specifies the protection level. type can be:

sig for signature, or
enc for encryption.

-s cas-url

Sets the CAS Service instance, where cas-url is the URL of the CAS service instance. Alternatively, an environment variable can be set as shown here.

The instance URL typically looks like http://Host:Port/wsrf/services/CASService, where Host and Port are the host and port where the container with the CAS service is running.

-v

Prints the version number.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z authorization

Specifies the type of authorization used, such as self or host.

If you cannot use a standard method for authorization, you can use the specific CAS server's identity as the value.

Alternatively, an environment variable can be set as shown here.

If none of the above are set, host authorization is done by default and the expected server credential is cas/<fqdn>, where <fqdn> is the fully qualified domain name of the host on which the CAS service is up.

	Note
	If the service being contacted is using GSI Secure Transport , then the container credentials configured for the service will be used, even if service/resource level credentials are configured. Hence authorization needs to be done based on the DN of the container credentials.

Name

cas-list-object — Getting object list

Synopsis

cas-list-object [options] type

Tool description

The cas-list-object command returns a list of CasObjects in the database of the requested type.

Command Options

type

Use one of the following to indicate the type of of CasObjects you want listed:

trustAnchor
user
userGroup
object
objectGroup
objectGroup
namespace
serviceType
serviceAction
serviceActionGp

Common Options

Important

If you have an asterisk (*) in your command, you might need to escape it with a backslash ( \ ).

-a, --anonymous

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

-c, --serverCertificate <file>

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

-debug

Runs the client with debug message traces and error stack traces.

-f, --descriptor <file>

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

-help

Prints the usage message for the client.

-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. The value type can be:

msg for GSI Secure Message, or
conv for GSI Secure Conversation.

-p, --protection <type>

Specifies the protection level. type can be:

sig for signature, or
enc for encryption.

-s cas-url

Sets the CAS Service instance, where cas-url is the URL of the CAS service instance. Alternatively, an environment variable can be set as shown here.

The instance URL typically looks like http://Host:Port/wsrf/services/CASService, where Host and Port are the host and port where the container with the CAS service is running.

-v

Prints the version number.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z authorization

Specifies the type of authorization used, such as self or host.

If you cannot use a standard method for authorization, you can use the specific CAS server's identity as the value.

Alternatively, an environment variable can be set as shown here.

	Note
	If the service being contacted is using GSI Secure Transport , then the container credentials configured for the service will be used, even if service/resource level credentials are configured. Hence authorization needs to be done based on the DN of the container credentials.

Name

cas-get-object — Getting CAS object

Synopsis

cas-get-object [options] type name

Tool description

The cas-get-object command returns the particular object of the said type and name.

Command Options

type

Use one of the following to indicate the type of of CasObjects you want to get:

trustAnchor
user
userGroup
object
objectGroup
namespace
serviceType
serviceAction
serviceActionGp

name

Use one of the following to indicate the name of the specific CAS object you want to get:

nickname (if getting trustAnchor, user, userGroup, or namespace)
objectNamespace objectName (if getting object or objectGroup)
serviceTypeName (if getting serviceType, serviceAction, or serviceActionGp)

Common Options

Important

If you have an asterisk (*) in your command, you might need to escape it with a backslash ( \ ).

-a, --anonymous

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

-c, --serverCertificate <file>

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

-debug

Runs the client with debug message traces and error stack traces.

-f, --descriptor <file>

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

-help

Prints the usage message for the client.

-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. The value type can be:

msg for GSI Secure Message, or
conv for GSI Secure Conversation.

-p, --protection <type>

Specifies the protection level. type can be:

sig for signature, or
enc for encryption.

-s cas-url

Sets the CAS Service instance, where cas-url is the URL of the CAS service instance. Alternatively, an environment variable can be set as shown here.

The instance URL typically looks like http://Host:Port/wsrf/services/CASService, where Host and Port are the host and port where the container with the CAS service is running.

-v

Prints the version number.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z authorization

Specifies the type of authorization used, such as self or host.

If you cannot use a standard method for authorization, you can use the specific CAS server's identity as the value.

Alternatively, an environment variable can be set as shown here.

	Note
	If the service being contacted is using GSI Secure Transport , then the container credentials configured for the service will be used, even if service/resource level credentials are configured. Hence authorization needs to be done based on the DN of the container credentials.

Name

cas-group-list-entries — Getting group members

Synopsis

cas-group-list-entries [options] type name

Tool description

The cas-group-list-entries command returns a list of group members.

Command Options

type

Use one of the following to indicate the type of group for which you want a list of members:

user
object
serviceType

name

The name of the group.

Common Options

Important

If you have an asterisk (*) in your command, you might need to escape it with a backslash ( \ ).

-a, --anonymous

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

-c, --serverCertificate <file>

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

-debug

Runs the client with debug message traces and error stack traces.

-f, --descriptor <file>

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

-help

Prints the usage message for the client.

-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. The value type can be:

msg for GSI Secure Message, or
conv for GSI Secure Conversation.

-p, --protection <type>

Specifies the protection level. type can be:

sig for signature, or
enc for encryption.

-s cas-url

Sets the CAS Service instance, where cas-url is the URL of the CAS service instance. Alternatively, an environment variable can be set as shown here.

The instance URL typically looks like http://Host:Port/wsrf/services/CASService, where Host and Port are the host and port where the container with the CAS service is running.

-v

Prints the version number.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z authorization

Specifies the type of authorization used, such as self or host.

If you cannot use a standard method for authorization, you can use the specific CAS server's identity as the value.

Alternatively, an environment variable can be set as shown here.

	Note
	If the service being contacted is using GSI Secure Transport , then the container credentials configured for the service will be used, even if service/resource level credentials are configured. Hence authorization needs to be done based on the DN of the container credentials.

Name

cas-find-policies — Getting policy information

Synopsis

cas-find-policies [options] [-c cas-url] type name

Tool description

The cas-find-policies command returns all applicable policies, both policies that are implicit to the CAS server and those that are external.

Command options

-c cas-url

The URL of the CAS service.

type

Use one of the following to indicate the type of CasObjects:

trustAnchor
user
userGroup
object
objectGroup
namespace
serviceType
serviceAction
serviceActionGp

name

Use the type of name corresponding to the appropriate CasObject:

nickname (for trustAnchors, users, or namespaces)
groupName (for userGroups, objectGroups, or serviceActionGps)
objectNamespace|objectName (for objects)
serviceTypeName (or) serviceType/Action (for serviceTypes or serviceActions)

Common Options

Important

If you have an asterisk (*) in your command, you might need to escape it with a backslash ( \ ).

-a, --anonymous

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

-c, --serverCertificate <file>

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

-debug

Runs the client with debug message traces and error stack traces.

-f, --descriptor <file>

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

-help

Prints the usage message for the client.

-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. The value type can be:

msg for GSI Secure Message, or
conv for GSI Secure Conversation.

-p, --protection <type>

Specifies the protection level. type can be:

sig for signature, or
enc for encryption.

-s cas-url

Sets the CAS Service instance, where cas-url is the URL of the CAS service instance. Alternatively, an environment variable can be set as shown here.

The instance URL typically looks like http://Host:Port/wsrf/services/CASService, where Host and Port are the host and port where the container with the CAS service is running.

-v

Prints the version number.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z authorization

Specifies the type of authorization used, such as self or host.

If you cannot use a standard method for authorization, you can use the specific CAS server's identity as the value.

Alternatively, an environment variable can be set as shown here.

	Note
	If the service being contacted is using GSI Secure Transport , then the container credentials configured for the service will be used, even if service/resource level credentials are configured. Hence authorization needs to be done based on the DN of the container credentials.

Name

query-cas-service — Query CAS Service (using OGSA AuthZ interface)

Synopsis

query-cas-service [options] assertionFilename

Tool description

The query-cas-service command returns a SAML Response containg SAML Assertions with user rights for a given SAML Query. This client uses the OGSA AuthZ interface and writes out the retrieved assertion to a file.

Command options

assertionFilename: File to write assertions to.

Common Options

Important

If you have an asterisk (*) in your command, you might need to escape it with a backslash ( \ ).

-a, --anonymous

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

-c, --serverCertificate <file>

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

-debug

Runs the client with debug message traces and error stack traces.

-f, --descriptor <file>

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

-help

Prints the usage message for the client.

-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. The value type can be:

msg for GSI Secure Message, or
conv for GSI Secure Conversation.

-p, --protection <type>

Specifies the protection level. type can be:

sig for signature, or
enc for encryption.

-s cas-url

Sets the CAS Service instance, where cas-url is the URL of the CAS service instance. Alternatively, an environment variable can be set as shown here.

The instance URL typically looks like http://Host:Port/wsrf/services/CASService, where Host and Port are the host and port where the container with the CAS service is running.

-v

Prints the version number.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z authorization

Specifies the type of authorization used, such as self or host.

If you cannot use a standard method for authorization, you can use the specific CAS server's identity as the value.

Alternatively, an environment variable can be set as shown here.

	Note
	If the service being contacted is using GSI Secure Transport , then the container credentials configured for the service will be used, even if service/resource level credentials are configured. Hence authorization needs to be done based on the DN of the container credentials.

CAS Admin Commands

Table of Contents

cas-proxy-init - Generate a CAS proxy
cas-wrap - Runs program with CAS credentials
cas-enroll - Enroll a CAS Object
cas-remove - Remove a CAS object from the database
cas-action - Maintains service types
cas-group-admin - Maintains user groups, object groups, or serviceAction groups
cas-group-add-entry - Adds CAS objects to CAS groups
cas-group-remove-entry - Removing CAS objects from CAS groups
cas-rights-admin - Granting or revoking permissions

Name

cas-proxy-init — Generate a CAS proxy

Synopsis

cas-proxy-init [common options] [ -p proxyfile | -t tag ]

Tool description

The cas-proxy-init command contacts a CAS server, obtains an assertion for the user, and embeds it in a credential. This credential can be used to access CAS-enabled services.

Options

Command-specific options

-b policyFileName: Generate a CAS credential that includes only those permissions specified in file policyFileName (the default is to generate a credential with all the user's permissions). Details about the template of the file is provided here.
-u tag: Choose a filename in which to store the CAS credential based on the value tag. Cannot be used with the -p option.
-w generatedCredFile: Specify the file in which to store the CAS credential. Cannot be used with the -t option.

Common Options

Important

If you have an asterisk (*) in your command, you might need to escape it with a backslash ( \ ).

-a, --anonymous

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

-c, --serverCertificate <file>

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

-debug

Runs the client with debug message traces and error stack traces.

-f, --descriptor <file>

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

-help

Prints the usage message for the client.

-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. The value type can be:

msg for GSI Secure Message, or
conv for GSI Secure Conversation.

-p, --protection <type>

Specifies the protection level. type can be:

sig for signature, or
enc for encryption.

-s cas-url

Sets the CAS Service instance, where cas-url is the URL of the CAS service instance. Alternatively, an environment variable can be set as shown here.

The instance URL typically looks like http://Host:Port/wsrf/services/CASService, where Host and Port are the host and port where the container with the CAS service is running.

-v

Prints the version number.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z authorization

Specifies the type of authorization used, such as self or host.

If you cannot use a standard method for authorization, you can use the specific CAS server's identity as the value.

Alternatively, an environment variable can be set as shown here.

	Note
	If the service being contacted is using GSI Secure Transport , then the container credentials configured for the service will be used, even if service/resource level credentials are configured. Hence authorization needs to be done based on the DN of the container credentials.

Usage

The following gets the assertion from the CAS server, generates a proxy with the assertion and writes it out to "casProxy".

cas-proxy-init -p casProxy

Requesting specific permissions from the CAS server

It is possible to request specific permissions from the CAS server using the -f option. This option causes cas-proxy-init to read a set of requested rights from a file.

This file should contain one or more resource identifiers:

Resource: ResourceNamespace|ResourceName

For each resource, there should be one or more action identifiers:

serviceType action

For example, if the client needed assertions for "file/read" service/action (permission) on two resources ("ftp://sample1.org" and "ftp://sample3.org", both in "FTPNamespace") but "directory/read" and "directory/write" permissions on the former resource only, the policy file should have the following entries:

Resource: FTPNamespace|ftp://sample1.org
      
      file read
      
      directory read
      
      directory write
      
      Resource: FTPNamespace|ftp://sample3.org
      
      file read

To indicate any resource, the following wildcard notation should be used:

uri:samlResourceWildcard

To indicate any action, the following wildcard notation for serviceType and action should be used. Note that this should be the first (and clearly the only action) in the list of actions specified. All other actions in the list are ignored and if it is not the first, it is not treated as a wildcard.

uri:samlActionNSWildcard uri:samlActionWildcard

For example, if the client needs assertions for all resources and all actions, the policy file should look like:

Resource: uri:samlResourceWildcard
        
        uri:samlActionNSWildcard uri:samlActionWildcard

If the client needs assertions for all actions on resource "FTPNamespace|ftp://sample1.org", the policy file should be as follows:

Resource: FTPNamespace|ftp://sample1.org
        
        uri:samlActionNSWildcard uri:samlActionWildcard

Name

cas-wrap — Runs program with CAS credentials

Synopsis

cas-wrap [common options] [ -p proxyfile | -t tag ]

Tool description

The cas-wrap command runs a grid-enabled program, causing it to use previously-generated CAS credentials.

This command invokes the given command with the given argument using the specified previously-generated CAS credential. For example:

casAdmin$ cas-wrap -t my-community gsincftp myhost.edu

will look for a credential generated by a previous execution of:

casAdmin$ cas-proxy-init -t my-community

and then set the environment to use that credential while running the command:

casAdmin$ gsincftp myhost.edu

The second form should be used if cas-proxy-init was run with the -p option. For example:

casAdmin$ cas-wrap -p /path/to/my/cas/credential gsincftp myhost.edu

will look for a credential generated by a previous execution of:

casAdmin$ cas-proxy-init -p /path/to/my/cas/credential

and then set the environment to use that credential while running the command:

casAdmin$ gsincftp myhost.edu

Options

Command-specific Options

-p proxyfile: Specify the file in which to store the CAS credential. Cannot be used with the -t option.
-t tag: Choose a filename in which to store the CAS credential based on the value tag. Cannot be used with the -p option.

Common Options

Important

If you have an asterisk (*) in your command, you might need to escape it with a backslash ( \ ).

-a, --anonymous

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

-c, --serverCertificate <file>

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

-debug

Runs the client with debug message traces and error stack traces.

-f, --descriptor <file>

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

-help

Prints the usage message for the client.

-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. The value type can be:

msg for GSI Secure Message, or
conv for GSI Secure Conversation.

-p, --protection <type>

Specifies the protection level. type can be:

sig for signature, or
enc for encryption.

-s cas-url

Sets the CAS Service instance, where cas-url is the URL of the CAS service instance. Alternatively, an environment variable can be set as shown here.

The instance URL typically looks like http://Host:Port/wsrf/services/CASService, where Host and Port are the host and port where the container with the CAS service is running.

-v

Prints the version number.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z authorization

Specifies the type of authorization used, such as self or host.

If you cannot use a standard method for authorization, you can use the specific CAS server's identity as the value.

Alternatively, an environment variable can be set as shown here.

	Note
	If the service being contacted is using GSI Secure Transport , then the container credentials configured for the service will be used, even if service/resource level credentials are configured. Hence authorization needs to be done based on the DN of the container credentials.

Usage

Example of using cas-wrap to transfer a file.

cas-wrap -p casProxy globus-url-copy gsiftp://somehost.edu/some_file_path \
file:///some_file_path

Name

cas-enroll — Enroll a CAS Object

Synopsis

cas-enroll [common options] trustAnchor userGpName nickname authMethod authData
cas-enroll [common options] namespace userGpName nickname basename comparisonAlg
cas-enroll [common options] object userGpName objectName namespaceNick
cas-enroll [common options] serviceType userGpName serviceTypeName

Tool description

This command line client is used to enroll a CAS Object, which includes trust anchors, namespaces, objects and service types.

Enrolling Trust Anchors

To enroll a trust anchor, the user must have cas/enroll_trustAnchor permission on that CAS server object (that is, the user must have permission to perform the enroll_trustAnchor action on the CAS service type).

The enroll operation allows the user to choose a user group to which cas/grantAll permission on the enrolled object should be granted. The nickname should be unique across the CAS database and is used to refer to this trust anchor.

To enroll trust anchors:

casAdmin$ cas-enroll [common options] trustAnchor userGpName nickname authMethod authData

where:

userGpName: Indicates the user group to which cas/grantAll permission should be granted on this trust anchor entity.
nickname: Indicates the trust anchor nickname.
authMethod: Indicates the authentication method used by the trust anchor.
authData: Indicates the data used for authentication, typically the DN.

Enrolling Namespaces

To enroll a namespace, the user must have cas/enroll_namespace permission (that is, the user must have permission to perform the enroll_namespace action on the cas service type).

The enroll operation allows the user to choose a userGroup to have cas/grantAll permission on the enrolled object. The comparison algorithm specified should be the name of the Comparison class that needs to be used to compare objects that belong to this namespace. The nickname should be unique across the CAS database and is used to refer to this user.

Also, two namespaces are added to the CAS database at boot up time, other than the inherent CAS Namespace:

FTPDirectoryTree uses the WildCardComparison Algorithm and has the base URL set to the current directory.
FTPExact uses the ExactComparison Algorithm and has the base URL set to the current directory.

To enroll namespaces:

casAdmin$ cas-enroll [common options] namespace userGpName nickname basename comparisonAlg

where:

userGpName

Indicates the user group to which cas/grantAll permission should be granted on this trust anchor entity.

nickname

Indicates the nickname of the namespace to be unenrolled.

If the trust anchor nickname specified does not exist, an error is not thrown. If the unenroll operation is successful, all policy data on that trust anchor is purged.

basename

Indicates the base URL for the namespace.

comparisonAlg

Indicates the comparison algorithm to be used. Unless the standard comparison algorithms described below are used, the fully qualified name of the class that needs to be used should be given. The class needs to extend from the abstract class org.globus.cas.impl.service.ObjectComparison.

The two comparison classes provided as a part of the distribution are:

ExactComparison: This class does a case-sensitive exact comparison of the object names. If comparisonAlg in the above method is set to ExactComparison, the class in the distribution is loaded and used.
WildcardComparison: This class does wild card matching as described in CAS Simple Policy Language. It assumes that the wild card character is "*" and that the file separator is "/". If comparisonAlg in the above method is set to WildCardComparison, the class in the distribution is loaded and used.

Enrolling Objects

To enroll an object, the user must have cas/enroll_object permission (that is, the use must have permission to perform the enroll_object action on the cas service type).

The enroll operation allows the user to choose a userGroup to have cas/grantAll permission on the enrolled object. The name of the object and the namespace this object belongs to identify an object in the database and should be unique across the CAS database.

To enroll objects:

casAdmin$ cas-enroll [common options] object userGpName objectName namespaceNick

where:

userGpName: Indicates the user group to which cas/grantAll permission should be granted on this trust anchor entity.
objectName: Indicates the name of the object.
namespaceNick: Indicates the nickname of the namespace to which this object belongs.

Enrolling Service Types

To enroll a service type, the user must have cas/enroll_serviceType permission (that is, the user must have permission to perform the enroll_serviceType action on the cas service type).

The enroll operation allows the user to choose a userGroup to have cas/grantAll permission on the enrolled service type. The service type name should be unique across the CAS database.

To enroll service types:

casAdmin$ cas-enroll [common options] serviceType userGpName serviceTypeName

where:

userGpName: Indicates the user group to which cas/grantAll permission should be granted on this trust anchor entity.
serviceTypeName: Indicates the service type name.

Options

Important

If you have an asterisk (*) in your command, you might need to escape it with a backslash ( \ ).

-a, --anonymous

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

-c, --serverCertificate <file>

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

-debug

Runs the client with debug message traces and error stack traces.

-f, --descriptor <file>

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

-help

Prints the usage message for the client.

-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. The value type can be:

msg for GSI Secure Message, or
conv for GSI Secure Conversation.

-p, --protection <type>

Specifies the protection level. type can be:

sig for signature, or
enc for encryption.

-s cas-url

Sets the CAS Service instance, where cas-url is the URL of the CAS service instance. Alternatively, an environment variable can be set as shown here.

The instance URL typically looks like http://Host:Port/wsrf/services/CASService, where Host and Port are the host and port where the container with the CAS service is running.

-v

Prints the version number.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z authorization

Specifies the type of authorization used, such as self or host.

If you cannot use a standard method for authorization, you can use the specific CAS server's identity as the value.

Alternatively, an environment variable can be set as shown here.

	Note
	If the service being contacted is using GSI Secure Transport , then the container credentials configured for the service will be used, even if service/resource level credentials are configured. Hence authorization needs to be done based on the DN of the container credentials.

Usage

For detailed examples of using this command, see Example of CAS Server Administration .

Name

cas-remove — Remove a CAS object from the database

Synopsis

cas-remove [common options] trustAnchor nickname
cas-remove [common options] namespace nickname
cas-remove [common options] object objName namespaceNick
cas-remove [common options] serviceType serviceTypeName

Tool description

Removing Trust Anchors

To remove a trust anchor, the user must have cas/remove permission on that trust anchor. The trust anchor must also be unused (that is, there may not be any users in the database that have this trust anchor or it may not be a part of any object group).

To remove trust anchors:

casAdmin$ cas-remove [options] trustAnchor nickname

where:

nickname: Indica

Software Links

Getting Started

Reference

Manuals

Common Runtime

Security

Data Mgt

WS MDS

Execution Mgt

Globus Toolkit 4.2.0 Developer's Guide

GT 4.2.0 Best Practices for Developing in GT4

1. Implementing Services

1.1. Dynamic resource creation and the factory pattern

1.2. Scalability, recovery and resource persistence

1.3. Concurrent invocations and synchronization

1.4. Lease-based lifetime management

1.5. Resource Types and Services

1.6. Messaging granularity

1.7. Choosing an authentication mechanism

GT 4.2.0 Resource Properties Overview

1. Introduction

2. Security

2.1. Resource properties

2.2. CAS Resource Properties

2.3. Delegation Service Resource properties

2.3.1. Delegation Factory Service

3. Data Management

3.1. RFT Resource Properties

3.1.1. RFT Factory Resource Properties

3.1.2. RFT Resource Properties

3.2. WS RLS Resource Properties

3.2.1. ReplicaLocationCatalog Resource Properties

3.2.2. ReplicaLocationIndex Resource Properties

3.3. Data Replication Service (DRS) Resource properties

4. Information Services

4.1. WS MDS Aggregator Framework Resource Properties

4.1.1. AggregatorServiceGroup Resource Properties

5. Execution Management

5.1. Resource properties

5.1.1. Managed Job Factory Port Type

5.1.2. Managed Job Port Type

5.1.3. Managed Executable Job Port Type

5.1.4. Managed Multi-Job Port Type

GT 4.2.0 Guide to Samples

Asynchronous Event Handling with Examples

GT 4.2.0: Asynchronous Event Handling

1. Examples

2. Event Models

2.1. Blocking Event Model

2.2. Non-blocking Event Model

2.3. Asynchronous Event Model

3. Callback Library

4. Thread Abstraction

5. Asynchronous Model

5.1. Blocking in Callbacks

6. Conclusion

7. References

GT 4.2.0: Asynchronous Event Handling: Example 1

GT 4.2.0: Asynchronous Event Handling: Example 2

GT 4.2.0: Asynchronous Event Handling: Example 3

Globus Toolkit 4.2.0 Commandline Tools

Java WS Core Commands

Name

Synopsis

Tool description

Command syntax

Name

Synopsis

Tool description

Command syntax

Name

Synopsis

Tool description

Command syntax

Name

Synopsis

Tool description

Command syntax

Name

Synopsis