Abstract
This page contains information for commonly performed tasks using GT components. This assumes a default installation and covers the more basic tasks using common tools.
Note that GT itself is typically used as middleware and not intended to be used directly by end-users. Instead, grid developers use the GT to develop higher-level services and systems that are then used by end-users (where GT is essentially the plumbing). However, GT Release Manuals include User's Guides for each established component that describe how the public interfaces are intended to be used - whether it is by a human or a program.
Table of Contents
This step is usually a prerequisite for using GT commands.
Make sure you have set
GLOBUS_LOCATION to the location of your Toolkit installation.
There are two environment scripts called $GLOBUS_LOCATION/etc/globus-user-env.sh and
$GLOBUS_LOCATION/etc/globus-user-env.csh. You should read in whichever one corresponds
to the type of shell you are using.
For example, in csh or tcsh, you would run:
source $GLOBUS_LOCATION/etc/globus-user-env.csh
In sh, bash, ksh, or zsh, you would run:
. $GLOBUS_LOCATION/etc/globus-user-env.sh
Set Globus location:
$ export GLOBUS_LOCATION='/opt/globus/apps/globus-4.2.0'
Source it..
source $GLOBUS_LOCATION/etc/globus-user-env.sh source $GLOBUS_LOCATION/etc/globus-devel-env.sh
Start container (for default installation using Java WS Core):
globus-start-container
Create new grid proxy certificate with grid-proxy-init.
The Java WS Core container is the web services hosting environment based on Java on which the GT higher-level Java web services (such as RFT and CAS) are based.
To start the Java WS Core container in any default installation of GT, run globus-start-container:
$GLOBUS_LOCATION bin/globus-start-container
If you want to run without transport-level security, use the -nosec
option:
$GLOBUS_LOCATION bin/globus-start-container -nosec
The following GT components are higher-level web services based on Java WS Core
You can use the wsrf-query command to query any WSRF resource property document. For example, you can use the following command to query the WS MDS Index Service for all the resource properties collected by the default Index Service on your local host:
$GLOBUS_LOCATION/bin/wsrf-query -s http://localhost:8443/wsrf/services/DefaultIndexService '/*'
The globus-wsc-container command is an implementation of a Web Service container for hosting services written in C. By default, the container will run in the foreground and process SOAP requests until terminated by a signal. See globus-wsc-container documentation for a complete list of command-line options.
%globus-wsc-containerContact: https://grid.example.org:8443/
There is no special command for stopping a C container. If the command is in the foreground (default), then sending the TERM signal (typically ctrl-C).
%globus-wsc-containerContact: https://grid.example.org:8443^CExecution cancelled, cleaning up.%
If the container is in the background, it can be terminated with the
POSIX-standard kill command. If the container was
started with the -pidfile command-line option, that fill
can be read to determine which process to kill. For example:
%globus-wsc-container -bg -pidfile $GLOBUS_LOCATION/var/wsc.pidContact: https://grid.example.org:8443%cat $GLOBUS_LOCATION/var/wsc.pid19773%kill 19773%
The container will automatically remove the PID file
($GLOBUS_LOCATION/var/wsc.pid in this example).
WSRF services share information on resource state through resource properties. C WS Core provides several tools for inspecting these properties. A list of the properties provided by Globus Toolkit services is available in the developer's guide.
The globus-wsrf-get-property and globus-wsrf-get-properties commands provide two options for getting the value of a single resource property or multiple resource properties, respectively. For this example, we'll explore some of the properties provided by the GRAM4 service.
First, we'll check the version information of a GRAM4 service using globus-wsrf-get-property:
%globus-wsrf-get-property-shttps://grid.example.org:8443/wsrf/services/ManagedJobFactoryService\'{http://mds.globus.org/metadata/2005/02}ServiceMetaDataInfo'<ns1:ServiceMetaDataInfo xmlns:ns1="http://mds.globus.org/metadata/2005/02"> <ns1:startTime>2008-06-19T16:34:31.248Z</ns1:startTime> <ns1:version>4.1.0</ns1:version> <ns1:serviceTypeName>ManagedJobFactoryService</ns1:serviceTypeName> </ns1:ServiceMetaDataInfo>%
Now, we'll check for some system-specific information using globus-wsrf-get-properties:
%globus-wsrf-get-properties-shttps://grid.example.org:8443/wsrf/services/ManagedJobFactoryService\'{http://www.globus.org/namespaces/2004/10/gram/job}hostCPUType'\'{http://www.globus.org/namespaces/2004/10/gram/job}hostOSName'<ns1:hostCPUType xmlns:ns1="http://www.globus.org/namespaces/2008/03/gram/job">i686</ns1:hostCPUType> <ns2:hostOSName xmlns:ns2="http://www.globus.org/namespaces/2008/03/gram/job">Linux</ns2:hostOSName>%
The globus-wsrf-query-propery program can be used to perform more sophisticated queries of resource properties using XPath expressions. We can check for the number of local resource managers supported by this installation:
%globus-wsrf-query \-shttps://grid.example.org:8443/wsrf/services/ManagedJobFactoryService\'count(//*[local-name() = "availableLocalResourceManagers"])'2%
We can then get the names of the local resource managers:
%globus-wsrf-query \-shttps://grid.example.org:8443/wsrf/services/ManagedJobFactoryService\'//*[local-name() = "availableLocalResourceManagers"]/*[1]/text()'Fork%globus-wsrf-query \-shttps://grid.example.org:8443/wsrf/services/ManagedJobFactoryService\'//*[local-name() = "availableLocalResourceManagers"]/*[2]/text()'Multi%
Table of Contents
This chapter provides information about basic security tasks in GT 4.2.0.
Security is at the heart of Globus, and unless you are running without security (only recommended for testing),
you will not be able to use most of Globus unless you have obtained a certificate for yourself. (Note that you may
use GridFTP without certificates if you are only using ftp:// or http:// protocols.)
For basic informationa bout obtaining certificates, see Obtaining host certificates in the Installation Guide.
Remember to keep track of when your certificates expire. If your certificates expire, you may not be able to use your services until they are refreshed.
Before using many of the tools in GT, a user must generate a valid user proxy. Use grid-proxy-init. The following is an example:
% $GLOBUS_LOCATION/bin/grid-proxy-init Your identity: /O=Grid/OU=GlobusTest/OU=simpleCA.mymachine/OU=mymachine/CN=John Doe Enter GRID pass phrase for this identity: Creating proxy ................................. Done Your proxy is valid until: Tue Oct 26 01:33:42 2004
Basic authorization in GT is enforced via a grid map file, a file that contains mappings of certificate subject names to local user names, like the following:
"/O=Grid/O=Globus/OU=your.domain.edu/CN=Your Name" youruser
For more information about gridmaps see Section 4, “Add authorization”, Section 4, “Configuring Credential Mappings” and Globus Toolkit Gridmap Processing.
Once you have generated a valid proxy you must create a delegated credential It is important to ensure that you give your delegated credential enough lifetime to support the running time of your replication activities. To delegate your credential use globus-credential-delegate.
% $GLOBUS_LOCATION/bin/globus-credential-delegate -h myhostname \ -p 8443 mycredential.epr EPR will be written to: mycredential.epr Delegated credential EPR: Address: https://128.9.72.118:8443/wsrf/services/DelegationService Reference property[0]: <ns1:DelegationKey xmlns:ns1="http://www.globus.org/08/2004/delegationService" >3b6cb210-e9b2-11d9-ab74-f7fa10f094cd</ns1:DelegationKey>
In most cases, an individual will do the following:
Acquire a user certificate from a certification authority (CA) with grid-cert-request. This certificate will typically be valid for a year or more and will be stored in a file in the individual's home directory.
It is important to keep in mind when your cert will expire - after your user certificate expires, you may not be able to use secure services in GT!
- Use the end-user certificate to create a proxy certificate using grid-proxy-init. This will be used to authenticate the individual to grid services. Proxy certificates typically have a much shorter lifetime than end-user certificates (usually 12 hours). Once your proxy certificate expires, simply rerun grid-proxy-init.
For common errors, see Certificates and Gridmap errors.
The grid-cert-diagnostics program checks prints diagnostics about the user's certificates, and host security environment.
%grid-cert-diagnostics-p
openssl verify -CApath /etc/grid-security/certificates -purpose sslclient ~/.globus/usercert.pem
openssl s_client -ssl3 -cert ~/.globus/usercert.pem -key
~/.globus/userkey.pem -CApath /etc/grid-security/certificates
-connect <host:port>Here <host:port> denotes the
server and port you connect to.
If it prints an error and puts you back at the command prompt, then it typically means that the server has closed the connection, i.e. that the server was not happy with the client's certificate and verification. Check the SSL log on the server.
If the command "hangs" then it has actually opened a telnet style (but secure) socket, and you can "talk" to the server.
You should be able to scroll up and see the subject names of the server's verification chain:
depth=2 /DC=net/DC=ES/O=ESnet/OU=Certificate Authorities/CN=ESnet Root CA 1
verify return:1
depth=1 /DC=org/DC=DOEGrids/OU=Certificate Authorities/CN=DOEGrids CA 1
verify return:1
depth=0 /DC=org/DC=doegrids/OU=Services/CN=wiggum.mcs.anl.gov
verify return:1
In this case, there were no errors. Errors would give you an extra line next to the subject name of the certificate that caused the error.
Table of Contents
If you just want the "rules of thumb" on getting started (without all the details), the
following options using globus-url-copy will normally give
acceptable performance:
globus-url-copy -vb -tcp-bs 2097152 -p 4source_urldestination_url
where:
- -vb
specifies verbose mode and displays:
- number of bytes transferred,
- performance since the last update (currently every 5 seconds), and
- average performance for the whole transfer.
- -tcp-bs
specifies the size (in bytes) of the TCP buffer to be used by the underlying ftp data channels. This is critical to good performance over the WAN.
- -p
Specifies the number of parallel data connections that should be used. This is one of the most commonly used options.
The source/destination URLs will normally be one of the following:
One of the most basic tasks in GridFTP is to "put" files, i.e., moving a file from your
file system to the server. So for example, if you want to move the file /tmp/foo from a file system accessible to the host on which you are running your
client to a file name /tmp/bar on a host named remote.machine.my.edu running a GridFTP server, you would use this command:
globus-url-copy -vb -tcp-bs 2097152 -p 4 file:///tmp/foo gsiftp://remote.machine.my.edu/tmp/bar
![[Note]](/docbook-images/note.gif) | Note |
|---|---|
In theory, |
A get, i.e, moving a file from a server to your file system, would just reverse the source and destination URLs:
![[Tip]](/docbook-images/tip.gif) | Tip |
|---|---|
Remember |
globus-url-copy -vb -tcp-bs 2097152 -p 4 gsiftp://remote.machine.my.edu/tmp/bar file:///tmp/foo
Finally, if you want to move a file between two GridFTP servers (a third party transfer), both URLs would use
gsiftp: as the
protocol:
globus-url-copy -vb -tcp-bs 2097152 -p 4 gsiftp://other.machine.my.edu/tmp/foo gsiftp://remote.machine.my.edu/tmp/bar
If you want more information and details on URLs and the command line options, the Key Concepts gives basic definitions and an overview of the GridFTP protocol as well as our implementation of it.
If you want to access data in a non-POSIX file data source that has a POSIX interface, the standard server will do just fine. Just make sure it is really POSIX-like (out of order writes, contiguous byte writes, etc).
The following information is helpful if you want to use GridFTP to access data in DSIs (such as HPSS and SRB), and non-POSIX data sources.
Architecturally, the Globus GridFTP server can be divided into 3 modules:
- the GridFTP protocol module,
- the (optional) data transform module, and
- the Data Storage Interface (DSI).
In the GT 4.2.0 implementation, the data transform module and the DSI have been merged, although we plan to have separate, chainable, data transform modules in the future.
| Note |
|---|---|
This architecture does NOT apply to the WU-FTPD implementation (GT3.2.1 and lower). |
The GridFTP protocol module is the module that reads and writes to the network and implements the GridFTP protocol. This module should not need to be modified since to do so would make the server non-protocol compliant, and unable to communicate with other servers.
The data transform functionality is invoked by using the ERET (extended retrieve) and ESTO (extended store) commands. It is seldom used and bears careful consideration before it is implemented, but in the right circumstances can be very useful. In theory, any computation could be invoked this way, but it was primarily intended for cases where some simple pre-processing (such as a partial get or sub-sampling) can greatly reduce the network load. The disadvantage to this is that you remove any real option for planning, brokering, etc., and any significant computation could adversely affect the data transfer performance. Note that the client must also support the ESTO/ERET functionality as well.
The Data Storage Interface (DSI) / Data Transform module knows how to read and write to the "local" storage system and can optionally transform the data. We put local in quotes because in a complicated storage system, the storage may not be directly attached, but for performance reasons, it should be relatively close (for instance on the same LAN).
The interface consists of functions to be implemented such as send (get), receive (put), command (simple commands that simply succeed or fail like mkdir), etc..
Once these functions have been implemented for a specific storage system, a client should not need to know or care what is actually providing the data. The server can either be configured specifically with a specific DSI, i.e., it knows how to interact with a single class of storage system, or one particularly useful function for the ESTO/ERET functionality mentioned above is to load and configure a DSI on the fly.
See Appendix A, Developing DSIs for GridFTP for more information.
Last Update: August 2005
Working with Los Alamos National Laboratory and the High Performance Storage System (HPSS) collaboration (http://www.hpss-collaboration.org), we have written a Data Storage Interface (DSI) for read/write access to HPSS. This DSI would allow an existing application that uses a GridFTP compliant client to utilize an HPSS data resources.
This DSI is currently in testing. Due to changes in the HPSS security mechanisms, it requires HPSS 6.2 or later, which is due to be released in Q4 2005. Distribution for the DSI has not been worked out yet, but it will *probably* be available from both Globus and the HPSS collaboration. While this code will be open source, it requires underlying HPSS libraries which are NOT open source (proprietary).
| Note |
|---|---|
This is a purely server side change, the client does not know what DSI is running, so only a site that is already running HPSS and wants to allow GridFTP access needs to worry about access to these proprietary libraries. |
Last Update: August 2005
Working with the SRB team at the San Diego Supercomputing Center, we have written a Data Storage Interface (DSI) for read/write access to data in the Storage Resource Broker (SRB) (http://www.npaci.edu/DICE/SRB). This DSI will enable GridFTP compliant clients to read and write data to an SRB server, similar in functionality to the sput/sget commands.
This DSI is currently in testing and is not yet publicly available, but will be available from both the SRB web site (here) and the Globus web site (here). It will also be included in the next stable release of the toolkit. We are working on performance tests, but early results indicate that for wide area network (WAN) transfers, the performance is comparable.
When might you want to use this functionality:
- You have existing tools that use GridFTP clients and you want to access data that is in SRB
- You have distributed data sets that have some of the data in SRB and some of the data available from GridFTP servers.
Pipelining allows the client to have many outstanding, unacknowledged transfer commands at once. Instead of being forced to wait for the "Finished response" message, the client is free to send transfer commands at any time.
Pipelining is enabled by using the -pp option:
globus-url-copy -pp
GridFTP Where There Is FTP (GWTFTP) is an intermediate program that acts as a proxy between existing FTP clients and GridFTP servers. Users can connect to GWFTP with their favorite standard FTP client, and GWFTP will then connect to a GridFTP server on the client’s behalf. To clients, GWFTP looks much like an FTP proxy server. When wishing to contact a GridFTP server, FTP clients instead contact GWTFTP.
Clients tell GWFTP their ultimate destination via the FTP USER <username> command. Instead of
entering their username, client users send the following:
USER<GWTFTP username>::<GridFTP server URL>
This command tells GWTFTP the GridFTP endpoint with which the client wants to communicate. For example:
USER bresnaha::gsiftp://wiggum.mcs.anl.gov:2811/
| Note |
|---|---|
Requires GSI C security. |
To transfer a single file to many destinations in a multicast/broadcast, use the new
-mc option.
| Note |
|---|---|
To use this option, the admin must enable multicasting. Click here for more information. |
globus-url-copy -vb -tcp-bs 2097152 -p 4 -mcfilenamesource_url
The filename must contain a line-separated list of destination
urls. For example:
gsiftp://localhost:5000/home/user/tst1 gsiftp://localhost:5000/home/user/tst3 gsiftp://localhost:5000/home/user/tst4
For more flexibility, you can also specify a single destination url on the command line in addition to the urls in the file. Examples are:
globus-url-copy -MC multicast.file gsiftp://localhost/home/user/src_file
or
globus-url-copy -MC multicast.file gsiftp://localhost/home/user/src_file gsiftp://localhost/home/user/dest_file1
Along with specifying the list of destination urls in a file, a set of options for each
url can be specified. This is done by appending a ? to the
resource string in the url followed by semicolon-separated key value pairs. For example:
gsiftp://dst1.domain.com:5000/home/user/tst1?cc=1;tcpbs=10M;P=4
This indicates that the receiving host dst1.domain.com will use 4
parallel stream, a tcp buffer size of 10 MB, and will select 1 host when forwarding on data
blocks. This url is specified in the -mc file as described above.
The following is a list of key=value options and their meanings:
- P=
integer - The number of parallel streams this node will use when forwarding.
- cc=
integer - The number of urls to which this node will forward data.
- tcpbs=
formatted integer - The TCP buffer size this node will use when forwarding.
- urls=
string list - The list of urls that must be children of this node when the spanning tree is complete.
- local_write=
boolean: y|n - Determines if this data will be written to a local disk, or just forwarded on to the next hop. This is explained more in the Network Overlay section.
- subject=
string - The DN name to expect from the servers this node is connecting to.
In addition to allowing multicast, this function also allows for creating user-defined network routes.
If the local_write option is set to n,
then no data will be written to the local disk, the data will only be forwarded on.
If the local_write option is set to n and is used with the cc=1 option, the data will be
forwarded on to exactly 1 location.
This allows the user to create a network overlay of data hops using each GridFTP server as a router to the ultimate destination.
The Java clients, rft and rft-delete commands are available for very simple transfers. For more options, use the programming instructions here.
Beginning with 4.2.0, RFT also offers a new C client, globus-crft.
To submit a transfer request the user must first create a 'transfer file'. Each line of this ASCII text file is a source/destination URL pair. There can be any number of of lines per file. An example file follows:
gsiftp://localhost:2811/etc/group gsiftp://localhost:2811/tmp/test_crft
gsiftp://ftp.globus.org:2811/pub/README gsiftp://myhost.here/home/user/file
This file requests two transfers. The first will user the GridFTP server running on the localhost to transfer /etc/group to /tmp/test_crft. The second will transfer the file /pub/README on ftp.globus.org to the file /home/user/file located on myhost.here
Once the transfer file is created globus-crft can be used in a variety of ways to transfer a file. The most simple is the blocking transfer:
% globus-crft -c -s -m -vb -f <transfer file> -e <container contact string>
Looking at each option individually, this command line does the following
-
-cCreate a new RFT server.,-sSubmit the transfer request. Since RFT is a 2 phase commit we allow the client the ability to do them in separate stages, however it is expected that the vast majority of the time -c and -s will be used together.
-mMonitor the transfers. When this option is used the client will block until all transfers have completed. It monitors the status of the transfers along the way and can report it to the user.
-vbDisplay verbose output. This just increases the level of diagnostic messages sent to stdout. When combined with -m it will allow the user to see the status of a transfer.
- -f <transfer file>
This option is a pointer to the transfer file described above.
- -e <container contact strings>
The contact string is in the following form:
https://hostname.com:8443/wsrf/services/
The strings ___ and ___ will be appended to the given string in order for the client to interact with that containers delegation service and RFT service.
The client can do non-blocking RFT submission. It can submit an RFT request and then terminate, returning later to monitor the status of the request. To accomplish this the client saves the EPR of the newly created RFT service to disk.
% globus-crft -c -s -f <transfer file> -e <container contact string> \
-ef <epr output file>
At some point later the client uses this same file to monitor the state of the transfer:
% globus-crft -ef <epr input file> --getOverallStatus
| Note |
|---|---|
Note that in both cases the option |
Once a transfer request completes, the user should destroy the resources associated with it. If the user stored the EPR of the service it created, this can be done with:
% globus-crft -ef <epr input file> --destroy
To check whether your server is active you may use the globus-rls-admin(1) ping command.
% $GLOBUS_LOCATION/bin/globus-rls-admin -p rls://localhost
ping rls://localhost: 0 seconds
When the RLS server is first installed its database of replica location information will be empty, as expected. To create a replica location mapping, use the globus-rls-cli(1) create command. Replica information in RLS is represented as mappings from logical names to target names. Typically, the logical name will be a unique identifier for a given replicated data set and the target name will be a URL identifying a particular replica of the data set.
% $GLOBUS_LOCATION/bin/globus-rls-cli create my-logical-name-1 url-for-target-name-1 rls://localhost
| Note |
|---|---|
The create command is intended for creating the initial replica mapping entry for a given logical name. If the user attempts to create another entry using an existing logical name, RLS will report a user error. To map additional target names to an existing logical name, see Section 4, “Adding replica location mappings”. |
To map additional target names to a logical name created by the previously described create command, use the globus-rls-cli(1) add command.
% $GLOBUS_LOCATION/bin/globus-rls-cli add my-logical-name-1 url-for-target-name-2 rls://localhost
Once your RLS server is populated with replica location mappings, you can query the server for useful information using the globus-rls-cli(1) query command.
% $GLOBUS_LOCATION/bin/globus-rls-cli query lrc lfn my-logical-name-1 rls://localhost
my-logical-name-1: url-for-target-name-1
my-logical-name-1: url-for-target-name-2
To remove unwanted replica location mappings from your RLS server, use the globus-rls-cli(1) delete command. The delete operation works directly on the mapping and indirectly on the logical and target names. When the delete operation is performed by the RLS server the association between the specified logical name and the specified target name is eliminated. However, there may still be other target names associated with the logical name, and there could still be other logical names associated with the target name, though the latter scenario is less likely. Only when all mapping associations for a given logical name (or a given target name) are eliminated (i.e., the specified logical name has no target names associated with it) will the logical (or target) name be deleted from the RLS server.
% $GLOBUS_LOCATION/bin/globus-rls-cli delete my-logical-name-1 url-for-target-name-1 rls://localhost % $GLOBUS_LOCATION/bin/globus-rls-cli query lrc lfn my-logical-name-1 rls://localhost my-logical-name-1: url-for-target-name-2 % $GLOBUS_LOCATION/bin/globus-rls-cli delete my-logical-name-1 url-for-target-name-2 rls://localhost % $GLOBUS_LOCATION/bin/globus-rls-cli query lrc lfn my-logical-name-1 rls://localhost globus_rls_client: LFN doesn't exist: my-logical-name-1
The globus-rls-cli(1) supports a variety of bulk operations that enhance productivity for users and reduce network connection overhead from making multiple, separate invocations of the client. The general pattern for bulk operation support as implemented by the client is a parameter list consisting of bulk command-name [command-modifiers] param-1 param-2 param-N, such as bulk query lrc lfn my-logical-name-1 my-logical-name-2 my-logical-name-3.
% $GLOBUS_LOCATION/bin/globus-rls-cli bulk create my-logical-name-1 url-for-target-name-1-1 my-logical-name-2 url-for-target-name-2-1 rls://localhost % $GLOBUS_LOCATION/bin/globus-rls-cli bulk add my-logical-name-1 url-for-target-name-1-2 my-logical-name-2 url-for-target-name-2-2 rls://localhost % $GLOBUS_LOCATION/bin/globus-rls-cli bulk query lrc lfn my-logical-name-1 my-logical-name-2 my-logical-name-3 rls://localhost my-logical-name-3: LFN doesn't exist my-logical-name-2: url-for-target-name-2-1 my-logical-name-2: url-for-target-name-2-2 my-logical-name-1: url-for-target-name-1-1 my-logical-name-1: url-for-target-name-1-2
The globus-rls-cli(1) supports an interactive mode in addition to the general command-line mode. To enter the interactive mode, simply invoke the client without any command.
% $GLOBUS_LOCATION/bin/globus-rls-cli rls://localhost
rls> query lrc lfn my-logical-name-2
my-logical-name-2: url-for-target-name-2-1
my-logical-name-2: url-for-target-name-2-2
rls> query lrc lfn my-logical-name-1
my-logical-name-1: url-for-target-name-1-1
my-logical-name-1: url-for-target-name-1-2
rls> bulk delete my-logical-name-1 url-for-target-name-1-1 my-logical-name-1
url-for-target-name-1-2 my-logical-name-2 url-for-target-name-2-1
my-logical-name-2 url-for-target-name-2-2
rls> bulk query lrc lfn my-logical-name-2 my-logical-name-1
my-logical-name-1: LFN doesn't exist
my-logical-name-2: LFN doesn't exist
rls> exit
Use the globus-replicalocation-createmappings(1) tool to create mappings.
% $GLOBUS_LOCATION/bin/globus-replicalocation-createmappings \
-s https://localhost:8443/wsrf/services/ReplicaLocationCatalogService \
mydata1 gsiftp://path/a/to/mydata1
No output is expect from this command when successful.
Use the globus-replicalocation-addmappings(1) tool to add mappings.
% $GLOBUS_LOCATION/bin/globus-replicalocation-addmappings \
-s https://localhost:8443/wsrf/services/ReplicaLocationCatalogService \
mydata1 gsiftp://path/b/to/mydata1
No output is expect from this command when successful.
Use the globus-replicalocation-defineattributes(1) tool to define attribute definitions.
% $GLOBUS_LOCATION/bin/globus-replicalocation-defineattributes \
-s https://localhost:8443/wsrf/services/ReplicaLocationCatalogService \
myattr1 logical string
No output is expect from this command when successful.
Use the globus-replicalocation-addattributes(1) tool to add attributes.
% $GLOBUS_LOCATION/bin/globus-replicalocation-addattributes \
-s https://localhost:8443/wsrf/services/ReplicaLocationCatalogService \
mydata1 myattr1 logical string attribute-value-goes-here
No output is expect from this command when successful.
Use the wsrf-query tool to query mappings.
% $GLOBUS_LOCATION/bin/wsrf-query \
-s https://localhost:8443/wsrf/services/ReplicaLocationCatalogService \
"query-target: mydata1" \
"http://globus.org/replica/location/06/01/QueryDialect"
<ns1:MappingStatusType ns1:logical="mydata1"
ns1:target="gsiftp://path/a/to/mydata1"
xmlns:ns1="http://www.globus.org/namespaces/2005/08/replica/location"/>
<ns1:MappingStatusType ns1:logical="mydata1"
ns1:target="gsiftp://path/b/to/mydata1"
xmlns:ns1="http://www.globus.org/namespaces/2005/08/replica/location"/>
Use the wsrf-query tool to query attributes.
% $GLOBUS_LOCATION/bin/wsrf-query \
-s https://localhost:8443/wsrf/services/ReplicaLocationCatalogService \
"query-logical-attributes: mydata1" \
"http://globus.org/replica/location/06/01/QueryDialect"
<ns1:AttributeStatusType ns1:key="mydata1" ns1:name="myattr1"
ns1:objtype="logical" ns1:status="attributeExists" ns1:valtype="string"
xmlns:ns1="http://www.globus.org/namespaces/2005/08/replica/location">
<_value xmlns="">attribute-value-goes-here</_value>
</ns1:AttributeStatusType>
A key parameter for any replication request is the request file. The replication request file is a text file containing CRLF-terminated rows of tab-delimited pairs of Logical Filename (LFN) names and destination (URL) locations. An example of such a file is shown.
% cat testrun.req
testrun-1 gsiftp://myhost:9001/sandbox/files/testrun-1
testrun-2 gsiftp://myhost:9001/sandbox/files/testrun-2
testrun-3 gsiftp://myhost:9001/sandbox/files/testrun-3
testrun-4 gsiftp://myhost:9001/sandbox/files/testrun-4
testrun-5 gsiftp://myhost:9001/sandbox/files/testrun-5
| Note |
|---|---|
The LFNs in the left column of the request file (e.g., |
The initial step for any replication is to create the replication resource. Creating the resource depends on the availability of a DRS service, a delegated credential, and a properly formatted replication request file. The replication request file must be specified by its URL. Currently supported URL schemes for the request file include file, http, and ftp. If the replication client is run local to the service the file scheme is appropriate, whereas if the client is remote than the latter schemes must be used. It is a good practice to specify a filename to save the replication resource's endpoint reference. The endpoint reference is required for all other operations on the resource, such as getting resource properties, starting/stopping, and destroying it. Numerous options are available to influence the behavior of the data replication activities (see globus-replication-create(1)). One option of particular interest is the --start option, which immediately starts the replication activities following creation of the replication resource. An example of using the globus-replication-create(1) tool is shown.
% $GLOBUS_LOCATION/bin/globus-replication-create -s \ https://myhost:8443/wsrf/services/ReplicationService \ -C mycredential.epr -V myreplicator.epr file:///scratch/testrun.req
This command does not write to stdout when successful unless the --debug option is specified.
Once a replication resource has been create, the replication activities may be started. As mentioned in Create replication resource the replication may be immediately started after it is created. If the immediate start option is not specified, the globus-replication-start(1) tool must be used to start the replication.
% $GLOBUS_LOCATION/bin/globus-replication-start -e myreplicator.epr
No output is expect from this command when successful.
Throughout the lifecycle and after the completion of the replication resource, it will be important to lookup its Resource Properties. The standard WS-RF port types are supported and the supplied tools (e.g., wsrf-get-property) may be used with the DRS and its resources.
% $GLOBUS_LOCATION/bin/wsrf-get-property -e myreplicator.epr \
"{http://www.globus.org/namespaces/2005/05/replica/replicator}status"
<ns1:status xmlns:ns1="http://www.globus.org/namespaces/2005/05/replica/replicator">
Active</ns1:status>
And,
% $GLOBUS_LOCATION/bin/wsrf-get-property -e myreplicator.epr \
"{http://www.globus.org/namespaces/2005/05/replica/replicator}count"
<ns1:count xmlns:ns1="http://www.globus.org/namespaces/2005/05/replica/replicator">
<ns1:total>10</ns1:total>
<ns1:finished>0</ns1:finished>
<ns1:failed>0</ns1:failed>
<ns1:terminated>0</ns1:terminated>
</ns1:count>
Throughout the lifecycle and after the completion of the replication resource, it may be helpful to find individual replication items in the replication resource to inspect the detailed status of the replication activities. The globus-replication-finditems(1) tool is used to find replication items. The following example demonstrates the usage when finding a limited number of items, offset into the lookup results set, for a specified status.
% $GLOBUS_LOCATION/bin/globus-replication-finditems -e myreplicator.epr -S Pending -O 1 -L 2
<ns1:FindItemsResponse xmlns:ns1="http://www.globus.org/namespaces/2005/05/replica/replicator">
<ns1:items xsi:type="ns1:ReplicationItemType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns1:uri xsi:type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema">testrun-2</ns1:uri>
<ns1:priority xsi:type="xsd:int" xmlns:xsd="http://www.w3.org/2001/XMLSchema">1000</ns1:priority>
<ns1:status xsi:type="ns1:ReplicationItemStatusEnumerationType">Pending</ns1:status>
<ns1:destinations xsi:type="ns1:DestinationType">
<ns1:uri xsi:type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
gsiftp://myhost:9001/sandbox/files/testrun-2</ns1:uri>
<ns1:status xsi:type="ns1:DestinationStatusEnumerationType">Pending</ns1:status>
</ns1:destinations>
</ns1:items>
<ns1:items xsi:type="ns1:ReplicationItemType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns1:uri xsi:type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema">testrun-3</ns1:uri>
<ns1:priority xsi:type="xsd:int" xmlns:xsd="http://www.w3.org/2001/XMLSchema">1000</ns1:priority>
<ns1:status xsi:type="ns1:ReplicationItemStatusEnumerationType">Pending</ns1:status>
<ns1:destinations xsi:type="ns1:DestinationType">
<ns1:uri xsi:type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
gsiftp://myhost:9001/sandbox/files/testrun-3</ns1:uri>
<ns1:status xsi:type="ns1:DestinationStatusEnumerationType">Pending</ns1:status>
</ns1:destinations>
</ns1:items>
</ns1:FindItemsResponse>
When the replication is complete, the replication resource may be destroyed. Destroying the replication resource will help to free up system resources (namely, memory), especially in the case that the replication entailed a large amount of individual replication activities (i.e., many files specified in the replication request file). The standard WS-RF port types are supported and the supplied wsrf-destroy tool may be used to destroy the DRS resource.
% $GLOBUS_LOCATION/bin/wsrf-destroy -e myreplicator.epr
Destroy operation was successful
Table of Contents
To view the information contained in an Index Service, you can use either Java WS Core commands (such as wsrf-query) or WebMDS.
A typical example of using the default Index Service is with the wsrf-query Java WS Core command. For example:
$GLOBUS_LOCATION/bin/wsrf-query -s https://localhost:8443/wsrf/services/DefaultIndexService '/*'
displays all the resource properties collected by the default Index Service on your local host.
You can also use an XPath query to drill down your search as well as other Java WS Core commands such as wsrf-get-property and wsrf-get-properties. For more information, review the User's Guide.
Once you've deployed the WebMDS servlet,
simply point your web browser at http://your-tomcat-host:your-tomcat-port/webmds and
click on the link labelled "A list of resources registered to the local default index service". For more information, see
Graphical User Interface.
For more detailed information about changing the look of WebMDS and more advanced configuration, see the WebMDS Admin Guide.
End-users will typically interact with the Trigger Service indirectly, using some mechanism specific to the triggered executable program (for example, an executable program may send mail to an end-user or write a structured log file that will later be read by some other program).
For more detailed information, see the Trigger Basic How To.
Table of Contents
- 1. Delegating credentials
- 2. Local resource managers interfaced by a GRAM4 installation
- 3. Submitting Jobs Specified in JDD
- 3.1. Simple interactive job
- 3.2. Streaming output
- 3.3. Using a contact string
- 3.4. Using a job description
- 3.5. Using a contact string in the job description
- 3.6. Specifying a local resource manager
- 3.7. Job with staging
- 3.8. Specifying a local user id in the job description
- 3.9. Using substitution variables
- 3.10. Using custom job description extensions
- 3.11. Multi-Job
- 4. Submitting jobs with metascheduling functionality
There are three different uses of delegated credentials:
- for use by the MEJS to create a remote user proxy
- for use by the MEJS to contact RFT
- for use by RFT to contact the GridFTP servers. The EPRs to each of these are specified in three job description elements -- they are jobCredentialEndpoint, stagingCredentialEndpoint, and transferCredentialEndpoint respectively. Please Job Description Schema Reference and RFT transfer request schema documentation for more details about these elements.
The globusrun-ws client can either delegate
these credentials automatically for a particular job, or it can reuse
pre-delegated credentials (see next paragraph) through the use of command-line
arguments for specifying the credentials' EPR files. Please see the
GRAM4 Commands for details on these command-line arguments.
It is possible to use delegation command-line tools to obtain and refresh delegated credentials in order to use them when submitting jobs to GRAM4. This, for instance, enables the submission of many jobs using a shared set of delegated credentials. This can significantly decrease the number of remote calls for a set of jobs, thus improving performance.
The following example shows how to delegate credentials.
globus-credential-delegate delegates to the specified
delegation factory on lucky0.mcs.anl.gov, prints some information and stores the
endpoint reference of the delegated credentials into the file delegCred.epr
[martin@osg-test1 ~]$ globus-credential-delegate \ > -s https://lucky0.mcs.anl.gov:8443/wsrf/services/DelegationFactoryService \ > delegCred.epr Delegated credential EPR: Address: https://lucky0.mcs.anl.gov:8443/wsrf/services/DelegationService Reference property[0]: <ns1:DelegationKey xmlns:ns1="http://www.globus.org/08/2004/delegationService"> 55e2a450-58be-11dd-b83c-e4ec640dfe13 </ns1:DelegationKey>
To destroy the delegated credential use wsrf-destroy:
[martin@osg-test1 jobs]$ wsrf-destroy -e delegCred.epr Destroy operation was successful
For more information about the delegation command-line tools see Command-line tools
A GRAM4 instance can interface to more than one local resource manager (LRM), as shown in the previous section. A user can explicitly specify what LRM should be used for a job. But in a larger Grid it might be confusing for users to remember which LRM's are available on which machines.
That's why GRAM4 configures a default local resource manager, which is used for job submission if the client didn't explicitly specify one.
You can check the resource property
availableLocalResourceManagers
of a GRAM4 factory service to get that information. Replace host and port in
the below example to query against other containers:
[martin@osg-test1 ~]$ globus-wsrf-get-property \
-s https://osg-test1.unl.edu:8443/wsrf/services/ManagedJobFactoryService \
"{http://www.globus.org/namespaces/2008/03/gram/job}availableLocalResourceManagers"The result on that machine is (formatted for better readability) shows that the local resource managers Fork, Multi, Condor and PBS are available:
<ns1:availableLocalResourceManagers
xmlns:ns1="http://www.globus.org/namespaces/2008/03/gram/job">
<ns1:localResourceManager>Fork</ns1:localResourceManager>
<ns1:localResourceManager>Multi</ns1:localResourceManager>
<ns1:localResourceManager>Condor</ns1:localResourceManager>
<ns1:localResourceManager>PBS</ns1:localResourceManager>
</ns1:availableLocalResourceManagers>A more typical result in a production environment is probably Fork, Multi and just one additional LRM like Condor, PBS or LSF.
You can check the resource property
defaultLocalResourceManagers
of a GRAM4 factory service to get that information. Replace host and port in
the below example to query against other containers:
[martin@osg-test1 ~]$ globus-wsrf-get-property \
-s https://osg-test1.unl.edu:8443/wsrf/services/ManagedJobFactoryService \
"{http://www.globus.org/namespaces/2008/03/gram/job}localResourceManager"The result on that machine shows that PBS is the default local resource managers:
<ns1:localResourceManager xmlns:ns1="http://www.globus.org/namespaces/2008/03/gram/job">
PBS
</ns1:localResourceManager>
Use the globusrun-ws program to submit a
simple job without writing a job description document. Use the -c argument,
a job description will be generated assuming the first arg is the executable
and the remaining are arguments. For example:
% globusrun-ws -submit -c /bin/touch touched_it Submitting job...Done. Job ID: uuid:4a92c06c-b371-11d9-9601-0002a5ad41e5 Termination time: 04/23/2005 20:58 GMT Current job state: Active Current job state: CleanUp Current job state: Done Destroying job...Done.
Confirm on the server-side that the job worked by verifying the file was touched:
% ls -l ~/touched_it -rw-r--r-- 1 smartin globdev 0 Apr 22 15:59 /home/smartin/touched_it % date Fri Apr 22 15:59:20 CDT 2005
Note: You did not tell globusrun-ws where to run your job, so the default of localhost was used.
Also note, that globusrun-ws destroyed the job after it was fully processed.
We call this kind of job interactive, because globusrun-ws does not return after submission. It subscribes for status update notifications of the job and informs the user about a status change as soon as it changes. Once it gets the information the the job has been fully processed it destroys the job, which means that internal state belonging to the job is cleaned up on the server-side.
A user can request that the output of the program is sent back directly to
the client as soon as it's available. This is useful if a user does not
want to do additional file staging for a quick job. To enable this, specify
the -s option.
[martin@osg-test1 ~]$ globusrun-ws -submit \
-F https://lucky0.mcs.anl.gov:8443/wsrf/services/ManagedJobFactoryService \
-s -c /bin/echo hello world!
Delegating user credentials...Done.
Submitting job...Done.
Job ID: uuid:1731f602-22fe-11dd-879c-0013d4c3b957
Termination time: 05/16/3008 04:10 GMT
Current job state: Active
Current job state: CleanUp-Hold
hello world!
Current job state: CleanUp
Current job state: Done
Destroying job...Done.
Cleaning up any delegated credentials...Done.
If you want the output of the job to be written to a local file instead
of the terminal you'll have to add the -so
option:
[martin@osg-test1 ~]$ globusrun-ws -submit \
-F https://lucky0.mcs.anl.gov:8443/wsrf/services/ManagedJobFactoryService \
-s -so job.out -c /bin/echo hello world!
Delegating user credentials...Done.
Submitting job...Done.
Job ID: uuid:1731f602-22fe-11dd-879c-0013d4c3b957
Termination time: 05/16/3008 04:10 GMT
Current job state: Active
Current job state: CleanUp-Hold
Current job state: CleanUp
Current job state: Done
Destroying job...Done.
Cleaning up any delegated credentials...Done.Check the output in the specified file:
[martin@osg-test1 ws-gram]$ cat job.out hello, world!
Note that a GridFTP server must be running on the remote machine (lucky0) to enable streaming.
Note that streaming output adds some overhead to the submission and will probably be significantly slower compared to a job without streaming. An alternative to streaming is to use staging to transport the output of the executable back to the client. This however requires that a GridFTP server is running on the client machine.
Use globusrun-ws to submit the same touch job, but this time tell globusrun-ws to run the job on another machine (lucky0.mcs.anl.gov:8443). A GT4 server with GRAM4 installed must run on that machine and listen on port 8443.
% globusrun-ws -submit \ -F https://lucky0.mcs.anl.gov:8443/wsrf/services/ManagedJobFactoryService \ -c /bin/touch touched_it Submitting job...Done. Job ID: uuid:3050ad64-b375-11d9-be11-0002a5ad41e5 Termination time: 04/23/2005 21:26 GMT Current job state: Active Current job state: CleanUp Current job state: Done Destroying job...Done.
Type globusrun-ws -help to learn the details about the contact string.
The specification of a job to submit is to be written by the user in a job description XML file.
Here is an example of a simple job description:
<job>
<executable>/bin/echo</executable>
<argument>this is an example_string </argument>
<argument>Globus was here</argument>
<stdout>${GLOBUS_USER_HOME}/stdout</stdout>
<stderr>${GLOBUS_USER_HOME}/stderr</stderr>
</job>Tell globusrun-ws to read the job description from a file, using the -f argument:
% bin/globusrun-ws -submit -f simple.xml
Submitting job...Done.
Job ID: uuid:c51fe35a-4fa3-11d9-9cfc-000874404099
Termination time: 12/17/2004 20:47 GMT
Current job state: Active
Current job state: CleanUp
Current job state: Done
Destroying job...Done.
Note the usage of the substitution variable ${GLOBUS_USER_HOME}
which resolves to the user home directory.
Here is an example with more job description parameters:
<?xml version="1.0" encoding="UTF-8"?>
<job>
<executable>/bin/echo</executable>
<directory>/tmp</directory>
<argument>12</argument>
<argument>abc</argument>
<argument>34</argument>
<argument>this is an example_string </argument>
<argument>Globus was here</argument>
<environment>
<name>PI</name>
<value>3.141</value>
</environment>
<stdin>/dev/null</stdin>
<stdout>stdout</stdout>
<stderr>stderr</stderr>
<count>2</count>
</job>Note that in this example, a <directory> element specifies the current directory for the execution
of the command on the execution machine to be /tmp, and the standard output is
specified as the relative path stdout. The output is therefore written to /tmp/stdout:
% cat /tmp/stdout
12 abc 34 this is an example_string Globus was here
Instead of specifying the contact string on the command-line, you can also put it in the job description:
<job xmlns:wsa="http://www.w3.org/2005/08/addressing">
<factoryEndpoint>
<wsa:Address>
https://osg-test1.unl.edu:8443/wsrf/services/ManagedJobFactoryService
</wsa:Address>
</factoryEndpoint>
<executable>/bin/date</executable>
</job>Submit the job with the following command (assuming the above description has been stored in the file job.xml):
% bin/globusrun-ws -submit -f job.xml
| Note |
|---|---|
This time you don't have to specify the -F option. |
Note that at this point you didn't specify any local resource manager related information. If a user does not specify anything then the job is run by the default local resource manager, that is defined on the server-side. If an admin e.g. configured Condor as default local resource manager, then the jobs submitted so far will be managed by Condor on the server-side.
Check the section Local resource managers interfaced by a GRAM4 installation to find out which local resource managers are available in a GRAM4 installation and which one is configured as the default.
As said, if you want to submit a job to the default local resource manager, all you have to do is to just NOT specify any local resource manager in your submission, neither in the job description, nor on the command-line. The above examples show how to do it.
If you want to submit a job to a non-default local resource manager, or if you just want to be explicit in what you specify, you'll have to specify the local resource manager in your submission. Using globusrun-ws, there are two ways to specify a local resource manager:
- as command-line argument of globusrun-ws
(
-Ft <lrm>) - in the factoryEndpoint element in the job description
Example: the following job will be submitted to Condor:
globusrun-ws -submit \ -F osg-test1.unl.edu:8443/wsrf/services/ManagedJobFactoryService \ -Ft Condor \ -c /bin/date
Or with a job description that contains a factoryEndpoint:
<job xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:gram="http://www.globus.org/namespaces/2008/03/gram/job">
<factoryEndpoint>
<wsa:Address>
https://osg-test1.unl.edu:8443/wsrf/services/ManagedJobFactoryService
</wsa:Address>
<wsa:ReferenceParameters>
<gram:ResourceID>Condor</gram:ResourceID>
</wsa:ReferenceParameters>
</factoryEndpoint>
<executable>/bin/date</executable>
</job>Submit that job (assuming the description is stored in the file myJob.xml):
globusrun-ws -submit -f myJob.xml
In order to do file staging one must add specific elements to the job description and delegate credentials appropriately (see Section 2, “Delegating credentials”). The file transfer directives follow the RFT syntax, which allows only for third-party transfers. Each file transfer must therefore specify a source URL and a destination URL. URLs are specified as GridFTP URLs (for remote files) or as file URLs (for files local to the service--these are converted internally to full GridFTP URLs by the service).
For instance, in the case of staging a file in, the source
URL would be a GridFTP URL (for instance
gsiftp://job.submitting.host:2811/tmp/mySourceFile
) resolving to a source document accessible on the file system
of the job submission machine (for instance /tmp/mySourceFile
). At run-time the Reliable File Transfer service used by the
MEJS on the remote machine would reliably fetch the remote file using the
GridFTP protocol and write it to the specified local file (for instance
file:///${GLOBUS_USER_HOME}/my_transfered_file,
which resolves to ~/my_transfered_file). Here
is how the stage-in directive would look like:
<fileStageIn>
<transfer>
<sourceUrl>gsiftp://job.submitting.host:2811/tmp/mySourceFile</sourceUrl>
<destinationUrl>file:///${GLOBUS_USER_HOME}/my_transfered_file</destinationUrl>
</transfer>
</fileStageIn>
Note: additional RFT-defined quality of service requirements can be specified for each transfer. See the RFT documentation for more information.
Here is an example job description with file stage-in and stage-out:
<job>
<executable>my_echo</executable>
<directory>${GLOBUS_USER_HOME}</directory>
<argument>Hello</argument>
<argument>World!</argument>
<stdout>${GLOBUS_USER_HOME}/stdout</stdout>
<stderr>${GLOBUS_USER_HOME}/stderr</stderr>
<fileStageIn>
<transfer>
<sourceUrl>gsiftp://job.submitting.host:2811/bin/echo</sourceUrl>
<destinationUrl>file:///${GLOBUS_USER_HOME}/my_echo</destinationUrl>
</transfer>
</fileStageIn>
<fileStageOut>
<transfer>
<sourceUrl>file:///${GLOBUS_USER_HOME}/stdout</sourceUrl>
<destinationUrl>gsiftp://job.submitting.host:2811/tmp/stdout</destinationUrl>
</transfer>
</fileStageOut>
<fileCleanUp>
<deletion>
<file>file:///${GLOBUS_USER_HOME}/my_echo</file>
</deletion>
</fileCleanUp>
</job>Note that the job description XML does not need to include a reference to the schema that describes its syntax. As a matter of fact it is possible to omit the namespace in the GRAM job description XML elements as well. The submission of this job to the GRAM services causes the following sequence of actions:
- The
/bin/echoexecutable is transfered from the submission machine to the GRAM host file system. The destination location is the HOME directory of the user on behalf of whom the job is executed by the GRAM services (see<fileStageIn>). - The transfered executable is used to print a test string
(see
<executable>,<directory>and the<argument>elements) on the standard output, which is redirected to a local file (see<stdout>). - The standard output file is transfered to the submission machine
(see
<fileStageOut>). - The file that was initially transfered during the stage-in phase is removed
from the file system of the GRAM installation (see
<fileCleanup>).
Submit that job (assuming the description is stored in the file myJob.xml):
globusrun-ws -submit -S -f myJob.xml
The flag -S tells globusrun-ws to delegate
credentials so that Gram4 can call the file transfer service RFT on behalf of
the submitting user, and that RFT can interact with the gridftp servers on
behalf of the submitting user.
If you already delegated credentials (see Delegating credentials for how to delegate a credential) and have an endpoint reference of that delegated credentials stored in the file delegCred.epr and want them to be used for the transfers instead of globusrun-ws delegating new credentials, you can tell globusrun-ws to use your credentials:
globusrun-ws -submit -Sf delegCred.epr -Tf delegCred.epr -f myJob.xml
The -Sf flag tells that the specified credential is
to be used by Gram4 to call RFT on behalf of the user, and the
-Tf flag tells that the specified credential is
to be used by RFT to interact with the GridFTP servers.
If a user has more than one user account on a server and the distinguished name (DN) of the user's certificate is mapped to all these user accounts, a user can specify which local account should be used by GRAM4 for the job submission. By default the first local user account that is defined is used for job submission. If this is not the one that should be used the user must explicitly specify the account to be used. The following dummy job description shows how to do this:
<job>
<localUserId>stu</localUserId>
<executable>/bin/date</executable>
<stdout>${GLOBUS_USER_HOME}/stdout</stdout>
<stderr>${GLOBUS_USER_HOME}/stderr</stderr>
</job>To allow for customization of values, such as paths, on a per-job basis; a job description substitution variable named "GLOBUS_JOB_ID" can be used.
For example:
<job>
<executable>/bin/date</executable>
<stdout>/tmp/stdout.${GLOBUS_JOB_ID}</stdout>
<stderr>/tmp/stderr.${GLOBUS_JOB_ID}</stderr>
<fileStageOut>
<transfer>
<sourceUrl>file:///tmp/stdout.${GLOBUS_JOB_ID}</sourceUrl>
<destinationUrl>gsiftp://mymachine.mydomain.com/out.${GLOBUS_JOB_ID}</destinationUrl>
</transfer>
</fileStageOut>
</job>More information about substitution variables can found here.
Basic support is provided for specifying custom extensions to the job description. There are plans to improve the usability of this feature, but at this time it involves a bit of work.
Specifying the actual custom elements in the job description is trivial. Simply add any elements that you need between the beginning and ending
extensions tags at the bottom of the job
description as in the following basic example:
<job>
<executable>/home/user1/myapp</executable>
<extensions>
<myData>
<flag1>on</flag1>
<flag2>off</flag2>
</myData>
</extensions>
</job>
To handle this data, you will have to alter the appropriate Perl scheduler
script (i.e. $GLOBUS_LOCATION/lib/perl/Globus/GRAM/JobManager/fork.pm for the
Fork scheduler, etc...) to parse the data returned from the
$description->extensions() sub.
For more information about extensions see the Extensions section.
The job description XML schema allows for specification of a multijob i.e. a job that is itself composed of several executable jobs, which we will refer to as subjobs (note: subjobs cannot be multijobs, so the structure is not recursive). This is useful for instance in order to bundle a group of jobs together and submit them as a whole to a remote GRAM installation.
Note that no relationship can be specified between the subjobs of a multijob. The subjobs are submitted to job factory services in their order of appearance in the multijob description.
Within a multijob description, each subjob description must come along with an endpoint for the factory to submit the subjob to. This enables the at-once submission of several jobs to different hosts. The factory to which the multijob is submitted acts as an intermediary tier between the client and the eventual executable job factories.
Here is an example of a multijob description:
<?xml version="1.0" encoding="UTF-8"?>
<multiJob xmlns:wsa="http://www.w3.org/2005/08/addressing">
<factoryEndpoint>
<wsa:Address>
https://localhost:8443/wsrf/services/ManagedJobFactoryService
</wsa:Address>
</factoryEndpoint>
<directory>${GLOBUS_LOCATION}</directory>
<count>1</count>
<job>
<factoryEndpoint>
<wsa:Address>https://localhost:8443/wsrf/services/ManagedJobFactoryService</wsa:Address>
</factoryEndpoint>
<executable>/bin/date</executable>
<stdout>${GLOBUS_USER_HOME}/stdout.p1</stdout>
<stderr>${GLOBUS_USER_HOME}/stderr.p1</stderr>
<count>2</count>
</job>
<job>
<factoryEndpoint>
<wsa:Address>https://localhost:8443/wsrf/services/ManagedJobFactoryService</wsa:Address>
</factoryEndpoint>
<executable>/bin/echo</executable>
<argument>Hello World!</argument>
<stdout>${GLOBUS_USER_HOME}/stdout.p2</stdout>
<stderr>${GLOBUS_USER_HOME}/stderr.p2</stderr>
<count>1</count>
</job>
</multiJob>Submit the multi-job with the following command:
% bin/globusrun-ws -submit -f test_multi.xml
Delegating user credentials...Done.
Submitting job...Done.
Job ID: uuid:bd9cd634-4fc0-11d9-9ee1-000874404099
Termination time: 12/18/2004 00:15 GMT
Current job state: Active
Current job state: CleanUp
Current job state: Done
Destroying job...Done.
Cleaning up any delegated credentials...Done. | Note |
|---|---|
When you submit a multi-job you don't have to specify the local resource manager, you can do so though. The fact that it's a multi-job is detected on the server-side and the right "local resource manager" Multi is used automatically. |
| Note |
|---|---|
In this multi-job description the sub-jobs are submitted to the default local resource manager. If you want them to be submitted to a non-default local resource manager you'll have to specify that in an additional ReferenceParameters element in the factoryEndpoint element of each sub-job. See here for more information about this. |
A multijob resource is created by the factory and exposes a set of WSRF resource properties different than the resource properties of an executable job. The state machine of a multijob is also different since the multijob represents the overall execution of all the executable jobs it is composed of.
Check GT 4.2.0 GridWay: User's Guide if you are looking for information on metascheduling functionality.
This page contains links to each GT 4.2.0 component's Public Interfaces Guide.
Common Runtime Components
Security
Data Management
Information Services
Execution Management
- Java WS Core container
- C WS Core container
- XIO
- GSI credentials
- GSI gridmap
- Java WS Authentication & Authorization (Java WS A&A)
- GridShib
- MyProxy
- GSI-OpenSSH
- GridFTP
- Reliable File Transfer (RFT)
- Replica Location Service (RLS)
- WS Replica Location Service (WS RLS)
- Data Replication Service (DRS)
- WS MDS Index Service
- WS MDS Trigger Service
- WS MDS Aggregator Framework
- WS MDS WebMDS
- GRAM4
- GRAM2 (legacy)
- GridWay
Table B.1. Java WS Core Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
Failed to acquire notification consumer home instance from registry | Caused by javax.naming.NameNotFoundException: Name services is not bound in this Context error. | Please see Running client programs from any directory if a client fails with this error. |
The WS-Addressing 'To' request header is missing | This warning is logged by the container if the request did not contain the necessary WS-Addressing headers. The client either did not attempt to send those headers at all or is somehow misconfigured. | If you are using a
Java client and launching it directly using the java executable,
take a look at Appendix B, Running client programs from any directory.
|
java.io.IOException: Token length X > 33554432 | If you see this error in the container log, it usually means you are trying to
connect to HTTPS server using HTTP. For example, the service address specifies
8443 as a port number and
http as the protocol name. | In general, use
8443 port number with the
https protocol, and 8080 port
number with the http protocol. |
java.lang.NoSuchFieldError: DOCUMENT | This error usually indicates a mismatch between the version of Apache Axis that the code was compiled with and the version of Axis that the code is currently running with. | Make sure that the same version of Axis is used at compile time and at runtime. |
org.globus.wsrf. InvalidResourceKeyException: Argument key is null / Resource key
is missing | These errors usually indicate that a resource key was not passed with the request or that an invalid resource key was passed with the request (that is, the element QName of the resource key did not match what the service expected). | Make sure that the EPR used to invoke the service that contains the appropriate resource key. If
you are using some command-line tool make sure
to specify the resource key using the -k option or pass a
complete EPR from a file using the -e option. |
Unable to connect to localhost:xxx | Cannot resolve localhost. The machine's /etc/hosts isn't set up correctly and/or you do not have DNS for these machines. |
There should always be an entry in /etc/hosts (or /etc/hostname/ on Debian)
for localhost in the following format (IP address/fully qualified domain name/short name):
140.221.8.109 cognito.mcs.anl.gov cognito |
org.globus.common.ChainedIOException: Failed to initialize security context | This may indicate that the user's proxy is invalid. | To correct the error, the user must properly initialize the user proxy. See grid-proxy-init for more information on proxy initialization. |
Error: org.xml.sax.SAXException: Unregistered type: class xxx | This may indicate that an Axis generated XML type, defined by the WS RLS XSD, was not properly registered. While all the XML types should get registered upon deployment without intervention by the user, sometimes they do not. | To remedy the situation add a typeMapping to the server-config.wsdd file under globus_wsrf_replicalocation_service.
Use the format shown here. |
No socket factory for 'https' protocol | When a client fails with the following exception: java.io.IOException: No socket factory for 'https' protocol at
org.apache.axis.transport.http.HTTPSender.getSocket(HTTPSender.java:179) at
org.apache.axis.transport.http.HTTPSender.writeToSocket(HTTPSender.java:397) at
org.apache.axis.transport.http.HTTPSender.invoke(HTTPSender.java:135)FIXME - it may have happened because... | Add the following to the client: import org.globus.axis.util.Util; ... static { Util.registerTransport(); }
... |
No client transport named 'https' found | When a client fails with the following exception: No client transport named 'https' found at
org.apache.axis.client.AxisClient.invoke(AxisClient.java:170) at
org.apache.axis.client.Call.invokeEngine(Call.java:2726)
The client is most likely loading an incorrect | Ensure that the GT4 installation
directory is listed as the first entry in the CLASSPATH=/usr/local/globus-4.2.0:/foo/bar/others.jar:... If you are seeing this problem in Tomcat, copy the |
ConcurrentModificationException in Tomcat 5.0.x | If the following exception is visible in the Tomcat logs at
startup, it might cause the java.util.ConcurrentModificationException at
java.util.HashMap$HashIterator.nextEntry(HashMap.java:782) at
java.util.HashMap$EntryIterator.next(HashMap.java:824) at
java.util.HashMap.putAllForCreate(HashMap.java:424) at
java.util.HashMap.clone(HashMap.java:656) at
mx4j.server.DefaultMBeanRepository.clone(DefaultMBeanRepository.java:56)
The java.lang.NullPointerException at
org.apache.coyote.tomcat5.CoyoteRequest.setAttribute(CoyoteRequest.java:1472) at
org.apache.coyote.tomcat5.CoyoteRequestFacade.setAttribute(CoyoteRequestFacade.java:351) at
org.globus.tomcat.coyote.valves.HTTPSValve.expose(HTTPSValve.java:99)
These exceptions will prevent the transport security from working properly in Tomcat. | This is a Tomcat bug. Keep restarting Tomcat until it starts
without the
|
java.net.SocketException: Invalid argument or
cannot assign requested address | FIXME - what causes this? | If you see the $ export GLOBUS_OPTIONS="-Djava.net.preferIPv4Stack=true" |
GAR deploy/undeploy fails with container is running error | A GAR file can only be deployed or undeployed locally while the container is off. However, GAR deployment/undeployment might still sometimes fail with this error even if the container is off. This usually happens if the container has crashed or was stopped improperly, preventing the container from cleaning up its state files. | To resolve
this problem, delete any files under the
|
Table B.2. C WS Core Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
globus_soap_message_module: Failed sending request
http://widgets.com/WidgetPortType/createWidgetRequest.
globus_xio: Unable to connect to grid.example.org:8080
globus_xio: System error in connect: Connection refused
globus_xio: A system call failed: Connection refused
| Unable to contact service container | Check that the service endpoint refers to a running container. |
globus_soap_message_module: Failed sending request
http://widgets.com/WidgetPortType/createWidgetRequest.
globus_xio_gsi: gss_init_sec_context failed.
GSS Major Status: Unexpected Gatekeeper or Service Name
globus_gsi_gssapi: Authorization denied: The name of the remote entity
(/C=US/O=Globus Alliance/OU=Service/CN=host/grid.example.org), and the
expected name for the remote entity
(/C=US/O=Globus Alliance/OU=Service/CN=host/cloud.example.org) do not
match
| Service is not running with the expected security credential. | Verify that the service credential being presented by the service (first parenthesized name) is a reasonable certificate name for the service. If so, set the GLOBUS_SOAP_MESSAGE_PEER_IDENTITY_KEY attribute on the soap message handle to that identity. For most command-line wsrf tools, this can be done by passing it as an argument to the -z command-line parameter. |
globus_soap_message_module: SOAP Fault
Fault code: Client
Fault string: globus_service_engine_module: Failed to find operation:
{XXXX}YYYY for service: {ZZZZ}BBBB
| The service port type {ZZZZ}BBBB does not contain a {XXXX}YYYY operation. | Verify that the client bindings are built from the same WSDL and XML Schema documents as the service. |
globus_soap_message_module: Failed receiving response
http://widgets.com/WidgetPortType/createWidgetResponse.
ws_addressing: Addressing header is a draft version of WS Addressing:
"http://schemas.xmlsoap.org/ws/2004/03/addressing". This could be a GT version
mismatch, client is GT 4.2.x and response is from GT 4.0.x
server
| The service is running on a container which is using a draft version of the WS-Addressing specification. This was used by GT 4.0.x | Update the service to work with GT 4.2.x or compile your client with GT 4.0.x libraries. |
globus_soap_message_module: Failed sending request
http://widgets.com/WidgetPortType/createWidgetRequest.
globus_xio: The GSI XIO driver failed to establish a secure connection. The
failure occured during a handshake read.
globus_xio: An end of file occurred
| The service container either did not support SSL authentication, or the service container did not trust the client certificate | Consult the service administrator to verify that the service container supports SSL and that your certificate is issued by a certificate authority trusted by the service. |
Table B.3. XIO Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
Operation was canceled | An I/O operation has been canceled by a close or a cancel | In most cases this will be intentionally performed by the application developer. In unexpected cases the applciation developer should verify that there is not a race condition relating to closing a handle. |
Operation timed out | Occurs when the application developer associates a timeout with a handle's I/O operations. If no I/O is performed before the timeout expires this error will be triggered. | The remote side of connection might be hung and busy. The network could have higher latencies than expected. The filesystem might be over worked. |
An end of file occurred | This occurs when and EOF is detected on the file descriptor | When doing file I/O this like means you read to the end of the file and thus you are finished and should now close it. On network connections however it means the socket was closed on the remote end. This can happen it the remote side suddenly dies (seg-fault is common here) or if the remote side chooses to close the connection. |
Contact string invalid | A poorly formed contact string was passed in to open | Verify the format of the contact string with the documentation of the drivers in use. |
Memory allocation failed on XXXX | malloc failed. The system is likely quite overloaded | Free up memory in your application |
System error in XXXX | A low level system error occurred. The errno and errstring should indicate more information. | |
Invalid stack | The requested stack does not meet XIO standards | Most likely a transport driver is not on the bottom of the stack, or 2 transport drivers are in the stack. |
Operation already registered | With certain common drivers like TCP and FILE, only one specific operations can be registered at a time (1 read, 1 write). If another operation of the same type is posted to the handle before receiving the previous operations callback, this error can occur. | Restructure the application code so that it waits for the callback before registering the next IO operation. |
Unexpected state | The internal logic of XIO came across a logical path that should not be possible. Often times this is due to application memory corruption or trying to perform an IO operation on a closed or otherwise invalid handle. | Use valgrind or some sort of memory managment tool to verify there is no memory corruption. Try to recreate the problem in a small program. Submit the program and the memory trace at bugzilla.globus.org |
Driver in handle has been unloaded | A driver associated with the offending operation has already been unloaded by the application code. | Verify that you are not unloading drivers until they are no longer in use. |
Module not activated | globus_module_activate(GLOBUS_XIO_MODULE); has not been called. | Call this before making any other XIO API calls. |
Table B.4. Credential Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
Your proxy credential may have expired | Your proxy credential may have expired. | Use grid-proxy-info to check whether the proxy credential has actually expired. If it has, generate a new proxy with grid-proxy-init. |
The system clock on either the local or remote system
is wrong. | This may cause the server or client to conclude that a credential has expired. | Check the system clocks on the local and remote system. |
Your end-user certificate may have
expired | Your end-user certificate may have expired | Use grid-cert-info to check your certificate's expiration date. If it has expired, follow your CA's procedures to get a new one. |
The permissions may be wrong on your proxy
file | If the permissions on your proxy file are too lax (for example, if others can read your proxy file), Globus Toolkit clients will not use that file to authenticate. | You can "fix" this problem by changing the permissions on
the file or by destroying it (with grid-proxy-destroy) and
creating a new one (with grid-proxy-init).
Important: However, it is still possible that someone else has made a copy of that file during the time that the permissions were wrong. In that case, they will be able to impersonate you until the proxy file expires or your permissions or end-user certificate are revoked, whichever happens first. |
The permissions may be wrong on your private key
file | If the permissions on your end user certificate private key file are too lax (for example, if others can read the file), grid-proxy-init will refuse to create a proxy certificate. | You can "fix" this by changing the permissions on the
private key file. Important: However, you will still have a much more serious problem: it is possible that someone has made a copy of your private key file. Although this file is encrypted, it is possible that someone will be able to decrypt the private key, at which point they will be able to impersonate you as long as your end user certificate is valid. You should contact your CA to have your end-user certificate revoked and get a new one. |
The remote system may not trust your
CA | The remote system may not trust your CA | Verify that the remote system is configured to trust the CA that issued your end-entity certificate. See Installing GT 4.2.0 for details. |
You may not trust the remote system's
CA | You may not trust the remote system's CA | Verify that your system is configured to trust the remote CA (or that your environment is set up to trust the remote CA). See Installing GT 4.2.0 for details. |
There may be something wrong with the remote
service's credentials | There may be something wrong with the remote service's credentials | It is sometimes difficult to distinguish between errors reported by the remote service regarding your credentials and errors reported by the client interface regarding the remote service's credentials. If you cannot find anything wrong with your credentials, check for the same conditions on the remote system (or ask a remote administrator to do so) . |
Table B.5. Gridmap Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
The content of the grid map file does not conform to the expected format | The content of the grid map file does not conform to the expected format | Run grid-mapfile-check-consistency to make sure that your gridmap file conforms to the expected format. |
The grid map file does not contain a entry for your DN | The grid map file does not contain a entry for your DN | Use grid-mapfile-add-entry to add the relevant entry. |
Table B.6. Java WS A&A Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
[JWSSEC-248] Secure container requires valid
credentials | This error occurs when globus-start-container is run without any valid credentials. Either a proxy certificate or service/host certificate needs to be configured for the container to start up. |
|
Failed to start container: Container failed to
initialize [Caused by: [JWSSEC-250] Failed to load certificate/key
file] | This error occurs if the file path to the container certificate and key configured are invalid. |
|
Failed to start container: Container failed to
initialize [Caused by: [JWSSEC-249] Failed to load proxy
file] | This error occurs if container proxy file configured is invalid. |
|
Failed to start container: Container failed to
initialize [Caused by: [JWSSEC-245] Error parsing file:
"etc/globus_wsrf_core/ global_security_descriptor.xml" [Caused by:
...] | This error occurs if the container security descriptor configured is invalid. |
|
[JGLOBUS-77] Unknown CA | This error occurs if the CA certificate for the credentials being used is not installed correctly. |
|
Table B.7. GridShib Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
error1 | description1 | solutions or links to solutions |
Table B.8. MyProxy Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
MyProxy server name does not match expected name | This error appears as a mutual authentication failure or a server authentication failure, and the error message should list two names: the expected name of the MyProxy server and the actual authenticated name. By default, the MyProxy clients expect the MyProxy server to be running with a host certificate that matches the target hostname. This error can occur when running the MyProxy server under a non-host certificate or if the server is running on a machine with multiple hostnames. The MyProxy clients authenticate the identity of the MyProxy server to avoid sending passphrases and credentials to rogue servers.If the expected name contains an IP address, your system is unable to do a reverse lookup on that address to get the canonical hostname of the server, indicating either a problem with that machine's DNS record or a problem with the resolver on your system. |
If the server name shown in the error message is acceptable, set the MYPROXY_SERVER_DN environment variable to that name to resolve the problem.
|
Error in bind(): Address already in use | This error indicates that the myproxy-server port (default: 7512) is in use by another process, probably another myproxy-server instance. You cannot run multiple instances of the myproxy-server on the same network port. |
If you want to run multiple instances of the myproxy-server on a machine, you can specify different ports with the -p option,
and then give the same -p option to the MyProxy commands to tell them to use the myproxy-server on that port.
|
grid-proxy-init failed | This error indicates that the grid-proxy-init command failed when myproxy-init attempted to run it, which implies a problem with the underlying Globus installation. |
Run grid-proxy-init -debug -verifyfor more information. |
User not authorized | An error from the myproxy-server saying you are "not authorized" to complete an operation typically indicates that the
myproxy-server.config file settings are restricting your access to the myproxy-server. It is possible that the
myproxy-server is running with the default myproxy-server.config file, which does not authorize any operations. | See Configuring for more information. |
Table B.9. GSI-OpenSSH Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
GSS-API error Failure acquiring GSSAPI credentials: GSS_S_CREDENTIALS_EXPIRED | This means that your proxy certificate has expired. |
Run grid-proxy-init to acquire a new proxy certificate, then run gsissh again.
|
...no proxy credentials... | Failing to run grid-proxy-init to create a user proxy with which to connect will result in the client notifying you that no local credentials exist. Any attempt to authenticate using GSI will fail in this case. | Verify that your GSI proxy has been properly initialized via grid-proxy-info. If you need to initialize the proxy, use the command grid-proxy-init. |
...bad file system permissions on private key; key must only be readable by the user... | The host key that the SSH server is using for GSI authentication must only be readable by the user which owns it. Any other permissions will cause this error. | Make sure that the host key's UNIX permissions are mode 400 (that is, it should only have mode readable for the user that owns the file, and no other mode bits should be set). |
...gssapi received empty username; failed to set username from gssapi context; Failed external-keyx for <user> from <host> <port>... | If the server was passed an "implicit username" (i.e. requested to map the incoming connection to a username based on some contextual clues such as the certificate's subject), and no entry exists in the grid-mapfile for the incoming connection's certificate subject, the server should output a clue that states it is unable to set the username against which to authenticate. | Add an entry for the user to the [grid-mapfile fixme link]. |
...INTERNAL ERROR: authenticated invalid user xxx... | If the subject name given in the system's grid-mapfile points to a non-existent user, the server will give an internal error which is best caught when it is running in debugging mode. | Add a new account to the system matching the username pointed at by the user's subject in the grid-mapfile. |
...gssapi received empty username; no suitable client data; failed to set username from gssapi context; Failed external-keyx for <user> from <host> <port>... | Should the user attempt to connect without first creating a proxy certificate, or if the user is connecting via a SSH client that does not support GSI authentication, the server will note that no GSSAPI data was sent to it. Verify that the client is able to connect through another GSI service (such as the gatekeeper) to make sure that the user's proxy has been created correctly. | Verify that you are using a GSI-enabled SSH client and that your GSI proxy has been properly initialized via grid-proxy-info. If you need to initialize this proxy, use the command grid-proxy-init. |
Table B.10. GridFTP Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
globus_ftp_client: the server responded with an error
530 530-globus_xio: Authentication Error
530-OpenSSL Error: s3_srvr.c:2525: in library: SSL routines,
function SSL3_GET_CLIENT_CERTIFICATE: no certificate returned
530-globus_gsi_callback_module: Could not verify credential
530-globus_gsi_callback_module: Can't get the local trusted CA certificate:
Untrusted self-signed certificate in chain with hash d1b603c3
530 End.
| This error message indicates that the GridFTP server doesn't trust the certificate authority (CA) that issued your certificate. | You need to ask the GridFTP server administrator to install your CA certificate chain in the GridFTP server's trusted certificates directory. |
globus_ftp_control: gss_init_sec_context failed
OpenSSL Error: s3_clnt.c:951: in library: SSL routines, function
SSL3_GET_SERVER_CERTIFICATE: certificate verify failed
globus_gsi_callback_module: Could not verify credential
globus_gsi_callback_module: Can't get the local trusted CA certificate:
Untrusted self-signed certificate in chain with hash d1b603c3
| This error message indicates that your local system doesn't trust the certificate authority (CA) that issued the certificate on the resource you are connecting to. | You need to ask the resource administrator which CA issued their certificate and install the CA certificate in the local trusted certificates directory. |
Table B.11. Reliable File Transfer (RFT) Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
Error creating RFT Home: Failed to connect to database ...
Until this is corrected all RFT request will fail and all GRAM jobs that require staging will fail | This occurs when you start the container if RFT is not configured properly to talk to a PostgreSQL database. | The usual cause is that Postmaster is not accepting TCP connections, which means that you must restart Postmaster with the -i option (see Configuring RFT). |
ERROR service.RFTResourceManager [Thread-13,transferCompleted:517]
Unable to update on finished
org.globus.transfer.reliable.service.database.RftDBException:
RFT database update error
[Caused by: Syntax error: Encountered ")" at line 1, column 47.]
| This error occurs as a result of a dynamically built SQL update string. The update occurs when a transfer completes. It is used to notify transfer requests using the same hosts that resources on that host have been freed. The error message occurs when no rows in the database match that host. | Users of RFT may safely ignore this error. The message is harmless to the functionality of RFT and will not affect the results of a transfer in any way. The exception is safely caught. Future versions of RFT will have optimizations to avoid this step. |
Table B.12. Replica Locator Service (RLS) Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
Error with credential: The proxy credential: <credential> with subject: <subject> expired <minutes> minutes ago
| Expired proxy credential | Create a new proxy with grid-proxy-init. |
Unable to connect to localhost:xxxx
| Unable to connect to the local host. This can be due to a variety of reasons, including a wrong address or port number in the RLS connection URL or an issue with a firewall configuration. |
|
| "connection timeout" | At times, a client may experience a connection timeout when interacting with the RLS server due to a variety of reasons:
|
If timeouts are experienced with increasing frequency, increase the RLS server's timeout configuration parameter found in the
$GLOBUS_LOCATION/var/globus-rls-server.conf file. You may also use the -t timeout option of the
globus-rls-cli tool.
|
Table B.13. WS Replica Location Service (WS RLS) Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
Error: java.lang.NullPointerException | When invoking the WS RLS command-line clients, a system-level exception like the one above may be encountered. | The admin should check the container logs for the exact error. |
Error: A server error occured while processing the request | When invoking the WS RLS command-line clients, a server error like the one above may be encountered. | The admin should check the container logs for the exact error. |
java.lang.UnsatisfiedLinkError | This exception when using the WS RLS may indicate that the native RLS libraries that WS RLS depends on could not be located. |
To correct this problem, ensure that the $GLOBUS_LOCATION/lib directory is in the library search path (on some systems this is the LD_LIBRARY_PATH variable).
|
Unable to connect to localhost:39281 | The WS RLS is an interface layer that depends on the RLS for the replica location functionality. You must install and run RLS and configure WS RLS to use the RLS via its JNDI configuration. | Check that RLS is installed, running, and check that the WS RLS JNDI configuration uses the correct hostname and port to connect to the RLS. |
org.globus.common.ChainedIOException: Failed to initialize security context | If this exception occurs while using WS RLS, it may indicate that the user's proxy is invalid. | To correct the error, the user must properly initialize the user proxy. See grid-proxy-init for more information on proxy initialization. |
Error: org.xml.sax.SAXException: Unregistered type: class xxx | If this exception occurs when using the WS RLS, it may indicate that an Axis generated XML type, defined by the WS RLS XSD, was not properly registered. While all the XML types should get registered upon deployment without intervention by the user, sometimes they do not. |
To remedy the situation add a typeMapping to the server-config.wsdd file under globus_wsrf_replicalocation_service.
Use the format shown here.
|
Table B.14. Data Replication Service (DRS) Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
Authorization failed. Expected <hostname1> target but received <hostname2> | Did not receive expected hostname | When authorization is enabled on the container, you may need to use the proper hostname when referencing the DRS service rather than using localhost. |
org.globus.wsrf.ResourceException: Failed to create Replication: /scratch/testrun (No such file or directory) | Cannot find the request file | Ensure that the request file's filename is correct, that it is reachable by the DRS service, and that it has the appropriate permissions for the DRS service to access it. |
org.globus.wsrf.ResourceException: Failed to create Replication: String
index out of range: -1 | The request file is malformed (for example by using spaces instead of a delimiting tab character) which is resulting in a runtime exception. | Make sure your request file is in the correct form as described here. |
Table B.15. WS MDS Index Service Error Messages
| Error Code | Definition | Possible Solutions |
|---|---|---|
error | what causes this | possible solutions |
| WS MDS is built on Java WS Core, please see Java WS Core Error Codes for more error code documentation. | ||
Table B.16. WS MDS Trigger Service Error Messages
| Error Code | Definition | Possible Solutions |
|---|---|---|
Error ; nested exception is: org.apache.commons.httpclient. NoHttpResponseException: The server xxx.x.x.x failed to respond | Happens when trying to create a trigger for the Trigger Service. The above error is accompanied by the following error in container:
[JWSCORE-192] Error processing request java.io.IOException: Token length 1347375956 > 33554432. FIXME - what causes this?
|
Be sure that you have properly edited the client-config-settings file under globus_wsrf_mds_trigger.
The DefaultServiceAddress parameter should properly reflect the service prefix from your container,
e.g.: https://127.0.0.1:8444/wsrf/services/. The services you wish to monitor should also be consistent.
|
| WS MDS is built on Java WS Core, please see Java WS Core Error Codes for more error code documentation. | ||
Table B.17. WS MDS Aggregator Error Messages
| Error Code | Definition | Possible Solutions |
|---|---|---|
error | what causes this | possible solutions |
| WS MDS is built on Java WS Core, please see Java WS Core Error Codes for more error code documentation. | ||
Table B.18. WS MDS Trigger Service Error Messages
| Error Code | Definition | Possible Solutions | |||
|---|---|---|---|---|---|
java.net.ConnectException: Connection refused |
If you attempt to use WebMDS to collect information from a service that is not running, you will see a stack trace that begins with:
org.globus.mds.webmds.xmlSources.resourceProperties.ResourcePropertySourceException: ; nested exception is: java.net.ConnectException: Connection refused | Make sure the service you are trying to collect information from is running. | |||
faultString: org.globus.common.ChainedIOException: Authentication failed
[Caused by: Failure unspecified at GSS-API level [Caused by: Unknown CA]] | When WebMDS sends resource property queries to a secure WSRF service instance (such as an WS MDS Index Server), the WebMDS server must trust the certificate authority that issued the certificate used by the WSRF service instance. If the WebMDS server does not trust the CA used by the remote service, then WebMDS queries will produce a stack trace that includes this message. |
This can be solved by configuring the Tomcat server that hosts WebMDS to trust the appropriate CA, by either:
| |||
| WebMDS connections to secure Index Servers (or other secure WSRF servers) just hang | If the JVM used by Tomcat is configured to use a blocking random-number source, WebMDS connections to secure Index Servers (or other secure WSRF servers) can hang. This is the default configuration for many installations. |
One solution is to set the CATALINA_OPTS environment variable to ensure that Tomcat's JVM will use a non-blocking
random-number source:
export CATALINA_OPTS=-Djava.security.egd=/dev/urandom $CATALINA_HOME/bin/shutdown.sh $CATALINA_HOME/bin/startup.sh
|
Table B.19. GRAM4 Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
globusrun-ws - error querying job state | During job submission, an error like this occurs:
globusrun-ws failed: Delegating user credentials...Done.
Submitting job...Done.
Job ID: xxxx
Termination time: xxxx
Current job state: Unsubmitted
globusrun-ws: Error querying job state
globus_soap_message_module: Failed sending request
ManagedJobPortType_GetMultipleResourceProperties.
globus_xio: An end of file occurred
| Periodically, globusrun-ws will query the GRAM service to check on the job state. The "End of file" indicates that the GRAM server dropped a connection when globusrun-ws tried to read a response. This could be caused by temporary network issues between the client and service, or possibly caused by an overloaded service host. |
globusrun-ws - error querying job state | During job submission, an error like this occurs:
globusrun-ws failed: Delegating user credentials...Done.
Submitting job...Done.
Job ID: xxxx
Termination time: xxxx
Current job state: Unsubmitted
globusrun-ws: Error querying job state
globus_soap_message_module: Failed sending request ManagedJobPortType_GetMultipleResourceProperties.
globus_xio: System error in read: Connection reset by peer
globus_xio: A system call failed: Connection reset by peer
|
Periodically, globusrun-ws will query the GRAM service to check on the job state. The System error in read: Connection reset by peerindicates that the GRAM server dropped the connection while trying to write the response. This could be caused by temporary network issues between the client and service, or possibly caused by an overloaded service host. |
globusrun-ws - error submitting job | During job submission, an error like this occurs:
globusrun-ws -Ft PBS -F https://host.teragrid.org:8444 -submit -b -f /tmp/wsgram.rsl -o /tmp/wsgram.epr failed: Submitting job...Failed.
globusrun-ws: Error submitting job
globus_soap_message_module: Failed sending request ManagedJobFactoryPortType_createManagedJob.
globus_xio: Operation was canceled
globus_xio: Operation timed out
|
The Operation timed outindicates that the GRAM service was not able to accept the job request and respond in time. This could be caused by temporary network issues between the client and service, or possibly caused by an overloaded service host. |
Table B.20. GRAM2 Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
error1 | description1 | solutions or links to solutions |
Table B.21. Gridway Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
Lock file exists | Another GWD may be running. | Be sure that no other GWD is running, then remove the lock file and try again. |
Error in MAD initialization | There may be problems with the proxy certificate, bin directory, or the executable name of a MAD may not be in the correct location. |
Check that you have generated a valid proxy (for example with the grid-proxy-info command). Also, check that the directory $GW_LOCATION/bin is in your path, and the executable name of all the
MADs is defined in gwd.conf.
|
Could not connect to gwd | GridWay may not be running or there may be something wrong with the connection. |
Be sure that GWD is running; for example:pgrep -l gwdIf it is running, check that you can connect to GWD; for example: telnet `cat $GW_LOCATION/var/gwd.port` |
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
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 22. 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 23. 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 24. 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. |
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. |
Name
wsrf-destroy — Destroys a resource
Synopsis
wsrf-destroy
Command syntax
wsrf-destroy [options]
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:
$ wsrf-destroy -s http://localhost:8080/wsrf/services/CounterService \ -k
"{http://counter.com}CounterKey" 123Name
wsrf-set-termination-time — Sets termination time of a resource
Synopsis
wsrf-set-termination-time
Command syntax
wsrf-set-termination-time [options] <seconds> | 'infinity'
The following are command-specific options in addition to the common options:
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. |
Example:
$ wsrf-set-termination-time -s http://localhost:8080/wsrf/services/CounterService \ -k
"{http://counter.com}CounterKey" 123 30Name
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 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. |
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
Command syntax
wsrf-get-property [options] <property>
The <property> is a QName of the resource property in the string form: {namespaceURI}localPart.
Table 31. 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
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 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:
$ 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
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 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: 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.xmlName
wsrf-update-property — Updates value of a resource property
Synopsis
wsrf-update-property
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 34. 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.xmlName
wsrf-delete-property — Deletes a resource property
Synopsis
wsrf-delete-property
Command syntax
wsrf-delete-property [options] <property>
The <property> is a QName of the resource property in the string form: {namespaceURI}localPart.
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. |
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
Command syntax
wsn-get-current-message [options] <topic>
The <topic> is a QName of the resource property in the string form: {namespaceURI}localPart.
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. |
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 37. 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 38. 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
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 39. 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 40. 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
Command syntax
globus-deploy-gar [options] <gar.file>
The <gar.file> is the path to the GAR file to be deployed.
Table 41. 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
|
| -D<property>=<value> |
Passes arbitrary property-value pairs. See below for the list of currently supported properties. |
Table 42. 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 |
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.garThe 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
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 43. 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
|
| -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_counterExample 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
Name
globus-check-remote-environment — Displays remote component version information.
Synopsis
globus-check-remote-environment
Command syntax
globus-check-environment [-help] -s endpoint -z authz
Table 44. 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.
Name
globus-validate-descriptors — Validate configuration files of all services
Synopsis
globus-validate-descriptors
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 47. 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 48. 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 49. 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 50. 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 51. 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.contextThe 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 52. 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 53. 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.contextThis 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 54. 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.contextName
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 55. Command-specific options
| -n, --nsMapFile <file> |
Specifies a file that contains namespace mappings. By default, the
|
| -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 56. 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:EntryThe 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.contextThe 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 57. 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 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
Examples
Start a container in the foreground on port 8443:
%globus-wsc-container-port 8443Contact: 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.contactContact: https://grid.example.org:18332/%cat$GLOBUS_LOCATION/var/globus-wsc-container.logts=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 58. 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.wsdlCreating 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 cppis 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
Command syntax
globus-wsrf-destroy [OPTIONS]... SERVICE-SPECIFIER
Table 59. 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.eprResource 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>
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
Command syntax
globus-wsrf-set-termination-time [OPTIONS]... SERVICE-SPECIFIER TERMINATION-TIME
Table 60. 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
Command syntax
globus-wsrf-query [OPTIONS]... SERVICE-SPECIFIER QUERY-EXPRESSION
Table 61. 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 62. 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>Name
globus-wsrf-get-property — Get a resource property's value
Synopsis
globus-wsrf-get-property [OPTIONS]... SERVICE-SPECIFIER PROPERTY-NAME
Command syntax
globus-wsrf-get-property [OPTIONS]... SERVICE-SPECIFIER PROPERTY-NAME
Table 63. 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>
Name
globus-wsrf-get-properties — Get multiple resource property value
Synopsis
globus-wsrf-get-properties [OPTIONS]... SERVICE-SPECIFIER PROPERTY-NAME...
Command syntax
globus-wsrf-get-properties [OPTIONS]... SERVICE-SPECIFIER PROPERTY-NAME...
Table 64. 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>
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 65. 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>
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 66. 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.xmlContents 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>
Name
globus-wsrf-delete-property — Delete a resource property
Synopsis
globus-wsrf-delete-property [OPTIONS] SERVICE-SPECIFIER PROPERTY-NAME
Command syntax
globus-wsrf-delete-property [OPTIONS]... SERVICE-SPECIFIER PROPERTY-NAMETable 67. 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"
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
Command syntax
globus-wsn-get-current-message [OPTIONS]... SERVICE-SPECIFIER TOPIC-EXPRESSIONTable 68. 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 69. 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
Command syntax
globus-wsn-pause-subscription [OPTIONS]... SERVICE-SPECIFIER TOPIC-EXPRESSIONTable 70. 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.eprContents 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
Command syntax
globus-wsn-resume-subscription [OPTIONS]... SERVICE-SPECIFIER TOPIC-EXPRESSIONTable 71. 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.eprContents 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
Command syntax
globus-wsn-subscribe [OPTIONS]... SERVICE-SPECIFIER TOPIC-EXPRESSIONTable 72. 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 73. 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-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.
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-diagnosticsChecking 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-pChecking 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
| 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. |
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 | 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 | 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 | 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 | 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 |
-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 | 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-requestA 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
%grid-cert-request-host grid.example.org-dir $HOME/.globus/hostA 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
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-listThe 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-caThe 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.0Enter the index number of the CA to set as the default [q to quit]:1setting 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.
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
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.
Options
Table 75. 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
Name
grid-proxy-destroy — Destroy the current proxy certificate (previously created with grid-proxy-init)
Synopsis
grid-proxy-destroy
Options
Table 76. 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. |
Name
grid-proxy-info — Display information obtained from a proxy certificate
Synopsis
grid-proxy-info
Options
Table 77. Command line options
| -help, -usage | Displays usage. |
| -version | Displays version. |
| -debug | Displays debugging output. |
| -file <proxyfile> (-f) | Non-standard location of proxy. |
| [printoptions] | |
| -exists [options] (-e) |
Determine whether a valid proxy exists. |
Table 78. 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. |
Name
grid-mapfile-add-entry — Add an entry to a grid map file
Synopsis
grid-mapfile-add-entry
Command syntax
grid-mapfile-add-entry -dn DN -ln LN [-help] [-d] [-f mapfile FILE]
Options:
Table 80. 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. |
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.
Name
grid-mapfile-delete-entry — Delete an entry from a grid map file
Synopsis
grid-mapfile-delete-entry
Options:
Table 82. 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. |
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]
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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:
trustAnchoruseruserGroupobjectobjectGroupobjectGroupnamespaceserviceTypeserviceActionserviceActionGp
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-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:
trustAnchoruseruserGroupobjectobjectGroupnamespaceserviceTypeserviceActionserviceActionGp
-
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-group-list-entries — Getting group members
Synopsis
cas-group-list-entries [ options] type name
Command Options
-
type Use one of the following to indicate the type of group for which you want a list of members:
userobjectserviceType
-
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-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
-ccas-url- The URL of the CAS service.
-
type Use one of the following to indicate the type of CasObjects:
trustAnchoruseruserGroupobjectobjectGroupnamespaceserviceTypeserviceActionserviceActionGp
-
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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
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.
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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.
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-poption.- -w
generatedCredFile Specify the file in which to store the CAS credential. Cannot be used with the
-toption.
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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.
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 actionFor 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 readTo 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:samlActionWildcardIf 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.eduwill look for a credential generated by a previous execution of:
casAdmin$ cas-proxy-init -t my-communityand then set the environment to use that credential while running the command:
casAdmin$ gsincftp myhost.eduThe 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.eduwill 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.eduOptions
Command-specific Options
- -p
proxyfile Specify the file in which to store the CAS credential. Cannot be used with the
-toption.- -t
tag Choose a filename in which to store the CAS credential based on the value
tag. Cannot be used with the-poption.
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-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] trustAnchoruserGpNamenicknameauthMethodauthData
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:
FTPDirectoryTreeuses the WildCardComparison Algorithm and has the base URL set to the current directory.FTPExactuses the ExactComparison Algorithm and has the base URL set to the current directory.
To enroll namespaces:
casAdmin$cas-enroll [common options] namespaceuserGpNamenicknamebasenamecomparisonAlg
where:
-
userGpName - Indicates the user group to which cas/grantAll permission should be granted on this trust anchor entity.
nicknameIndicates 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.
comparisonAlgIndicates 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. IfcomparisonAlgin the above method is set toExactComparison, 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 "/". IfcomparisonAlgin the above method is set toWildCardComparison, 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] objectuserGpNameobjectNamenamespaceNick
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] serviceTypeuserGpNameserviceTypeName
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-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] trustAnchornickname
where:
nicknameIndicates the nickname of the trust anchor 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.
Removing Namespaces
To remove a namespace, the user must have cas/remove permission on that namespace. The namespace must also be unused — that is, there may not be any object in the database that belongs to this namespace.
casAdmin$cas-remove [options] namespacenickname
where:
nicknameIndicates the nickname of the namespace to be unenrolled.
If the namespace nickname specified does not exist, an error is not thrown. If the remove operation is successful, all policy data on that trust anchor is purged.
Removing Objects
To remove an object the user must have cas/remove permission on that object. The object must also be unused — that is, there may not be any object group in the database that this object belongs to.
casAdmin$cas-remove [options] objectobjNamenamespaceNick
where:
objName- Indicates the name of the object to be removed.
namespaceNickIndicates the nickname of the namespace to which this object belongs.
If the object specified does not exist, an error is not thrown. If the remove operation is successful, all policy data on that object is purged.
Removing Service Types
To remove a service type the user must have cas/remove permission on that service type. The service type must also be unused — that is, there may not be any service type to action mapping.
casAdmin$cas-remove [options] serviceTypeserviceTypeName
where:
serviceTypeNameIndicates the service type name.
If the service type specified does not exist, an error is not thrown. If the remove operation is successful, all policy data on that service type is purged.
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-action — Maintains service types
Synopsis
cas-action [common options] [ add | remove ] serviceTypeName actionName
Tool description
Use the cas-action command to add an action mapping to a service type or remove an action mapping from a service type.
To add an action mapping to a service type, the user must have cas/create_group_entry permission on the service type.
To remove a service type action mapping, the user must have cas/delete_group_entry permission on the service type.
If the group member being removed does not exist, an error is not thrown.
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-group-admin — Maintains user groups, object groups, or serviceAction groups
Synopsis
cas-group-admin [common options] [ user | object | serviceAction ] create userGpName groupName cas-group-admin [common options] [ user | object | serviceAction ] delete groupName
Tool description
Use cas-group-admin to create or delete user groups, object groups, or serviceAction groups. Note: to add or delete entries to these groups, see [fixme olink to other clients].
Adding user groups
To create a new user group the user must have cas/create_user_group permission (that is, the user must have permission to perform the create_user_group action on the cas service type). The user group name should be unique across the CAS database. The create operation allows the user to choose a user group to have cas/grantAll permission on the created user group. If the user group that is chosen to have cas/grantAll permission is the new group created, then the user making this request is added to the new group.
To add a user group:
casAdmin$cas-group-admin [common options] user createuserGpNamegroupName
where:
userGpName- Indicates the user group to which cas/grantAll permission should be granted on this trust anchor entity.
groupName- Indicates the name of the user group being created.
Deleting user groups
To delete a user group, the user must have cas/delete_user_group entry permission on that user group. The group must be empty and also must not be referenced from other entities in the database (for example, it should not be a member of some object group).
If the user group specified does not exist, an error is not thrown. If the delete operation is successful, all policy data on that user group is purged.
casAdmin$cas-group-admin [common options] user deletegroupName
where:
groupName- Indicates the name of the user group to be deleted.
Creating An Object Group
To create a new object group, the user must have cas/create_object_group permission (that is, the user must have permission to perform the create_object_group action on the CAS service type). The object group name should be unique across the CAS database. The create operation allows the user to choose a user group to have cas/grantAll permission on the created object group.
casAdmin$cas-group-admin [common options] object createuserGpNamegroupName
where:
userGpName- Indicates the user group to which cas/grantAll permission should be granted on this object group.
groupName- Indicates the object group name.
Deleting An Object Group
To delete an object group, the user must have cas/delete_user_group entry permission on that object group. The group must be empty.
If the object group specified does not exist, an error is not thrown. If the delete operation is successful, all policy data on that object group is purged.
casAdmin$cas-group-admin [common options] object deletegroupName
where:
groupName- The name of the object group to be deleted.
Creating A Service/Action Group
To create a new service/action group, the user must have cas/create_serviceAction_group permission (that is, the user must have permission to perform the create_serviceAction_group action on the CAS service type). The serviceAction group name should be unique across the CAS database. The create operation allows the user to choose a user group to have cas/grantAll permission on the created serviceAction group.
casAdmin$cas-group-admin [common options] serviceAction createuserGpNamegroupName
where:
-
userGpName - Indicates the user group to which cas/grantAll permission should be granted on this service/action group.
groupName- Indicates the name of the service/action group being created.
Deleting A Service/Action Group
To delete a service/action group, the user must have cas/delete_user_group entry permission on that service/action group. The group must be empty and also must not be referenced from any other entity in the database. For example, it should not be a member of some object group.
If the service/action group specified does not exist, an error is not thrown. If the delete operation is successful, all policy data on that service/action group is purged.
casAdmin$cas-group-admin [common options] serviceAction deletegroupName
where:
-
groupName - Indicates the name of the service/action group to be deleted.
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-group-add-entry — Adds CAS objects to CAS groups
Synopsis
cas-group-add-entry [common options] user groupName nickname cas-group-add-entry [common options] object groupName objectSpecDesc objectSpec cas-group-add-entry [common options] serviceAction groupName serviceTypeName actionName
Tool description
Use cas-group-add-entry to add users to a user group, objects to an object group, or service/actions to service/action groups. Note: to add or delete groups, see [fixme olink to other clients].
Adding Member To A User Group
To add a user to a user group, the user must have cas/add_group_entry permission on that particular user group. Only user nicknames that exist in the CAS database can be valid members.
casAdmin$cas-group-add-entry [common options] usergroupNamenickname
where:
-
groupName - Indicates the user group name to which the member needs to be added.
-
nickname - Indicates the nickname of the user to be added to this group.
Adding Member To An Object Group
To add a member (an object group can have the following CasObjects as members: object, user, user group, service type, namespace or trust anchor) to an object group, the user must have cas/add_group_entry permission on that particular object group.
casAdmin$cas-group-add-entry [common options] objectgroupNameobjectSpecDescobjectSpec
where:
-
groupName - Indicates the object group name to which the member needs to be added.
-
objectSpecDesc Indicates the type of CasObject. Can be one of the following options:
trustAnchoruseruserGroupobjectnamespaceserviceType
-
objectSpec Indicates the identifier for the CasObject the user is adding. Can be one of the following:
nicknameif adding a trustAnchor or usergroupNameif adding a userGroupobjectNamespaceobjectName if adding an objectnicknameif adding a namespaceserviceTypeNameif adding a serviceType
Adding Service/Action To A Service/Action Group
To add a service/action to a serviceAction group, the user must have cas/add_group_entry permission on that particular serviceAction group (that is, the user must have permission to perform add_group_entry action on that service action group).
casAdmin$cas-group-add-entry [common options] serviceActiongroupNameserviceTypeNameactionName
where:
-
groupName - Indicates the service/action group to which the service/action needs to be added.
-
serviceTypeName - Indicates the service type name part of the mapping to be added to the group.
-
actionName - Indicates the action name part of the mapping to be added to the group.
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-group-remove-entry — Removing CAS objects from CAS groups
Synopsis
cas-group-remove-entry [common options] user groupName nickname cas-group-remove-entry [common options] object groupName objectSpec objectSpecDesc cas-group-remove-entry [common options] serviceAction groupName serviceTypeName actionName
Tool description
Use cas-group-remove-entry to remove users from a user group, objects from an object group, or service/actions from a service/action group. Note: to add or delete groups, see [fixme olink to other clients].
Removing User From A User Group
To remove a user from a user group, the user must have cas/remove_group_entry permission on that particular user group.
If the group member being removed does not exist, an error is not thrown.
casAdmin$cas-group-remove-entry [common options] usergroupNamenickname
where:
-
groupName - Indicates the user group name from which the member needs to be removed.
-
nickname - Indicates the nickname of the user to be removed from this group.
Removing Member From An Object Group
To remove an object from an object group the user must have cas/remove_group_entry permission on that particular object group:
If the group member being removed does not exist, an error is not thrown.
casAdmin$cas-group-remove-entry [common options] objectgroupNameobjectSpecobjectSpecDesc
where:
-
groupName - Indicates the object group name from which the member needs to be removed.
-
objectSpecDesc Indicates the type of CasObject. Can be one of the following options:
trustAnchoruseruserGroupobjectnamespaceserviceType
-
objectSpec Indicates the identifier for the CasObject the user is adding. Can be one of the following:
nicknameif adding a trustAnchor or usergroupNameif adding a userGroupobjectNamespaceobjectName if adding an objectnicknameif adding a namespaceserviceTypeNameif adding a serviceType
Removing A Service/Action From A Service/Action Group
To remove a service/action from a service/action group, the user must have cas/remove_group_entry permission on that particular service/action group.
If the action being removed does not exist, an error is not thrown.
casAdmin$cas-group-remove-entry [common options] serviceActiongroupNameserviceTypeNameactionName
where:
-
groupName - Indicates the serviceAction group name from which the service/action needs to be removed.
-
serviceTypeName - Indicates the service type name part of the mapping to be removed from the group.
-
actionName - Indicates the action name part of the mapping to be removed from the group.
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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-rights-admin — Granting or revoking permissions
Synopsis
cas-rights-admin [common options] [ grant | revoke ] userGroupName objectSpecDesc objectSpec actionSpecDesc actionSpec
Tool description
Use cas-rights-admin to grant or revoke rights.
Granting Permissions To A User Group On An Object/Object Group
The user may grant permissions to a user group on an object or object group to perform a service action or service action group (that is, to perform any action that is a member of the service action group to which permission is granted), provided the user has both:
- cas/grant permission on the object or object group, and
- permission to perform the service action or service action group on the object or object group.
casAdmin$cas-rights-admin [common options] grantuserGroupNameobjectSpecDescobjectSpecactionSpecDescactionSpec
where:
-
userGroupName - Indicates the user group to be granted permission.
-
objectSpec - Indicates the identifier for the object or object group.
-
objectSpecDesc Indicates the type:
objectobjectGroup
-
actionSpec - Indicates the identifier for action or action group.
-
actionSpecDesc Indicates the type:
serviceActionserviceActionGp
Revoking A Policy In The CAS Database
The user may revoke a policy in the CAS database if the user has cas/revoke permission on the object or object group on which the policy is defined.
casAdmin$cas-rights-admin [common options] revokeuserGroupNameobjectSpecDescobjectSpecactionSpecDescactionSpec
where:
-
userGroupName - Indicates the user group for which you want to grant permission.
-
objectSpecDesc Indicates the type of CasObject. Can be one of the following:
trustAnchoruseruserGroupobjectnamespaceserviceTypeuserGroup
-
objectSpec - Indicates the identifier for the object or object group.
-
actionSpec - Indicates the identifier for the action or action group.
-
actionSpecDesc - Indicates the type (serviceAction or serviceActionGp).
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.
valueis in milliseconds. Only supported with the GSI Secure Conversation authentication mechanism.- -m, --securityMech
<type> Specifies the authentication mechanism. The value
typecan be:msgfor GSI Secure Message, orconvfor GSI Secure Conversation.
- -p, --protection
<type> Specifies the protection level.
typecan be:sigfor signature, orencfor encryption.
- -s
cas-url Sets the CAS Service instance, where
cas-urlis 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, whereHostandPortare 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
selforhost.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/, where<fqdn><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.
Table of Contents
- globus-credential-delegate - Delegation client
- globus-credential-refresh - Delegation refresh client
- globus-delegation-client - C Delegation client
Name
globus-credential-delegate — Delegation client
Synopsis
globus-credential-delegate
Tool description
Used to contact a Delegation Factory Service and store a delegated credential. A delegated credential is created and stored in a delegated credential WS-Resource, and the Endpoint Reference(EPR) of the credential is written out to a file for further use.
Command syntax
globus-credential-delegate [options] <eprFilename>
Table 83. globus-credential-delegate options
| -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. |
| -g, --delegation <mode> | Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism. |
| -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. |
| -x, --proxyFilename <value> | Sets the proxy file to use as the client credential. |
| -m, --securityMech <type> | Specifies the authentication mechanism. 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, --service <url> | Specifies the Delegtion Factory Service URL. |
| -x, --proxyFilename <value> | Sets the proxy file to use as client credential. |
| -y, --lifetine <value> | Lifetime of delegated credential in seconds. Default is 43200 (which is 12 hours). |
| -z, --authorization <type> | Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party. |
<eprFilename> | Filename to write the EPR of delegated credential to. |
Name
globus-credential-refresh — Delegation refresh client
Synopsis
globus-credential-refresh
Tool description
Used to refresh delegated credentials pointed to by the specified EPR. A new credential is generated and the one previously created by the Delegation Service is overwritten.
Command syntax
globus-credential-refresh [options]
Table 84. globus-credential-refresh options
| -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 |
| -e, --eprFile <file> | Specifies an XML file that contains the WS-Addressing endpoint reference. The EPR would be of the delegation resource that needs to be refreshed. |
| -f, --descriptor <file> | Specifies a client security descriptor. Overrides all other security settings. |
| -g, --delegation <mode> | Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism. |
| -help | Prints the usage message for the client. |
| -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. For Delegation resource, the name will be as specified here and will replace delegationResourceKey with the actual key: -k "{http://www.globus.org/08/2004/delegationService}DelegationKey delegationResourceKey" |
| -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. |
| -p, --protection <type> | Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption. |
| -s, --service <url> | Specifies the Delegtion Factory Service URL. |
| -x, --proxyFilename <value> | Sets the proxy file to use as the client credential. |
| -y, --lifetine <value> | Lifetime of delegated credential in seconds. Defaults to 43200 (which is 12 hours). |
| -z, --authorization <type> | Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party. |
Name
globus-delegation-client — C Delegation client
Synopsis
globus-delegation-client [OPTION...] {SERVICE-SPECIFIER} {{EPR-FILENAME} | {-refresh}}
Description
Create or refresh delegated credentials in a service container. If
the -refresh option is specified on the command-line,
then the credential associated with an existing DelegationService
resource is updated with a new credential. Otherwise, the
SERVICE-SPECIFIER is interpreted as a DelegationFactoryService and a new
DelegationService resource is created.
Command syntax
globus-delegation-client [OPTION...] {SERVICE-SPECIFIER} {{EPR-FILENAME} | {-refresh}}
SERVICE-SPECIFIER: [-s URI [-k KEY VALUE] | -e FILENAME]
EPR-FILENAME: Name of file to store EPR of new delegated credential.
Table 85. 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. |
Examples
Create a new delegated credential resource and store the EPR of
the resource in ~/.globus/delegation.epr:
% globus-delegation-client -z host -s https://gridhost.virtual.org:8443/wsrf/services/DelegationFactoryService ~/delegation.eprRefresh the previously delegated credential:
% globus-delegation-client -z host -e ~/delegation.epr -refreshDestroy the delegated credential:
% globus-wsrf-destroy -z host -e ~/delegation.eprTable of Contents
- globus-url-copy - Multi-protocol data movement
- globus-gridftp-server - Configures the GridFTP Server
Name
globus-url-copy — Multi-protocol data movement
Synopsis
globus-url-copy
Tool description
globus-url-copy is a scriptable command line tool that can do multi-protocol data movement. It supports gsiftp:// (GridFTP), ftp://, http://, https://, and file:/// protocol specifiers in the URL. For GridFTP, globus-url-copy supports all implemented functionality. Versions from GT 3.2 and later support file globbing and directory moves.
Before you begin
![[Important]](/docbook-images/important.gif) | Important |
|---|---|
To use |
First, as with all things Grid, you must have a valid proxy certificate to run globus-url-copy in certain protocols (
gsiftp://andhttps://, as noted above). If you are usingftp://orhttp://protocols, security is not mandatory and you may skip the rest of this table.If you do not have a certificate, you must obtain one.
If you are doing this for testing in your own environment, the SimpleCA provided with the Globus Toolkit should suffice.
If not, you must contact the Virtual Organization (VO) with which you are associated to find out whom to ask for a certificate.
One common source is the DOE Science Grid CA, although you must confirm whether or not the resources you wish to access will accept their certificates.
Instructions for proper installation of the certificate should be provided from the source of the certificate.
Please note when your certificates expire; they will need to be renewed or you may lose access to your resources.
Now that you have a certificate, you must generate a temporary proxy. Do this by running:
grid-proxy-init
Further documentation for grid-proxy-init can be found here.
You are now ready to use globus-url-copy! See the following sections for syntax and command line options and other considerations.
Command syntax
The basic syntax for globus-url-copy is:
globus-url-copy [optional command line switches]Source_URLDestination_URL
where:
| [optional command line switches] | See Command line options below for a list of available options. |
|
|
Specifies the original URL of the file(s) to be copied. If this is a directory, all files within that directory will be copied. |
|
|
Specifies the URL where you want to copy the files. If you want to copy multiple files, this must be a directory. |
| Note |
|---|---|
Any url specifying a directory must end with /. |
URL prefixes
As of GT 3.2, we support the following URL prefixes:
- file:// (on a local machine only)
- ftp://
- gsiftp://
- http://
- https://
By default, globus-url-copy expects the same kind of host certificates that globusrun expects from gatekeepers.
| Note |
|---|---|
We do not provide an interactive client similar to the generic FTP client provided with Linux. See the Interactive Clients section below for information on an interactive client developed by NCSA/NMI/TeraGrid. |
URL formats
URLs can be any valid URL as defined by RFC 1738 that have a protocol we support. In general, they have the following
format: protocol://host:port/path.
| Note |
|---|---|
If the path ends with a trailing / (i.e. |
Table 87. URL formats
gsiftp://myhost.mydomain.com:2812/data/foo.dat | Fully specified. |
http://myhost.mydomain.com/mywebpage/default.html | Port is not specified; therefore, GridFTP uses protocol default (in this case,
80). |
file:///foo.dat | Host is not specified; therefore, GridFTP uses your local host. Port is not
specified; therefore, GridFTP uses protocol default (in this case, 80). |
file:/foo.dat | This is also valid but is not recommended because, while many servers (including ours) accept this format, it is not RFC conformant and is not recommended. |
| Important |
|---|---|
For GridFTP ( gsiftp:// If you are using GSI security, then you may specify the username (but you may
not include the If you are using anonymous FTP, the username must be one of the usernames listed as a valid anonymous name and the password can be anything. If you are using password authentication, you must specify both your username and password. THIS IS HIGHLY DISCOURAGED, AS YOU ARE SENDING YOUR PASSWORD IN THE CLEAR ON THE NETWORK. This is worse than no security; it is a false illusion of security. |
Command line options
Informational Options
- -help | -usage
Prints help.
- -version
Prints the version of this program.
- -versions
Prints the versions of all modules that this program uses.
- -q | -quiet
Suppresses all output for successful operation.
- -vb | -verbose
During the transfer, displays:
- number of bytes transferred,
- performance since the last update (currently every 5 seconds), and
- average performance for the whole transfer.
- -dbg | -debugftp
Debugs FTP connections and prints the entire control channel protocol exchange to STDERR.
Very useful for debugging. Please provide this any time you are requesting assistance with a globus-url-copy problem.
- -list <url>
This option will display a directory listing for the given url.
Utility Ease of Use Options
- -a | -ascii
Converts the file to/from ASCII format to/from local file format.
- -b | -binary
Does not apply any conversion to the files. This option is turned on by default.
- -f
filename Reads a list of URL pairs from a filename.
Each line should contain:
sourceURLdestURLEnclose URLs with spaces in double quotes ("). Blank lines and lines beginning with the hash sign (#) will be ignored.
- -r | -recurse
Copies files in subdirectories.
- -notpt | -no-third-party-transfers
Turns third-party transfers off (on by default).
Site firewall and/or software configuration may prevent a connection between the two servers (a third party transfer). If this is the case, globus-url-copy will "relay" the data. It will do a GET from the source and a PUT to the destination.
This obviously causes a performance penalty but will allow you to complete a transfer you otherwise could not do.
Reliability Options
- -rst | -restart
Restarts failed FTP operations.
- -rst-retries <retries>
Specifies the maximum number of times to retry the operation before giving up on the transfer.
Use 0 for infinite.
The default value is 5.
- -rst-interval <seconds>
Specifies the interval in seconds to wait after a failure before retrying the transfer.
Use 0 for an exponential backoff.
The default value is 0.
- -rst-timeout <seconds>
Specifies the maximum time after a failure to keep retrying.
Use 0 for no timeout.
The default value is 0.
Performance Options
- -tcp-bs <size> | -tcp-buffer-size <size>
Specifies the size (in bytes) of the TCP buffer to be used by the underlying ftp data channels.
Important This is critical to good performance over the WAN.
- -p <parallelism> | -parallel <parallelism>
Specifies the number of parallel data connections that should be used.
Note This is one of the most commonly used options.
- -bs <block size> | -block-size <block size>
Specifies the size (in bytes) of the buffer to be used by the underlying transfer methods.
- -pp
(New starting with GT 4.1.3) Allows pipelining. GridFTP is a command response protocol. A client sends one command and then waits for a "Finished response" before sending another. Adding this overhead on a per-file basis for a large data set partitioned into many small files makes the performance suffer. Pipelining allows the client to have many outstanding, unacknowledged transfer commands at once. Instead of being forced to wait for the "Finished response" message, the client is free to send transfer commands at any time.
- -mc
filenamesource_url (New starting with GT 4.2.0) Transfers a single file to many destinations. Filename is a line-separated list of destination urls. For more information on this option, click here.
Multicasting must be enabled for use on the server side.
Security Related Options
- -s <subject> | -subject <subject>
Specifies a subject to match with both the source and destination servers.
Note Used when the server does not have access to the host certificate (usually when you are running the server as a user). See the section called “If you run a GridFTP server by hand...”.
- -ss <subject> | -source-subject <subject>
Specifies a subject to match with the source server.
Note Used when the server does not have access to the host certificate (usually when you are running the server as a user). See the section called “If you run a GridFTP server by hand...”.
- -ds <subject> | -dest-subject <subject>
Specifies a subject to match with the destination server.
Note Used when the server does not have access to the host certificate (usually when you are running the server as a user). See the section called “If you run a GridFTP server by hand...”.
- -nodcau | -no-data-channel-authentication
Turns off data channel authentication for FTP transfers (the default is to authenticate the data channel).
![[Warning]](/docbook-images/warning.gif)
Warning We do not recommend this option, as it is a security risk.
- -dcsafe | -data-channel-safe
Sets data channel protection mode to SAFE.
Otherwise known as integrity or checksumming.
Guarantees that the data channel has not been altered, though a malicious party may have observed the data.
Warning Rarely used as there is a substantial performance penalty.
- -dcpriv | -data-channel-private
Sets data channel protection mode to PRIVATE.
The data channel is encrypted and checksummed.
Guarantees that the data channel has not been altered and, if observed, it won't be understandable.
Warning VERY rarely used due to the VERY substantial performance penalty.
Default globus-url-copy usage
A globus-url-copy invocation using the gsiftp protocol with no options (i.e., using all the defaults) will perform a transfer with the following characteristics:
- binary
- stream mode (which implies no parallelism)
- host default TCP buffer size
- encrypted and checksummed control channel
- an authenticated data channel
MODES in GridFTP
GridFTP (as well as normal FTP) defines multiple wire protocols, or MODES, for the data channel.
Most normal FTP servers only implement stream mode (MODE S) , i.e. the bytes flow in order over a single TCP connection. GridFTP defaults to this mode so that it is compatible with normal FTP servers.
However, GridFTP has another MODE, called Extended Block Mode, or MODE E. This mode sends the data over
the data channel in blocks. Each block consists of 8 bits of flags, a 64 bit integer
indicating the offset from the start of the transfer, and a 64 bit integer indicating the
length of the block in bytes, followed by a payload of length bytes. Because the offset and
length are provided, out of order arrival is acceptable, i.e. the 10th block could arrive
before the 9th because you know explicitly where it belongs. This allows us to use multiple
TCP channels. If you use the -p | -parallelism option, globus-url-copy automatically puts the servers into MODE E.
| Note |
|---|---|
Putting |
If you run a GridFTP server by hand...
If you run a GridFTP server by hand, you will need to explicitly specify the subject name to expect. The subject option provides globus-url-copy with a way to validate the remote servers with which it is communcating. Not only must the server trust globus-url-copy, but globus-url-copy must trust that it is talking to the correct server. The validation is done by comparing host DNs or subjects.
If the GridFTP server in question is running under a host certificate then
the client assumes a subject name based on the server's canonical DNS name. However, if it
was started under a user certificate, as is the case when a server is started
by hand, then the expected subject name must be explicitly stated. This is done with the
-ss, -sd, and -s options.
-ssSets the
sourceURLsubject.-dsSets the
destURLsubject.-sIf you use this option alone, it will set both urls to be the same. You can see an example of this usage under the Troubleshooting section.
Note This is an unusual use of the client. Most times you need to specify both URLs.
How do I choose a value?
How do I choose a value for the TCP buffer size (-tcp-bs) option?
The value you should pick for the TCP buffer size (-tcp-bs) depends
on how fast you want to go (your bandwidth) and how far you are moving the data (as
measured by the Round Trip Time (RTT) or the time it takes a packet to get to the
destination and back).
To calculate the value for -tcp-bs, use the following formula (this
assumes that Mega means 1000^2 rather than 1024^2, which is typical for bandwidth):
-tcp-bs = bandwidth in Megabits per second (Mbs) * RTT in
milliseconds (ms) * 1000 / 8
As an example, if you are using fast ethernet (100 Mbs) and the RTT was 50 ms it would be:
-tcp-bs = 100 * 50 * 1000 / 8 = 625,000 bytes.
So, how do you come up with values for bandwidth and RTT? To determine RTT, use either ping or traceroute. They both list RTT values.
| Note |
|---|---|
You must be on one end of the transfer and ping the other end. This means that if you are doing a third party transfer you have to run the ping or traceroute between the two server hosts, not from your client. |
The bandwidth is a little trickier. Any point in the network can be the bottleneck, so you either need to talk with your network engineers to find out what the bottleneck link is or just assume that your host is the bottleneck and use the speed of your network interface card (NIC).
| Note |
|---|---|
The value you pick for |
So where does this formula come from? Because it uses the bandwidth and the RTT (also known as the latency or delay) it is called the bandwidth delay product. The very simple explanation is this: TCP is a reliable protocol. It must save a copy of everything it sends out over the network until the other end acknowledges that it has been received.
As a simple example, if I can put one byte per second onto the network, and it takes 10 seconds for that byte to get there, and 10 seconds for the acknowledgment to get back (RTT = 20 seconds), then I would need at least 20 bytes of storage. Then, hopefully, by the time I am ready to send byte 21, I have received an acknowledgement for byte 1 and I can free that space in my buffer. If you want a more detailed explanation, try the following links on TCP tuning:
How do I choose a value for the parallelism (-p) option?
For most instances, using 4 streams is a very good rule of thumb. Unfortunately, there is not a good formula for picking an exact answer. The shape of the graph shown here is very characteristic.
You get a strong, nearly linear, increase in bandwidth, then a sharp knee, after which additional streams have very little impact. Where this knee is depends on many things, but it is generally between 2 and 10 streams. Higher bandwidth, longer round trip times, and more congestion in the network (which you usually can only guess at based on how applications are behaving) will move the knee higher (more streams needed).
In practice, between 4 and 8 streams are usually sufficient. If things look really bad, try 16 and see how much difference that makes over 8. However, anything above 16, other than for academic interest, is basically wasting resources.
Interactive clients for GridFTP
The Globus Project does not provide an interactive client for GridFTP. Any normal FTP client will work with a GridFTP server, but it cannot take advantage of the advanced features of GridFTP. The interactive clients listed below take advantage of the advanced features of GridFTP.
There is no endorsement implied by their presence here. We make no assertion as to the quality or appropriateness of these tools, we simply provide this for your convenience. We will not answer questions, accept bugs, or in any way shape or form be responsible for these tools, although they should have mechanisms of their own for such things.
UberFTP was developed at the NCSA under the auspices of NMI and TeraGrid:
- NCSA Uberftp only download: http://dims.ncsa.uiuc.edu/set/uberftp/download.html
- UberFTP User's Guide: http://dims.ncsa.uiuc.edu/set/uberftp/userdoc.html
Name
globus-gridftp-server — Configures the GridFTP Server
Synopsis
globus-gridftp-server
Tool description
globus-gridftp-server configures the GridFTP server using a config file and/or commandline options.
| Note |
|---|---|
Command line options and configuration file options may both be used, but the command line overrides the config file. |
The configuration file for the GridFTP server is read from the following locations, in the given order. Only the first file found will be loaded:
- Path specified with the
-c <configfile>command line option. -
$GLOBUS_LOCATION/etc/gridftp.conf -
/etc/grid-security/gridftp.conf
Options are one per line, with the format:
<option> <value>
If the value contains spaces, they should be enclosed in double-quotes ("). Flags or boolean options should only have a value of 0 or 1. Blank lines and lines beginning with # are ignored.
For example:
port 5000
allow_anonymous 1
anonymous_user bob
banner "Welcome!"
Developer notes
The Globus implementation of the GridFTP server draws on:
three IETF RFCs:
- RFC 959
- RFC 2228
- RFC 2389
- an IETF Draft: MLST-16
- the GridFTP protocol specification, which is Global Grid Forum (GGF) Standard GFD.020.
The command line tools and the client library completely hide the details of the protocol from the user and the developer. Unless you choose to use the control library, it is not necessary to have a detailed knowledge of the protocol.
Command syntax
The basic syntax for globus-gridftp-server is:
globus-gridftp-server [optional command line switches]
To use globus-gridftp-server with a config file, make sure to use the
-c <configfile> option.
Command line options
The table below lists config file options, associated command line options (if available) and descriptions.
| Note |
|---|---|
Any boolean option can be negated on the command line by preceding the specified option with '-no-' or '-n'. example: -no-cas or -nf. |
Informational Options
-
help <0|1>,-h,-help Show usage information and exit.
Default value: FALSE
-
version <0|1>,-v,-version Show version information for the server and exit.
Default value: FALSE
-
versions <0|1>,-V,-versions Show version information for all loaded globus libraries and exit.
Default value: FALSE
Modes of Operation
-
inetd <0|1>,-i,-inetd Run under an inetd service.
Default value: FALSE
-
daemon <0|1>,-s,-daemon Run as a daemon. All connections will fork off a new process and setuid if allowed. See Section 4, “Running in daemon mode” for more information.
Default value: TRUE
-
detach <0|1>,-S,-detach Run as a background daemon detached from any controlling terminals. See Section 4, “Running in daemon mode” for more information.
Default value: FALSE
-
exec <string>,-exec <string> For statically compiled or non-GLOBUS_LOCATION standard binary locations, specify the full path of the server binary here. Only needed when run in daemon mode.
Default value: not set
-
chdir <0|1>,-chdir Change directory when the server starts. This will change directory to the dir specified by the chdir_to option.
Default value: TRUE
-
chdir_to <string>,-chdir-to <string> Directory to chdir to after starting. Will use
/if not set.Default value: not set
-
fork <0|1>,-f,-fork Server will fork for each new connection. Disabling this option is only recommended when debugging. Note that non-forked servers running as 'root' will only accept a single connection and then exit.
Default value: TRUE
-
single <0|1>,-1,-single Exit after a single connection.
Default value: FALSE
Authentication, Authorization, and Security Options
-
auth_level <number>,-auth-level <number> - 0 = Disables all authorization checks.
- 1 = Authorize identity only.
- 2 = Authorize all file/resource accesses.
If not set, the GridFTP Server uses level 2 for front ends and level 1 for data nodes.
Default value: not set
-
allow_from <string>,-allow-from <string> Only allow connections from these source IP addresses. Specify a comma-separated list of IP address fragments. A match is any IP address that starts with the specified fragment. Example: '192.168.1.' will match and allow a connection from 192.168.1.45. Note that if this option is used, any address not specifically allowed will be denied.
Default value: not set
-
deny_from <string>,-deny-from <string> Deny connections from these source IP addresses. Specify a comma-separated list of IP address fragments. A match is any IP address that starts with the specified fragment. Example: '192.168.2.' will match and deny a connection from 192.168.2.45.
Default value: not set
-
cas <0|1>,-cas Enable Community Authorization Service (CAS) authorization. For complete instructions on setting up a GridFTP server to use CAS, click here.
Default value: TRUE
-
secure_ipc <0|1>,-si,-secure-ipc Use GSI security on the IPC channel.
Default value: TRUE
-
secure_ipc <0|1>,-si,-secure-ipc Use GSI security on the IPC channel.
Default value: TRUE
-
ipc_auth_mode <string>,-ia <string>,-ipc-auth-mode <string> Set GSI authorization mode for the IPC connection. Options are one of the following:
- none
- host
- self
- subject:[subject]
Default value: host
-
allow_anonymous <0|1>,-aa,-allow-anonymous Allow cleartext anonymous access. If server is running as root, anonymous_user must also be set. Disables IPC security.
Default value: FALSE
-
anonymous_names_allowed <string>,-anonymous-names-allowed <string> Comma-separated list of names to treat as anonymous users when allowing anonymous access. If not set, the default names of 'anonymous' and 'ftp' will be allowed. Use '*' to allow any username.
Default value: not set
-
anonymous_user <string>,-anonymous-user <string> User to setuid to for an anonymous connection. Only applies when running as root.
Default value: not set
-
anonymous_group <string>,-anonymous-group <string> Group to setgid to for an anonymous connection. If not set, the default group of anonymous_user will be used.
Default value: not set
-
pw_file <string>,-password-file <string> Enable cleartext access and authenticate users against this
/etc/passwdformatted file.Default value: not set
-
connections_max <number>,-connections-max <number> Maximum concurrent connections allowed. Only applies when running in daemon mode. Unlimited if not set.
Default value: not set
-
connections_disabled <0|1>,-connections-disabled Disable all new connections. Does not affect ongoing connections. This must be set in the configuration file and then a SIGHUP issued to the server in order to reload the configuration.
Default value: FALSE
Logging Options
-
log_level <string>,-d <string>,-log-level <string> Log level. A comma-separated list of levels from the following:
- ERROR
- WARN
- INFO
- DUMP
- ALL
For example:
globus-gridftp-server -d error,warn,info
You may also specify a numeric level of 1-255.
Default value: ERROR
-
log_module <string>,-log-module <string> Indicates the
globus_loggingmodule that will be loaded. If not set, the defaultstdiomodule will be used and the logfile options (see next option) will apply.Built-in modules are
stdioandsyslog. Log module options may be set by specifyingmodule:opt1=val1:opt2=val2. Available options for the built-in modules are:interval- Indicates buffer flush interval. Default is 5 seconds. A 0 second flush interval will disable periodic flushing, and the buffer will only flush when it is full.buffer- Indicates buffer size. Default is 64k. A value of 0k will disable buffering and all messages will be written immediately.
Example:
-log-module stdio:buffer=4096:interval=10
Default value: not set
-
log_single <string>,-l <string>,-logfile <string> Indicates the path of a single file to which you want to log all activity. If neither this option nor
log_uniqueis set, logs will be written to stderr, unless the execution mode is detached, or inetd, in which case logging will be disabled.Default value: not set
-
log_unique <string>,-L <string>,-logdir <string> Partial path to which
gridftp.(pid).logwill be appended to construct the log filename. Example:-L /var/log/gridftp/
will create a separate log (
/var/log/gridftp/gridftp.xxxx.log) for each process (which is normally each new client session). If neither this option norlog_singleis set, logs will be written to stderr, unless the execution mode is detached, or inetd, in which case logging will be disabled.Default value: not set
-
log_transfer <string>,-Z <string>,-log-transfer <string> Log NetLogger-style info for each transfer into this file.
Default value: not set
Example: DATE=20050520163008.306532 HOST=localhost PROG=globus-gridftp-server NL.EVNT=FTP_INFO START=20050520163008.305913 USER=ftp FILE=/etc/group BUFFER=0 BLOCK=262144 NBYTES=542 VOLUME=/ STREAMS=1 STRIPES=1 DEST=[127.0.0.1] TYPE=RETR CODE=226
Time format is YYYYMMDDHHMMSS.UUUUUU (microsecs).
- DATE: time the transfer completed.
- START: time the transfer started.
- HOST: hostname of the server.
- USER: username on the host that transfered the file.
- BUFFER: tcp buffer size (if 0 system defaults were used).
- BLOCK: the size of the data block read from the disk and posted to the network.
- NBYTES: the total number of bytes transfered.
- VOLUME: the disk partition where the transfer file is stored.
- STREAMS: the number of parallel TCP streams used in the transfer.
- STRIPES: the number of stripes used on this end of the transfer.
- DEST: the destination host.
- TYPE: the transfer type, RETR is a send and STOR is a receive (ftp 959 commands).
- CODE: the FTP rfc959 completion code of the transfer. 226 indicates success, 5xx or 4xx are failure codes.
-
log_filemode <string>,-log-filemode <string> File access permissions of log files. Should be an octal number such as 0644 (the leading 0 is required).
Default value: not set
-
disable_usage_stats <0|1>,-disable-usage-stats Disable transmission of per-transfer usage statistics. See the Usage Statistics section in the online documentation for more information.
Default value: FALSE
-
usage_stats_target <string>,-usage-stats-target <string> Comma-separated list of contact strings for usage statistics listeners. The format of <string> is
host:port.Default value:
usage-stats.globus.org:4810Example:
-usage-stats-target usage-stats.globus.org:4810,usage-stats.uc.teragrid.org:5920
In this example, the usage statistics will be transmitted to the default Globus target (
usage-stats.globus.org:4810) and another target (usage-stats.uc.teragrid.org:5920).
Single and Striped Remote Data Node Options
-
remote_nodes <string>,-r <string>,-remote-nodes <string> Comma-separated list of remote node contact strings. See Remote data-nodes and striped operations and Separation of processes for higher security for examples of using this option.
Default value: not set
-
data_node <0|1>,-dn,-data-node This server is a back end data node. See Separation of processes for higher security for an example of using this option.
Default value: FALSE
-
stripe_blocksize <number>,-sbs <number>,-stripe-blocksize <number> Size in bytes of sequential data that each stripe will transfer.
Default value: 1048576
-
stripe_layout <number>,-sl <number>,-stripe-layout <number> Stripe layout. 1 = Partitioned, 2 = Blocked.
Default value: 2
-
stripe_blocksize_locked <0|1>,-stripe-blocksize-locked; Do not allow client to override stripe blocksize with the OPTS RETR command.
Default value: FALSE
-
stripe_layout_locked <0|1>,-stripe-layout-locked Do not allow client to override stripe layout with the OPTS RETR command.
Default value: FALSE
Disk Options
-
blocksize <number>,-bs <number>,-blocksize <number> Size in bytes of data blocks to read from disk before posting to the network.
Default value: 262144
-
sync_writes <0|1>,-sync-writes Flush disk writes before sending a restart marker. This attempts to ensure that the range specified in the restart marker has actually been committed to disk. This option will probably impact performance and may result in different behavior on different storage systems. See the man page for sync() for more information.
Default value: FALSE
Network Options
-
port <number>,-p <number>,-port <number> Port on which a front end will listen for client control channel connections or on which a data node will listen for connections from a front end. If not set, a random port will be chosen and printed via the logging mechanism. See Remote data-nodes and striped operations and Separation of processes for higher security for examples of using this option.
Default value: not set
-
control_interface <string>,-control-interface <string> Hostname or IP address of the interface to listen for control connections on. If not set, will listen on all interfaces.
Default value: not set
-
data_interface <string>,-data-interface <string> Hostname or IP address of the interface to use for data connections. If not set will use the current control interface.
Default value: not set
-
ipc_interface <string>,-ipc-interface <string> Hostname or IP address of the interface to use for IPC connections. If not set, will listen on all interfaces.
Default value: not set
-
hostname <string>,-hostname <string> Effectively sets the above
control_interface,data_interfaceandipc_interfaceoptions.Default value: not set
-
ipc_port <number>,-ipc-port <number> Port on which the front end will listen for data node connections.
Default value: not set
Timeouts
-
control_preauth_timeout <number>,-control-preauth-timeout <number> Time in seconds to allow a client to remain connected to the control channel without activity before authenticating.
Default value: 30
-
control_idle_timeout <number>;,-control-idle-timeout <number> Time in seconds to allow a client to remain connected to the control channel without activity.
Default value: 600
-
ipc_idle_timeout <number>,-ipc-idle-timeout <number> Idle time in seconds before an unused IPC connection will close.
Default value: 600
-
ipc_connect_timeout <number>,-ipc-connect-timeout <number> Time in seconds before cancelling an attempted IPC connection.
Default value: 60
User Messages
-
banner <string>,-banner <string> Message that is displayed to the client before authentication.
Default value: not set
-
banner_file <string>,-banner-file <string> Read banner message from this file.
Default value: not set
-
banner_terse <0|1>,-banner-terse When this is set, the minimum allowed banner message will be displayed to unauthenticated clients.
Default value: FALSE
-
login_msg <string>,-login-msg <string> Message that is displayed to the client after authentication.
Default value: not set
-
login_msg_file <string>,-login-msg-file <string> Read login message from this file.
Default value: not set
Module Options
-
load_dsi_module <string>,-dsi <string> Load this Data Storage Interface module. File and remote modules are defined by the server. If not set, the file module is loaded, unless the
remoteoption is specified, in which case the remote module is loaded. An additional configuration string can be passed to the DSI using the format[module name]:[configuration string]. The format of the configuration string is defined by the DSI being loaded.Default value: not set
-
allowed_modules <string>,-allowed-modules <string> Comma-separated list of ERET/ESTO modules to allow and, optionally, specify an alias for. Example:
-allowed-modules module1,alias2:module2,module3
(module2 will be loaded when a client asks for alias2).
Default value: not set
Other Options
-
configfile <string>,-c <string> Path to configuration file that should be loaded. Otherwise will attempt to load
$GLOBUS_LOCATION/etc/gridftp.confand/etc/grid-security/gridftp.conf.Default value: not set
-
use_home_dirs <0|1>,-use-home-dirs Set the startup directory to the authenticated user's home dir.
Default value: TRUE
-
debug <0|1>,-debug Set options that make the server easier to debug. Forces no-fork, no-chdir, and allows core dumps on bad signals instead of exiting cleanly. Not recommended for production servers. Note that non-forked servers running as root will only accept a single connection and then exit.
Default value: FALSE
Limitations
For transfers using parallel data transport streams and for transfers using multiple computers at each end, the direction of the connection on the data channels must go from the sending to the receiving side. For more information about this limitations see http://www.ogf.org/documents/GFD.20.pdf.
Globus GridFTP server does not run on windows
Table of Contents
- 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
Name
rft — Submit and monitor a 3rd party GridFTP transfer
Synopsis
rft
Tool description
Submits a transfer to the Reliable File Transfer Service and prints out the status of the transfer on the console.
Command syntax and options
rft [-h <host-ip of the container defaults to localhost> -r <port, defaults to 8080> -l <lifetime for the resource default 60mins> -m <security mechanism. 'msg' for secure message or 'conv' for secure conversation and 'trans' for transport. Defaults to secure transport.> -p <protection type, 'sig' signature and 'enc' encryption, defaults to signature > -z <authorization mechanism can be self or host. default self> -file <file to write EPR of created Reliable File Transfer Resource]> -f <path to the file that contains list of transfers>
This is a sample transfer file that the command-line client will be able to parse. It can also be found in $GLOBUS_LOCATION/share/globus_wsrf_rft_client/ along with other samples for directory transfers and deletes (lines starting with # are comments):
This option when it is set to true means to perform transfer in binary form, if it is set to false transfer is done in ASCII. Default is binary. true #Block size in bytes that is transferred. Default is 16000 bytes. 16000 #TCP Buffer size in bytes #Specifies the size (in bytes) of the TCP buffer to be used by the underlying ftp data channels. This is critical to good performance over the WAN. Use the bandwidth-delay product as your buffer size. 16000 #Notpt (No thirdPartyTransfer): turns third-party transfers off is this option is set to false (on if set to true). Site firewall and/or software configuration may prevent a connection between the two servers (a third party transfer). If this is the case, RFT will "relay" the data. It will do a GET from the source and a PUT to the destination. This obviously causes a performance penalty, but will allow you to complete a transfer you otherwise could not do. false #Number of parallel streams: Specifies the number of parallel data connections that should be used. 1 #Data Channel Authentication (DCAU): Turns off data channel authentication for FTP transfers is set to false.(the default is true to authenticate the data channel). true # Concurrency of the request: Number of files that you want to transfer at any given point. Default is set to one. 1 #Grid Subject name of the source gridftp server. This is used for Authorization purposes. If the source gridftp server is running with host credentials you can specify "null" here. By default host authorization is performed /DC=org/DC=doegrids/OU=People/CN=Ravi Madduri 134710 #Grid Subject name of the destination gridftp server. This is used for Authorization purposes. If the destination gridftp server is running with host credentials you can specify "null" here. By default Host authorization is done. /DC=org/DC=doegrids/OU=People/CN=Ravi Madduri 134710 #Transfer all or none of the transfers: This option if set to true will make RFT to clean up ( delete ) all the transfers that have been done already if one of the transfers fails. Used in GRAM when staging. false #Maximum number of retries: This is number of times RFT retries a transfer failed with a non-fatal error. 10 #Source/Dest URL Pairs: gsiftp urls of source followed by destination. If directory is to be recursively transferred the source gsiftp url and destination gsiftp url should end with "/". Currently RFT supports Directory - Directory, File - Directory, File - File transfers. There can be more URL pairs and all of them use the same options as above for performing the transfer. gsiftp://localhost:5678/tmp/rftTest.tmp gsiftp://localhost:5678/tmp/rftTest_Done.tmp
Limitations
This command line client is very simple and does not do any intelligent parsing of various command line options or of the options in the sample transfer file. It works fine if used in the way documented here. For more information on all these options please refer to the documentation of globus-url-copy. Also, please note that the maximum number of transfers the command-line client can process before running out of memory is ~21K with the default JVM heap size, which was 64M in our tests. Please look at Performance Reports for more details.
Name
globus-crft — Command-line client to transfer files using RFT
Synopsis
globus-crft
Tool description
This distribution contains a client to the RFT service written in C. RFT is the reliable transfer server. It allows clients to submit URL transfer requests to a persistent service which will perform the transfers on behalf of the client.
Options
-
-a|--all-or-none<on | off> - Enable all or none transfer: default off.
-
-con|--concurrent<int> - The number of simultaneous transfers.
-C|--cancel- Cancel a transfer.
-c|--create- Create a new RFT service.
-del|--delete- Delete a URL.
-ds|--destination-subject<subject>- The expected domain name of the destination GridFTP server.
-d|--destroy- Destroy the server. If used with
-monitor, wait until completion and then destroy. -D|--doneReturn the current status of the transfer in the exit code:
- 0=Done
- 1=Active
- 2=Pending
- 3=Cancelled
- 4=Failed
-ef|--epr-file<path>- Path to the EPR file. If used with
--createthe EPR is written to this location. In all other cases the EPR is read from this location. - -ez | --easy
- Create, submit, and wait for the transfer to complete. The job is started with some standard options.
- -e | --factory <contact>
- The endpoint to contact when creating a server. Used with --create.
-f|--transfer-file <path>- A path to a file that contains the source destination URL pairs.
-gS|--getStatusSet <int> <int>- Get the status of all the transfer requests in the range.
-g|--getStatus<source url>- Get the status of the given source url.
-h|--help- Print usage information.
FIXME - finish converting to variable list:
-ms | --message-security <[sig] | [conv] | [trans]>
Security mechanism. 'msg' for secure message,
'conv' for secure conversation, 'trans' for
transport. The default is trans.
-m | --monitor Wait for the service to complete, and recieve
status updates.
-os | --getOverallStatus Get the overall status.
-p | --protection <[sig] | [enc]>
Protection type. 'sig' for signature, 'enc' for
encryption. The default is 'sig'.
-P | --parallel <int> The number of parallel sockets to use with each
transfer.
-q | --quiet Write no output.
-rs | --getRequestStatus Get the request status.
-r | --retries Number of retries
-S | --subject <subject> The expected domain name of both the source and
destination GridFTP servers.
-ss | --source-subject <subject>
The expected domain name of the source GridFTP
server.
-s | --submit Start the RFT service
-tb | --tcp-bs <int> The TCP buffer size to use with each transfer.
-ttl | --termination-time <int>
Set the lifetime of the service.
-v | --version Print version information.
-vb | --verbose Display much more output.
-xi | --xml-input <path> Read the request description from the given xml
description.
-xo | --xml-output <path> Write the request description to the given file
location in xml format.
-z | --authz <[self] | [host] | [id <subject>]>
Authorization. 'self', 'host', or 'id <DN>'.
Name
rft-delete — Command-line client to delete files using RFT
Synopsis
rft-delete
Command and options
rft-delete [-h <host-ip of the container default localhost> -r <port, defaults to 8080> -l <lifetime for the resource default 60mins> -m <security mechanism. 'msg' for secure message or 'conv' for secure conversation and 'trans' for transport. Defaults to secure transport.> -p <protection type, 'sig' signature and 'enc' encryption, defaults to signature > -z <authorization mechanism can be self or host. default self> -file <file to write EPR of created Reliable File Transfer Resource]> -f <path to the file that contains list of transfers>
This is a sample file that the command line client will be able to parse, and it can also be found in $GLOBUS_LOCATION/share/globus_wsrf_rft_client/ along with other samples for directory transfers and deletes (lines starting with # are comments):
# Subject name (defaults to host subject) /DC=org/DC=doegrids/OU=People/CN=Ravi Madduri 134710 gsiftp://localhost:5678/tmp/rftTest_Done.tmp gsiftp://localhost:5678/tmp/rftTest_Done1.tmp
Table of Contents
- globus-rls-admin - RLS administration tool
- globus-rls-cli - RLS client tool
- globus-rls-server - RLS server tool
Name
globus-rls-admin — RLS administration tool
Synopsis
globus-rls-admin
Synopsis
-A|-a|-C option value|-c option|-d|-e|-p|-q|-s|-t timeout|-u|-v [ rli ] [ pattern ] [ server ]
Options
Table 88. Options for globus-rls-admin
| -A | Adds rli to the list of RLI servers updated by an LRC server using Bloom filters. Note: Partitions are not supported with Bloom filters. The LRC server maintains one Bloom filter for all LFNs in its database, which is sent to all RLI servers configured to receive Bloom filter updates with this option. |
| -a | Adds rli and optionally pattern to the list of RLI servers that the LRC server sends updates to (using a list of LFNs). If pattern is specified, then only LFNs matching it will be sent to rli. If rli is added with no patterns, then it is sent all updates. Pattern matching is done using standard Unix file globbing. |
| -C option value | Sets server option to value. Important: This does not update the configuration file. The next time the server is restarted, the configuration change will be lost. |
| -c option | Retrieves the configuration value for the specified option from the server. If option is set to all, then all options are retrieved. |
| -d | Removes rli and pattern from the list of RLI servers that the LRC server sends updates to. If pattern is not specified, then all entries for rli are removed. Note: If all patterns are removed separately, then rli is sent all updates. To stop any updates from being sent to rli, do not specify pattern. |
| -e | Clears the LRC database. Removes all lfn, pfn mappings. |
| -p | Verifies that the server is responding. |
| -q | Causes the RLS server to exit. |
| -S | Shows statistics and other information gathered by the RLS server. This is intended to be input into GRIS. |
| -s | Shows the list of RLI servers and patterns being sent updates by the LRC server. If rli or pattern are not specified, they are considered wildcards. |
| -t timeout | Sets timeout (in seconds) for RLS server requests. The default value is 30. |
| -u | Causes the LRC server to immediately start full soft state updates to any RLI servers previously added with the -a option. |
| -v | Shows the version and exits. |
Name
globus-rls-cli — RLS client tool
Synopsis
globus-rls-cli
Tool description
Provides a command line interface to some of the functions supported by RLS. It also supports an interactive interface (if command is not specified). In interactive mode, double quotes may be used to encode an argument that contains white space.
Options
The client command tool uses getopt for command line parsing.
Note: Some versions will continue scanning for options (works that begin with a hyphen) for the entire command line, which makes it impossible to specify negative integer or floating point value for an attribute. The workaround for this problem is to tell getopt() that there are no more options by including 2 hyphens. For example, to specify the value -2 you must enter -- -2.
Table 89. Options for globus-rls-cli
| -c | Sets "clearvalues" flag when deleting an attribute (will remove any attribute value records when an attribute is deleted). |
| -h | Shows usage. |
| -l reslimit |
Sets an incremental limit on the number of results returned by a wildcard query at a time. Note that all results will be returned by the client. This parameter only limits the number of results incrementally retrieved by the client during a single internal communication call. For instance, if the wildcard query produces 1000 results and the reslimit is set to 100, the client will internally make 10 calls to the server. From the user's perspective the client will simply return all 1000 results. Zero means no limit. |
| -s | Uses SQL style wildcards (% and _). |
| -t timeout | Sets timeout (in seconds) for RLS server requests. The default is 30 seconds. |
| -u | Uses Unix style wildcards (* and ?). |
| -v | Shows version. |
Commands
Table 90. Commands for globus-rls-cli
| add <lfn> <pfn> | Adds pfn to mappings of lfn in an LRC catalog. |
| attribute add <object> <attr> <obj-type> <attr-type> | Adds an attribute to an object, where object should be the lfn or pfn name. obj-type should be one of lfn or pfn. attr-type should be one of date, float, int, or string. If <value> is of type date then it should be in the form "YYYY-MM-DD HH:MM:DD". |
| attribute bulk add <object> <attr> <obj-type> | Bulk adds attribute values. |
| attribute bulk delete <object> <attr> <obj-type> | Bulk deletes attributes. |
| attribute bulk query <attr> <obj-type> <object> | Bulk queries attributes. |
| attribute define <attr> <obj-type> <attr-type> | Defines a new attribute. |
| attribute delete <object> <attr> <obj-type> | Removes attribute from object. |
| attribute modify <object> <attr> <obj-type> <attr-type> | Modifies the value of an attribute. |
| attribute query <object> <attr> <obj-type> | Retrieves the value of the specified attribute for object. |
| attribute search <attr> <obj-type> <operator> <attr-type> | Searches for objects which have the specified attribute matching operator and value. operator should be one of =, !=, >, >=, <, or <=. |
| attribute show <attr> <obj-type> | Shows an attribute definition. If attr is a hyphen (-) then all attributes are shown. |
| attribute undefine <attr> <obj-type> | Deletes an attribute definition. Will return an error if any objects possess this attribute. |
| bulk add <lfn> <pfn> [<lfn> <pfn>] | Bulk adds lfn, pfn mappings. |
| bulk create <lfn> <pfn> [<lfn> <pfn>] | Bulk creates lfn, pfn mappings. |
| bulk delete <lfn> <pfn> [<lfn> <pfn>] | Bulk deletes lfn, pfn mappings. |
| bulk query lrc lfn [<lfn> ...] | Bulk queries the LRC for lfns. |
| bulk query lrc pfn [<pfn> ...] | Bulk queries the LRC for pfns. |
| bulk query rli lfn [<lfn> ...] | Bulk queries the RLI for lfns. |
| create <lfn> <pfn> | Creates a new lfn, pfn mapping in an LRC catalog. |
| delete <lfn> <pfn> | Deletes a lfn, pfn mapping from an LRC catalog. |
| exit | Exits the interactive session. |
| help | Prints a help message. |
| query lrc lfn <lfn> | Queries an LRC server for mappings of lfn. |
| query lrc pfn <pfn> | Queries an LRC server for mappings to pfn. |
| query rli lfn <lfn> | Queries an RLI server for mappings of lfn. |
| query wildcard lrc lfn <lfn-pattern> | Performs a wildcarded query of an LRC server for mappings of lfn-pattern. Patterns use the standard Unix wildcard characters: an asterisk (*) matches 0 or more characters, and a question mark (?) matches any single character. |
| query wildcard lrc pfn <pfn-pattern> | Queries an LRC server for mappings to pfn-pattern. Patterns use the standard Unix wildcard characters: an asterisk (*) matches 0 or more characters, and a question mark (?) matches any single character. |
| query wildcard rli lfn <lfn-pattern> | Queries an RLI server for mappings of lfn-pattern. Patterns use the standard Unix wildcard characters: an asterisk (*) matches 0 or more characters, and a question mark (?) matches any single character. |
| set reslimit <limit> |
Sets an incremental limit on the number of results returned by a wildcard query at a time. Note that all results will be returned by the client. This parameter only limits the number of results incrementally retrieved by the client during a single internal communication call. For instance, if the wildcard query produces 1000 results and the reslimit is set to 100, the client will internally make 10 calls to the server. From the user's perspective the client will simply return all 1000 results. |
| set timeout <timeout> | Sets the timeout (in seconds) on calls to the RLS server. The default value is 30. |
| version | Shows the version and exits. |
Name
globus-rls-server — RLS server tool
Synopsis
globus-rls-server
Tool description
The RLS server (globus-rls-server) can be configured as either one or both of the following:
- Location Replica Catalog (LRC) server, which manages Logical FileName (LFN) to Physical FileName (PFN) mappings in a database. Note: If globus-rls-server is configured as an LRC server, the RLI servers that it sends updates to should be added to the database using globus-rls-admin.
- Replica Location Index (RLI) server, which manages mappings of LFNs to LRC servers.
Clients wishing to locate one or more physical filenames associated with a logical filename should first contact an RLI server, which will return a list of LRCs that may know about the LFN. The LRC servers are then contacted in turn to find the physical filenames.
Note: RLI information may be out of date, so clients should be prepared to get a negative response when contacting an LRC (or no response at all if the LRC server is unavailable).
Synopsis
[ -B lrc_update_bf ] [ -b maxbackoff ] [ -C rlscertfile ] [ -c conffile ] [ -d ] [ -e rli_expire_int ] [ -F lrc_update_factor ] [ -f maxfreethreads ] [ -I true|false [ -i idletimeout ] [ -K rlskeyfile ] [ -L loglevel ] [ -l true|false ] [ -M maxconnections ] [ -m maxthreads ] [ -N ] [ -o lrc_buffer_time ] [ -p pidfiledir ] [ -r true|false ] [ -S rli_expire_stale ] [ -s startthreads ] [ -t timeout ] [ -U myurl ] [ -u lrc_update_ll ] [ -v ]
LRC to RLI Updates
Two methods exist for LRC servers to inform RLI servers of their LFNs.
- By default, the LFNs are sent from the LRC to the RLI. This can be time consuming if the number of LFNs is large, but it does give the RLI an exact list of the LFNs known to the LRC, and it allows wildcard searching of the RLI.
- Alternatively, Bloom filters may be sent, which are highly compressed summaries of the LFNs. However, they do not allow wildcard searching and will generate more "false positives" when querying an RLI.
Please see below for more on Bloom filters.
globus-rls-admin can be used to manage the list of RLIs that an LRC server updates. This includes partitioning LFNs among multiple RLI servers.
A soft state algorithm is used in both update modes: periodically the LRC server sends its state (LFN information) to the RLI servers it updates. The RLI servers add these LFNs to their indexes or update timestamps if the LFNs were already known. RLI servers expire information about LFN, LRC mappings if they haven't been updated for a period longer than the soft state update interval.
The following options in the configuration file control the soft state algorithm when an LRC updates an RLI by sending LFNs:
- rli_expire_int (seconds)
- rli_expire_stale (seconds)
- lrc_update_ll (seconds)
- lrc_update_bf (seconds)
Updates to an LRC (new LFNs or deleted LFNs) normally don't propagate to RLI servers until the next soft state update (controlled by options lrc_update_ll and lrc_update_bf).
However, by enabling "immediate update" mode (set lrc_update_immediate to true), an LRC will send updates to an RLI within lrc_buffer_time seconds.
If updates are done with LFN lists then only the LFNs that have been added or deleted to the LRC are sent. If Bloom filters are used, then the entire Bloom filter is sent.
When immediate updates are enabled, the interval between soft state updates is multiplied by lrc_update_factor as long as no updates have failed (LRC and RLI are considered to be in sync). This can greatly reduce the number of soft state updates an LRC needs to send to an RLI.
Incremental updates are buffered by the LRC server until either 200 updates have accumulated (when LFN lists are used), or lrc_buffer_time seconds have passed since the last update.
Bloom filter updates
A Bloom filter is an array of bits. Each LFN is hashed multiple times and the corresponding bits in the Bloom filter are set.
Querying an RLI to verify if an LFN exists is done by performing the same hashes and checking if the bits in the filter are on. If not, then the LFN is known not to exist. If they're all on, then all that's known is that the LFN probably exists.
The size of the Bloom filter (as a multiple of the number of LFNs) and the number of hash functions control the false positive rate. The default values of 10 and 3 give a false positive rate of approximately 1%.
The advantage of Bloom filters is their efficiency. For example, if the LRC has 1,000,000 LFNs in its database, with an average length of 20 bytes, then 20,000,000 bytes must be sent to an RLI during a soft state update (assuming no partitioning). The RLI server must perform 1,000,000 updates to its database to create new LFN, LRC mappings or update timestamps on existing entries. With Bloom filters only 1,250,000 bytes are sent (10 x 1,000,000 bits / 8), and there are no database operations on the RLI (Bloom filters are maintained entirely in memory). A comparison of the time to perform a 1,000,000 LFN update: it took 20 minutes sending all the LFNs and less than 1 second using a Bloom filter. However as noted before, Bloom filters do not support wild card searches of an RLI.
Note: An LRC server can update some RLIs with Bloom filters and others with LFNs. However, an RLI server can only be updated using one method.
The following options in the Configuration file control Bloom filter updates:
- rli_bloomfilter true|false
- rli_bloomfilter_dir none|default|pathname
- lrc_bloomfilter_numhash N
- lrc_bloomfilter_ratio N
- lrc_update_bf seconds
Log Messages
globus-rls-server uses syslog to log errors and other information (facility LOG_DAEMON) when it's running in normal (daemon) mode.
If the -d option (debug) is specified, then log messages are written to stdout.
Signals
The server will reread its configuration file if it receives a HUP signal. It will wait for all current requests to complete and shut down cleanly if sent any of the following signals: INT, QUIT or TERM.
Options (globus-rls-server)
The following table describes the command line options available for globus-rls-server:
Table 91. Options for globus-rls-server
| -b maxbackoff | Maximum time (in seconds) that globus-rls-server will attempt to reopen the socket it listens on after an I/O error. |
| -C rlscertfile | Name of the X.509 certificate file that identifies the server; sets environment variable X509_USER_CERT. |
| -c conffile | Name of the configuration file for the server. The default is $GLOBUS_LOCATION/etc/globus-rls-server.conf if the environment variable GLOBUS_LOCATION is set; else, /usr/local/etc/globus-rls-server.conf. |
| -d | Enables debugging. The server will not detach from the controlling terminal, and log messages will be written to stdout rather than syslog. For additional logging verbosity set the loglevel (see the -L option) to higher values. |
| -e rli_expire_int | Interval (seconds) at which an RLI server should expire stale entries. |
| -F lrc_update_factor | If lrc_update_immediate mode is on, and the LRC server is in sync with an RLI server (an LRC and RLI are synced if there have been no failed updates since the last full soft state update), then the interval between RLI updates for this server (lrc_update_ll) is multiplied by lrc_update_factor. |
| -f maxfreethreads | Maximum number of idle threads the server will leave running. Excess threads are terminated. |
| -I true|false | Turns LRC to RLI immediate update mode on (true) or off (false). The default value is false. |
| -i idletimeout | Seconds after which idle client connections are timed out. |
| -K rlskeyfile | Name of the X.509 key file. Sets environment variable X509_USER_KEY. |
| -L loglevel | Sets the log level. By default this is 0, which means only errors will be logged. Higher values mean more verbose logging. |
| -l true|false | Configures whether the server is an LRC server. The default is false. |
| -M maxconnections | Maximum number of active connections. It should be small enough to prevent the server from running out of open file descriptors. The default value is 100. |
| -m maxthreads | Maximum number of threads server will start up to support simultaneous requests. |
| -N | Disables authentication checking. This option is intended for debugging. Clients should use the URL RLSN://host to disable authentication on the client side. |
| -o lrc_buffer_time | LRC to RLI updates are buffered until either the buffer is full or this much time (in seconds) has elapsed since the last update. The default value is 30. |
| -p pidfiledir | Directory where PID files should be written. |
| -r | Configures whether the server is an RLI server. The default value is false. |
| -S rli_expire_stale | Interval (in seconds) after which entries in the RLI database are considered stale (presumably because they were deleted in the LRC). Stale entries are not returned in queries. |
| -s startthreads | Number of threads to start up initially. |
| -t timeout | Timeout (in seconds) for calls to other RLS servers (in other words, for LRC calls to send an update to an RLI). A value of 0 disables timeouts. The default value is 30. |
| -U myurl | URL for this server. |
| -u lrc_update_ll | Interval (in seconds) between lfn-list LRC to RLI updates. |
| -v | Shows version and exits. |
The WS RLS provides a set of command-line tools to create, add, remove mappings between logical names and target names, define and undefine attribute definitions, and create, modify, and delete attributes. 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 WS RLS command-line tools make use of the Common Java Client Options. These options are refered to below as [options].
Table of Contents
- 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.
Name
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.
Synopsis
globus-replicalocation-createmappings
Tool description
Use this tool to create mappings between logical names and target names in the replica location catalog. The mapping must not exist. In addition, the logical name must not exist.
Command syntax
globus-replicalocation-createmappings [options] \
{ { logical-name target-name }+ | input-file | - }
Name
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.
Synopsis
globus-replicalocation-addmappings
Tool description
Use this tool to add mappings between logical names and target names in the replica location catalog. The mapping must not exist. In addition, the logical name must exist.
Command syntax
globus-replicalocation-addmappings [options] \
{ { logical-name target-name }+ | input-file | - }
Name
globus-replicalocation-deletemappings — This tool is used to delete mappings between logical names and target names.
Synopsis
globus-replicalocation-deletemappings
Tool description
Use this tool to delete mappings between logical names and target names in the replica location catalog. The mapping must exist.
Command syntax
globus-replicalocation-deletemappings [options] \
{ { logical-name target-name }+ | input-file | - }
Name
globus-replicalocation-defineattributes — This tool is used to define attributes.
Synopsis
globus-replicalocation-defineattributes
Tool description
Use this tool to define attributes. Attribute definitions must be given a name unique within the local instance of the replica location catalog. Attribute definitions must be given a value type of dateTime, decimal, integer, or string. And attribute definitions must be associated with an object type of logical or target.
Command syntax
globus-replicalocation-defineattributes [options] \
{ { name object-type value-type }+ | input-file | - }
Table 95. globus-replicalocation-defineattributes Options
| { name object-type value-type }+ | A listing of attribute name, associated object-type, and value-type. |
| input-file | A file containing the listing of attribute name, associated object-type, and value-type. |
| - | Standard input stream containing the listing of attribute name, associated object-type, and value-type. |
Name
globus-replicalocation-undefineattributes — This tool is used to undefine attributes.
Synopsis
globus-replicalocation-undefineattributes
Tool description
Use this tool to undefine attributes. Attribute definitions must be identified by the definition's name and associated object-type. The operation will clear attribute values for existing attributes with the definition's name.
Command syntax
globus-replicalocation-undefineattributes [options] \
{ { name object-type }+ | input-file | - }
Table 96. globus-replicalocation-undefineattributes Options
| { name object-type }+ | A listing of attribute name and associated object-type. |
| input-file | A file containing the listing of attribute name and associated object-type. |
| - | Standard input stream containing the listing of attribute name and associated object-type. |
Name
globus-replicalocation-addattributes — This tool is used to add attributes.
Synopsis
globus-replicalocation-addattributes
Tool description
Use this tool to add attributes associated with logical names or target names. A corresponding attribute definition must exist. The logical name or target name with which to associate the attribute must exist. There must not be an existing attribute of the same type for a given logical name or target name. When adding attributes, the following parameters are required. The logical name or target name, refered to as the key. The name of the attribute as defined by an existing attribute definition. An object-type of logical or target. A value-type corresponding to dateTime, decimal, integer, or string. And finally a value compatible with the value-type.
Command syntax
globus-replicalocation-addattributes [options] \
{ { key name object-type value-type value }+ | input-file | - }
Table 97. globus-replicalocation-addattributes Options
| { key name object-type value-type value }+ | A listing of key, attribute name, associated object-type, value-type, and value. |
| input-file | A file containing the listing of key, attribute name, associated object-type, value-type, and value. |
| - | Standard input stream containing the listing of key, attribute name, associated object-type, value-type, and value. |
Name
globus-replicalocation-modifyattributes — This tool is used to modify attributes.
Synopsis
globus-replicalocation-modifyattributes
Tool description
Use this tool to modify attributes associated with logical names or target names. Mutability of attributes is limited only to the attribute's value. The corresponding attribute must exist.
Command syntax
globus-replicalocation-modifyattributes [options] \
{ { key name object-type value-type value }+ | input-file | - }
Table 98. globus-replicalocation-modifyattributes Options
| { key name object-type value-type value }+ | A listing of key, attribute name, associated object-type, value-type, and value. |
| input-file | A file containing the listing of key, attribute name, associated object-type, value-type, and value. |
| - | Standard input stream containing the listing of key, attribute name, associated object-type, value-type, and value. |
Name
globus-replicalocation-removeattributes — This tool is used to remove existing attributes.
Synopsis
globus-replicalocation-removeattributes
Tool description
Use this tool to remove existing attributes associated with logical names or target names. The corresponding attribute must exist.
Command syntax
globus-replicalocation-removeattributes [options] \
{ { key name object-type }+ | input-file | - }
Table 99. globus-replicalocation-removeattributes Options
| { key name object-type }+ | A listing of key, attribute name, and associated object-type. |
| input-file | A file containing the listing of key, attribute name, and associated object-type. |
| - | Standard input stream containing the listing of key, attribute name, and associated object-type. |
Table of Contents
- 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
Name
mds-servicegroup-add — Registering grid resources to aggregating MDS services such as the Index, Archive and Trigger services
Synopsis
mds-servicegroup-add
Tool description
mds-servicegroup-add creates a set of registrations to a WS-ServiceGroup and periodically renews those registrations. It is intended primarily for registering grid resources to aggregating MDS services such as the Index and Trigger services.
The tool can be deployed at the aggregating service, at resource services, or at any other location.
This allows registrations to be configured by the administrator of the aggregating service, or by the administrator of resources, by a third party, or by some combination of those.
Registrations are defined in an XML configuration file, which is documented here: Registering Aggregator Sources.
For an example using an Index Service, see Simple usage for the Index Service.
And remember to note the section on Limitations.
Command syntax
The basic syntax for mds-servicegroup-add is:
mds-servicegroup-add [options] config.xmlwhere:
| -s http(s)://host:port/service-group-address | A URL to the service group against which the mds-servicegroup-add request will be executed. This command line argument is an optional argument, it is only necessary that this URL argument be specified in the case that there are no suitable target service group EPRs present in the configuration file. Any end point references found in the configuration file will automatically override the EPR specified by this argument on the command-line. If this argument is not specified and no suitable service group EPR is present in the configuration file, the target EPR defaults to the DefaultIndexService on the local host using the default TLS port of 8443. |
| -o outputFile | If this argument is specified, mds-servicegroup-add will write the EPRs of all successfully created service group entries from the target resource to this file. This file can then be used as input to the mds-set-multiple-termination-time command. |
| -q seconds | By default, mds-servicegroup-add will continue to run, refreshing the lifetimes for the service group entry resources it creates. Use this option to cause mds-servicegroup-add to terminate itself after the specified number of seconds has elapsed. This can be helpful when using long-lifetime registrations or when updating entry lifetimes via a different mechanism. |
| -a | By default, mds-servicegroup-add will attempt to make an authenticated connection to each service group. This option is used to specify anonymous connections (and to prevent mds-servicegroup-add from failing if you don't have a valid Grid credential). |
| -z auth_type | Specify an authorization type:
|
| config.xml | Path to the registration configuration file (see Registering Aggregator Sources). The Globus Toolkit distribution includes an example configuration file:
|
The common java client options are also supported.
Registering a resource manually
Prerequisites
You need the following before you register a resource with an Index Service:
| Note |
|---|---|
Beginning with GT 4.0.1, the CAS, RFT and GRAM4 services are automatically registered with the default Index Service. |
- Have a working Index Service, as documented in the Index Service System Administrator's Guide.
- Know the EPR to the resource.
- Know the EPR to the Index Service. This can be seen in the container output at startup of the container on the index host, and will look something like this:
https://myhost:8443/wsrf/services/DefaultIndexService
Simple usage for the Index Service
The simplest way to register resources to an index is to:
- Edit the example configuration file (
$GLOBUS_LOCATION/etc/globus_wsrf_mds_aggregator/example-aggregator-registration.xml), replacing the EPRs in that file with the EPRs for your resources - Run mds-servicegroup-add to perform the registrations specified in that file.
For example, to register to the DefaultIndexService with a modified example-aggregator-registration.xml file, you
could run a command similar to the following:
$GLOBUS_LOCATION/bin/mds-servicegroup-add -s \
https://127.0.0.1:8443/wsrf/services/DefaultIndexService \
$GLOBUS_LOCATION/etc/globus_wsrf_mds_aggregator/example-aggregator-registration.xml
Name
mds-set-multiple-termination-time — Administering the termination time of grid resources created by aggregating MDS services such as the Index and Trigger services
Synopsis
mds-set-multiple-termination-time
Tool description
mds-set-multiple-termination-time sets the termination time of multiple service group entries. It is intended primarily for working with groups of service group entry resources created by aggregating MDS services such as the Index and Trigger services.
The tool can be deployed at the aggregating service, at resource services, or at any other location.
This allows the lifetime of registrations to be configured by the administrator of the aggregating service, or by the administrator of resources, by a third party, or by some combination of those.
Command syntax
The basic syntax for mds-set-multiple-termination-time is:
mds-set-multiple-termination-time [options]
where:
| -i inputFile | file containing an XML array of Endpoint References, such as one output by the mds-servicegroup-add command when used with the -o option. |
| -w delay | integer wait delay in seconds that will be added to the current time at the remote resource to generate the resource termination time. If not specified the termination time by defaults is set to the current time at the remote resource. |
| -n date string | ISO-8601 formatted date string representing an exact date and time, e.g. 2016-06-28T01:06:430Z If not specified the termination time by default is set to the current time at the remote resource. |
The common java client options are also supported.
Table of Contents
- globusrun-ws - Official job submission client for GRAM4
Name
globusrun-ws — Official job submission client for GRAM4
Synopsis
globusrun-ws -submit [-batch] [-quiet] [-no-cleanup] [-streaming] [-streaming-out filename] [-streaming-err filename] [-host-authz] [-self-authz] [-subject-authz subject name] [-private] [-http-timeout milliseconds] [-debug] [-allow-ipv6] [-passive] [-nodcau] [[-factory-epr-file filename] [[-factory contact] | [-factory-type type]]] [[-submission-id uuid] | [-submission-id-file filename]] [-submission-id-output-file filename] [-job-epr-output-file filename] [-job-delegate] [-staging-delegate] [-job-credential-file filename] [-staging-credential-file filename] [-transfer-credential-file filename] [-termination
[+HH:MMmm/dd/yyyy HH:MM]
] [[-job-description-file filename] | [-job-command [--] program arg ...]]
globusrun-ws -validate -job-description-file filename
globusrun-ws -monitor -job-epr-file filename [-quiet] [-no-cleanup] [-streaming] [-streaming-out filename] [-streaming-err filename] [-host-authz] [-self-authz] [-subject-authz subject name] [-private] [-http-timeout milliseconds] [-debug] [-allow-ipv6] [-passive] [-nodcau]
globusrun-ws -status -job-epr-file filename [-host-authz] [-self-authz] [-subject-authz subject name] [-private] [-http-timeout milliseconds] [-debug]
globusrun-ws -kill -job-epr-file filename [-host-authz] [-self-authz] [-subject-authz subject name] [-private] [-http-timeout milliseconds] [-debug]
globusrun-ws -help
globusrun-ws -usage [-submit] [-validate] [-monitor] [-status] [-kill]
globusrun-ws -version(s)
Description
globusrun-ws (GRAM4 client) is a program for submitting and
managing jobs to a local or remote job host. GRAM4 provides secure
job submission to many types of job scheduler for users who have the
right to access a job hosting resource in a Grid environment. All
GRAM4 submission options are supported transparently through the
embedded request document input. globusrun-ws offers
additional features to fetch job output files incrementally during the
run as well as to automatically delegate credentials needed for
certain optional GRAM4 features. Online and batch submission modes
are supported with reattachment (recovery) for jobs whether they were
started with this client or another GRAM4 client application.
Command options
Quiet mode
A variety of protocol status messages, warning messages, and output data may be printed to standard output and error under multiple command modes. The quiet mode suppresses all but fatal standard error messages in order to have clean outputs for use in scripting or with the streaming output mode where application output is retrieved and output.
- -q, -quiet
If supplied, all non-fatal status and protocol-related messages are suppressed.
Debug mode
- -dbg, -debug
If supplied, all soap messages and ftp control messages will be displayed on stderr.
Protocol Options
Service authorization
Usually, secure communication includes mutual authentication. In addition to the service authorizing the client for the requested operation(s), an authorization decision is made by the client to determine whether the remote service is the one intended.
- -host, -host-authz
The GSI "host authorization" rule is used to verify that the service is using a host credential appropriate for the underlying service address information. This is the default.
- -self, -self-authz
The GSI "self authorization" rule is used to verify that the service is using a (proxy) credential derived from the same identity as the client's.
- -subject, -subject-authz subject name
The service must be using a credential with the exact subject name provided by this option.
Security Protocol
The client uses secure transport for all https endpoints and secure message for http. Secure conversation is currently unsupported.
- -p, -private
If supplied, privacy-protection is enabled between globusrun-ws and GRAM4 or GridFTP services. It is a fatal error to select privacy protection if it is not available due to build options or other security settings. Note: Currently only supported with https endpoints.
Signal handling
- -n, -no-cleanup
If supplied, the default behavior of trapping interrupts (SIG_INTR) and cancelling the job is disabled. Instead, the interrupt simply causes the tool to exit without affecting the ManagedJob resource.
Submit options
- -submit
The -submit command submits (or resubmits) a job to a job host using an XML-based job description document. The -submit command can submit jobs in one of three output modes: batch, interactive, or interactive-streaming.
Output Mode
The user can select several tool behaviors following submission. In batch mode, the tool prints the resulting ManagedJob EPR as the sole standard output (unless in quiet mode) and exits. In interactive mode, the tool keeps running in order to monitor job status. Interactive mode is qualitatively equivalent to a batch-mode submission immediately followed a second invocation of globusrun-ws using the -monitor command. In interactive mode, an optional streaming mode where job output files are fetched and output from globusrun-ws.
- -b, -batch
If supplied, the batch mode is enabled. The default is interactive mode. The tool prints the resulting ManagedJob EPR as the sole standard output (unless in quiet mode) and exits.
- -s, -streaming
The standard output and standard error files of the job are monitored and data is written to the corresponding output of globusrun-ws. The standard output will contain ONLY job output data, while the standard error may be a mixture of job error output as well as globusrun-ws messages, unless the quiet mode is also enabled.
Streaming output depends on the ability to access job outputs via GridFTP. If -streaming mode is selected and the job description does not already specify output file redirection for the job host, then globusrun-ws adds unique output file name redirections and automatic cleanup directives to the job description.
If you are using -batch mode, but intend to use -streaming with -monitor, you may want to still include -streaming. -streaming always introduces a 'CleanUp Hold' state which ensures that all the data is streamed before the files are destroyed. If you do use -streaming with -batch, you must come back with -monitor so the hold can be released.
This option implies -staging-delegate if the stdout and stderr entries are not specified in the job description.
- -so, -stdout-file filename
append stdout out stream to the specified file instead of to stdout.
- -se, -stderr-file filename
append stderr out stream to the specified file instead of to stderr.
Streaming Options
Streaming makes use of GridFTP client calls to retrieve user data. The following options apply to such transfers.
- -ipv6, -allow-ipv6
Allow streaming transfers to use IPV6.
- -passive
Force streaming transfers to use MODE S to allow for passive mode transfers. (Useful if you're behind a firewall, but expensive because there is no connection caching).
- -nodcau
Disable data channel authentication on streaming transfers
Factory information
Addressing information for the ManagedJobFactory target of this submission must be provided. If neither option is specified, and no EPR is supplied in the job description, then "-factory localhost -factory-type fork" is assumed.
- -Ff, -factory-epr-file filename
If supplied, this option causes the EPR for the ManagedJobFactory to be read from the given file. This EPR is used as the service endpoint for submission of the job.
- -F, -factory contact
If supplied, this option causes an EPR to be constructed using ad-hoc methods that depend on GT implementation details. For interoperability to other implementations of GRAM4_, the -factory-epr-file option should be used instead.
[protocol://]{hostname|hostaddr}[:port][/service]
Default values form the following contact information if not overridden:
https://localhost:8443/wsrf/services/ManagedJobFactoryService
- -Ft, -factory-type type
In the absence of -factory-epr-file, this option refines the behavior of the -factory option to select a specific type of scheduler. The default is "Fork" for single jobs and "Multi" for multijobs.
Job description
A description of the job to be submitted must be provided with the -submit command, either using the GRAM4 XML description syntax or a simpler Unix command and argument list.
- -f, -job-description-file filename
If supplied, this option causes the job description to be read from the given file. This description is modified according to the other options and passed in the GRAM4 submission messages. The root element of this file must be 'job' for a single job or 'multiJob' for a multijob.
- -c, -job-command [--] prog [arg ...]
If supplied, this option take all remaining globusrun-ws arguments as its arguments; therefore it must appear last among globusrun-ws options. This option causes globusrun-ws to generate a simple job description with the named program and arguments.
Submission ID
A submission ID may be used in the GRAM4 protocol for robust reliability in the face of message faults or other transient errors to ensure that at most one instance of a job is executed, i.e. to prevent accidental duplication of jobs under rare circumstances with client retry on failure. The globusrun-ws tool always uses this feature, requiring either a submission ID to be passed in as input or a new unique ID to be created by the tool itself. If a new ID is created, it should be captured by the user who wishes to exploit this reliability interface. The ID in use, whether created or passed as input, will be written to the optional output file when provided, as well as to the standard error output unless the quiet mode is in effect.
If a user is unsure whether a job was submitted successfully, he should resubmit using the same ID as was used for the previous attempt.
- -I, -submission-id ID
If supplied, this option causes the job to be submitted using the given ID in the reliability protocol.
- -If, -submission-id-file filename
If supplied, this option causes the ID to be read from the given file. It is an error to use both mechanisms to provide an input ID.
- -Io, -submission-id-output-file filename
If supplied, the ID in use is written to the given file, whether this ID was provided by the user or given by one of the above input options.
Job EPR output
A successful submission will create a new ManagedJob resource with its own unique EPR for messaging. The globusrun-ws tool will output this EPR to a file when requested and as the sole standard output when running in batch mode. When running in streaming output mode, it is possible that the EPR will not be output and the user's only recourse is to submit again with the same submission ID and job request in order to reattach to the existing job.
- -o, -job-epr-output-file filename
If supplied, the created ManagedJob EPR will be written to the given file following successful submission. The file will not be written if the submission fails.
Delegation
The job description supports the optional identification of delegated credentials for use by the GRAM4 services. These features are passed through globusrun-ws without modification. However, globusrun-ws can also perform delegation and construct these optional request elements before submitting it to the service. The only delegation performed by default (if an endpoint does not already exist) is the multijob level jobCredential.
- -J, -job-delegate
If supplied AND the job description does not already provide a jobCredential element, globusrun-ws will delegate the client credential to GRAM4 and introduce the corresponding element to the submission input.
- -S, -staging-delegate
If supplied AND the job description does include staging or cleanup directives AND the job description does not already provide the necessary stagingCredential or transferCredential element(s), globusrun-ws will delegate the client credential to GRAM4 and RFT, and introduce the corresponding elements to the submission input.
This option is implied by -streaming
- -Jf, -job-credential-file filename:
If supplied AND the job description does not already provide a jobCredential element, globusrun-ws will copy the supplied epr into the job description. This should be an epr returned from the DelegationFactoryService intended for use by the job (or, in the case of a multijob, for authenticating to the subjobs).
note: for multijob descriptions, only the top level jobCredential will be copied into.
- -Sf, -staging-credential-file filename:
If supplied AND the job description does not already provide a stagingCredential element, globusrun-ws will copy the supplied epr into the job description. This should be an epr returned from the DelegationFactoryService intended for use with the RFT service associated with the ManagedJobService.
note: this option is ignored for multijobs.
- -Tf, -transfer-credential-file filename:
If supplied, globusrun-ws will copy the epr into each of the stage in, stage out, and cleanup elements that do not already contain a transferCredential element. This should be an epr returned from the DelegationFactoryService intended for use by RFT to authenticate with the target gridftp server.
note: this option is ignored for multijobs.
Lifetime
The ManagedJob resource supports lifetime management in the form of a scheduled destruction. The default lifetime requested by the client is infinite, subject to server policies.
- -term, -termination mm/dd/yyyy HH:MM
Set an absolute termination time.
- -term, -termination +HH:MM
Set a termination time relative to the successful creation of the job. The default is +24:00
Validate options
- -validate
The -validate command checks the job description for syntax errors and a subset of semantic errors without making any service requests.
Monitor options
- -monitor
The -monitor command attaches to an existing job in interactive or interactive-streaming output modes.
Status options
- -status
The -status command reports the current state of the job and exits. See the External States of the Managed Job Services section of the developer guid for information on valid job states.
See the Job options for the -monitor command.
Job Handling
For every job that globusrun-ws delegates a credential, globusrun will augment the user's job description, adding annotations that will later tell globusrun-ws to destroy the credential after the job has been destroyed. Below are 2 job annotation examples. globusrun-ws only delegated the job cred...
<extensions>
<globusrunAnnotation>
<automaticJobDelegation>true</automaticJobDelegation>
<automaticStagingDelegation>false</automaticStagingDelegation>
<automaticStageInDelegation>false</automaticStageInDelegation>
<automaticStageOutDelegation>false</automaticStageOutDelegation>
<automaticCleanUpDelegation>false</automaticCleanUpDelegation>
</globusrunAnnotation>
</extensions>
globusrun-ws delegated the job, staging and stage in cred...
<extensions>
<globusrunAnnotation>
<automaticJobDelegation>true</automaticJobDelegation>
<automaticStagingDelegation>true</automaticStagingDelegation>
<automaticStageInDelegation>true</automaticStageInDelegation>
<automaticStageOutDelegation>false</automaticStageOutDelegation>
<automaticCleanUpDelegation>false</automaticCleanUpDelegation>
</globusrunAnnotation>
</extensions>
B
- Bloom filter
Compression scheme used by the Replica Location Service (RLS) that is intended to reduce the size of soft state updates between Local Replica Catalogs (LRCs) and Replica Location Index (RLI) servers. A Bloom filter is a bit map that summarizes the contents of a Local Replica Catalog (LRC). An LRC constructs the bit map by applying a series of hash functions to each logical name registered in the LRC and setting the corresponding bits.
C
- Certificate Authority ( CA )
An entity that issues certificates. [fixme - flesh out]
- certificate
A public key plus information about the certificate owner bound together by the digital signature of a CA. In the case of a CA certificate, the certificate is self signed, i.e. it was signed using its own private key.
- client
A process that sends commands and receives responses. Note that in GridFTP, the client may or may not take part in the actual movement of data.
E
- extended block mode (MODE E)
MODE E is a critical GridFTP components because it allows for out of order reception of data. This in turn, means we can send the data down multiple paths and do not need to worry if one of the paths is slower than the others and the data arrives out of order. This enables parallelism and striping within GridFTP. In MODE E, a series of “blocks” are sent over the data channel. Each block consists of:
- an 8 bit flag field,
- a 64 bit field indicating the offset in the transfer,
- and a 64 bit field indicating the length of the payload,
- followed by length bytes of payload.
Note that since the offset and length are included in the block, out of order reception is possible, as long as the receiving side can handle it, either via something like a seek on a file, or via some application level buffering and ordering logic that will wait for the out of order blocks.
F
G
- grid map file
A file containing entries mapping certificate subjects to local user names. This file can also serve as a access control list for GSI enabled services and is typically found in
/etc/grid-security/grid-mapfile. For more information see the Gridmap section here.
J
- job description
Term used to describe a GRAM4 job for GT4.
- job scheduler
See the term scheduler.
L
- Local Replica Catalog (LRC)
Stores mappings between logical names for data items and the target names (often the physical locations) of replicas of those items. Clients query the LRC to discover replicas associated with a logical name. Also may associate attributes with logical or target names. Each LRC periodically sends information about its logical name mappings to one or more RLIs.
See also RLI.
- logical file name
A unique identifier for the contents of a file.
M
- Managed Executable Job Service (MEJS)
[FIXME]
- multijob
A job that is itself composed of several executable jobs; these are processed by the MMJS subjob.
See also MMJS subjob.
P
- physical file name
The address or the location of a copy of a file on a storage system.
- proxy certificate
A short lived certificate issued using a EEC. A proxy certificate typically has the same effective subject as the EEC that issued it and can thus be used in its place. GSI uses proxy certificates for single sign on and delegation of rights to other entities.
For more information about types of proxy certificates and their compatibility in different versions of GT, see http://dev.globus.org/wiki/Security/ProxyCertTypes.
R
- Replica Location Index (RLI)
Collects information about the logical name mappings stored in one or more Local Replica Catalogs (LRCs) and answers queries about those mappings. Each RLI periodically receives updates from one or more LRCs that summarize their contents.
- resource properties
A resource is composed of zero or more resource properties which describe the resource. For example, a resource can have the following three resource properties: Filename, Size, and Descriptors. The resource properties are defined in the web service's WSDL interface description.
- RLS attribute
Descriptive information that may be associated with a logical or target name mapping registered in a Local Replica Catalog (LRC). Clients can query the LRC to discover logical names or target names that have specified RLS attributes.
S
- server
A process that receives commands and sends responses to those commands. Since it is a server or service, and it receives commands, it must be listening on a port somewhere to receive the commands. Both FTP and GridFTP have IANA registered ports. For FTP it is port 21, for GridFTP it is port 2811. This is normally handled via inetd or xinetd on Unix variants. However, it is also possible to implement a daemon that listens on the specified port. This is described more fully in in the Architecture section of the GridFTP Developer's Guide.
- SOAP
SOAP provides a standard, extensible, composable framework for packaging and exchanging XML messages between a service provider and a service requester. SOAP is independent of the underlying transport protocol, but is most commonly carried on HTTP. See the SOAP specifications for details.
- stream mode (MODE S)
The only mode normally implemented for FTP is MODE S. This is simply sending each byte, one after another over the socket in order, with no application level framing of any kind. This is the default and is what a standard FTP server will use. This is also the default for GridFTP.
T
- third party transfers
In the simplest terms, a third party transfer moves a file between two GridFTP servers.
The following is a more detailed, programmatic description.
In a third party transfer, there are three entities involved. The client, who will only orchestrate, but not actually take place in the data transfer, and two servers one of which will be sending data to the other. This scenario is common in Grid applications where you may wish to stage data from a data store somewhere to a supercomputer you have reserved. The commands are quite similar to the client/server transfer. However, now the client must establish two control channels, one to each server. He will then choose one to listen, and send it the PASV command. When it responds with the IP/port it is listening on, the client will send that IP/port as part of the PORT command to the other server. This will cause the second server to connect to the first server, rather than the client. To initiate the actual movement of the data, the client then sends the RETR “filename” command to the server that will read from disk and write to the network (the “sending” server) and will send the STOR “filename” command to the other server which will read from the network and write to the disk (the “receiving” server).
See Also client/server transfer.
- transport-level security
Uses transport-level security (TLS) mechanisms.
U
- user certificate
A EEC belonging to a user. When using GSI, this certificate is typically stored in
$HOME/.globus/usercert.pem. For more information on possible user certificate locations, see this.
W
- Web Services Addressing (WSA)
The WS-Addressing specification defines transport-neutral mechanisms to address web services and messages. Specifically, it defines XML elements to identify web service endpoints and to secure end-to-end endpoint identification in messages. See the W3C WS Addressing Working Group for details.
- Web Services Description Language (WSDL)
WSDL is an XML document for describing Web services. Standardized binding conventions define how to use WSDL in conjunction with SOAP and other messaging substrates. WSDL interfaces can be compiled to generate proxy code that constructs messages and manages communications on behalf of the client application. The proxy automatically maps the XML message structures into native language objects that can be directly manipulated by the application. The proxy frees the developer from having to understand and manipulate XML. See the WSDL 1.1 specification for details.
- Web Services Resource Framework (WSRF)
Web Services Resource Framework (WSRF) is a specification that extends web services for grid applications by giving them the ability to retain state information while at the same time retaining statelessness (using resources). The combination of a web service and a resource is referred to as a WS-Resource. WSRF is a collection of different specifications that manage WS-Resources.
This framework comprises mechanisms to describe views on the state (WS-ResourceProperties), to support management of the state through properties associated with the Web service (WS-ResourceLifetime), to describe how these mechanisms are extensible to groups of Web services (WS-ServiceGroup), and to deal with faults (WS-BaseFaults).
For more information, go to: http://www.globus.org/wsrf/ and OASIS Web Services Notification (WSRF) TC .
X
- XML
Extensible Markup Language (XML) is standard, flexible, and extensible data format used for web services. See the W3C XML site for details.
- XML Path Language (XPath)
XPath is a language for finding information in an XML document. XPath is used to navigate through elements and attributes in an XML document. See the XPath specification for details.