SRM-REQUEST

BeStMan Copyright (c) 2007,2008, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy).� All rights reserved.

If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Technology Transfer Department at [email protected] and [email protected].

NOTICE.� This software was developed under partial funding from the U.S. Department of Energy.� As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, and perform publicly and display publicly.� Beginning five (5) years after the date permission to assert copyright is obtained from the U.S. Department of Energy, and subject to any subsequent five (5) year renewals, the U.S. Government is granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.

For the end user license agreement file for BeStMan for non-commercial research use, go to http://datagrid.lbl.gov/bestman/license-nc.html.

For the end user license agreement file for BeStMan for commercial research use, go to http://datagrid.lbl.gov/bestman/license-c.html.

1 Introduction

SRM client tools are full implementations of SRM v2.2 as generic SRM v2.2 clients, developed by Lawrence Berkeley National Laboratory. They have been tested for all current SRM v2.2 implementations such as BeStMan, CASTOR, dCache, DPM, SRM/iRODS-SRB and StoRM. They are continuously being tested for compatibility and interoperability.

It�s a java implementation that would run on any OS platforms, and currently supports gsiftp, http, https and ftp as its file transfer protocols.

It requires the minimal administrative efforts on the deployment and maintenance.

SRM v2.2 specification can be found on http://sdm.lbl.gov/srm-wg/doc/SRM.v2.2.html.
SRM client downloads and instructions can be found on http://datagrid.lbl.gov/bestman.

2 Requirements

� SUN Java 1.5.0_12 or IBM Java 1.5 or higher versions such as 1.6.0_07.

� Valid user grid proxy

3 Installation

� Refer to SRM Client User�s Guide.

4 Configuration, configuration options, configuration file and notes

� Refer to SRM Client User�s Guide.

5 SRM-REQUEST

srm-request manages request related operations, such as abort, extending lifetimes, suspend and resume.

5.1 Usage

� srm-request� <service_url> [command line options]

� srm-request� <service_url>� -f <input_file> [command line options]

5.2 Options

� Command line options take priority from the options from conf file.

� Options in the following table are in alphabetical order

-abortfiles <request_token>	� Specifies a request to abort files in the request � Used with -s or -f to specify SURLs
-abortrequest <request_token>	� Specifies a request to abort
-authid <string>	� Authorization� ID to be used in SRM for the request
-conf <path>	� Path to the configuration file. � Command line options will override the options from conf file
-connectiontimeout <int>	� Specifies time in seconds to wait for soap or gsi connection before timing out. � Default=1800
-debug	� Specifies debugging output � Default=false
-delegation <true\|false>	� Force proxy delegation. � When not provided, srm client makes no delegation by default, and automatically handles proxy delegation based on the source and target URLs. � When -delegation is provided, it overrides the automatic handling and forces the user choice.
-f <path>	� Path to the xml input file containing the source url, targer url information for requests with more than one file � Refer to the format and an example in 6.3
-getrequesttoken	� Retrieves request tokens that belong to the client
-help	� Show the help message
-lifetime <int>	� File (SURL) lifetime in seconds � Used with �s or �f to specify SURLs
-log <path>	� Specifies path to log file � Default=./srmclient-event-date-random.log
-pinlifetime <int>	� File pin lifetime in seconds � Mostly on TURLs
-proxyfile <path>	� Path to user grid proxy
-quiet	� Suppress output in the console. � This option writes the output to the log file.
-requestsummary <request_token>	� Specifies a request to retrieve request summary
-requesttoken <request_token>	� Specifies a request token
-resume <request_token>	� Specifies a previously suspended request to resume
-s <source_url>	� Source URL
-serviceurl <ws_endpoint>	� Full web service endpoint � Required when source url does not contain web service endpoint information
-suspend <request_token>	� Specifies a request to suspend
-usercert <path>	� Path to user grid certificate
-userdesc <string>	� Specifies user request description
-userkey <path>	� Path to user grid certificate key

5.3 Notes

� srm client makes no proxy delegation by default, and automatically handles proxy delegation based on the source and target urls. A user can override the automatic handling by providing an option �-delegation� (or �-delegation true�) to force the delegation, and �-delegation false� to force no delegation. �-debug� option would show how the delegation is done on the output.

5.4 Input file format

<?xml version="1.0" encoding="UTF-8"?>

� <file>

�� <sourceurl>Source_URL</sourceurl>

� </file>

</request>

� Example 1

<?xml version="1.0" encoding="UTF-8"?>

� <file>

�� <sourceurl>srm://bestman.lbl.gov:8443/srm/v2/server?SFN=/mydir/mypath/myfile</sourceurl>

� </file>

� <file>

�� <sourceurl>srm://bestman.lbl.gov:8443/srm/v2/server?SFN=/mydir/mypath/myfile2</sourceurl>

� </file>

</request>

5.5 Examples

5.5.1 Abort a request

1. srm-request �srm://host:port/wsept �-abortrequest <request_token>
This command requests to abort a request that is specified with the request token. Click here for the sample output.

1.1. srm-request �srm://bestman.lbl.gov:8443/srm/v2/server� \
�� -abortrequest TOKEN_GET_12345

5.5.2 Abort a file in a request

1. srm-request� srm://host:port/wsept \

�� -abortfiles� <request_token> \
�� -s� srm://host:port/wsept\?SFN=/my_file_path

This command requests to abort a file in the re2uest that is specified with the request token. Click here for the sample output.

1.1. srm-request srm://bestman.lbl.gov:8443/srm/v2/server \
�� -abortfiles TOKEN_GET_12345 \
�� -s srm://bestman.lbl.gov:8443/srm/v2/server\?SFN=/srmcache/guest/test.file

5.5.3 extend lifetime of a file in a request

1. srm-request� srm://host:port/wsept \
�� -lifetime <seconds> \
�� -s srm://host:port/wsept\?SFN=/source_filepath

This command requests to extend SURL lifetime. Click here for the sample output.

1.1. srm-request srm://bestman.lbl.gov:8443/srm/v2/server�� \
�� -lifetime 3600 \
�� -s srm://bestman.lbl.gov:8443/srm/v2/server\?SFN=/srmcache/guest/test.data

1.2. srm-request -lifetime 3600 \
�� -s srm://bestman.lbl.gov:8443/srm/v2/server\?SFN=/srmcache/guest/test.data

5.5.4 extend pin lifetime of a file in a request

1. srm-request� srm://host:port/wsept� \
�� -extlifetime <request_token> ��-pinlifetime <seconds> �\
�� -s srm://host:port/wsept?SFN=/source_filepath

This command requests to extend pin lifetime of a file in a request. Click here for the sample output.

1.1. srm-request�� srm://bestman.lbl.gov:8443/srm/v2/server�� \
�� -extlifetime TOKEN_GET_12345 ��-pinlifetime 3600 \
�� -s srm://bestman.lbl.gov:8443/srm/v2/server\?SFN=/srmcache/guest/test.data

1.2. srm-request� -extlifetime TOKEN_GET_12345 -pinlifetime 3600 \
�� -s srm://bestman.lbl.gov:8443/srm/v2/server\?SFN=/srmcache/guest/test.data

5.5.5 Retrieve request summary

1. srm-request� srm://host:port/wsept \

�� -requestsummary <request_token>

This command requests to retrieve the request summary for the request that is specified with the request token. Click here for the sample output.

1.1. srm-request�� srm://bestman.lbl.gov:8443/srm/v2/server�� \
�� -requestsummary TOKEN_GET_12345

5.5.6 Retrieve request tokens

1. srm-request� srm://host:port/wsept� \

�� -getrequesttoken

This command requests to retrieve the request tokens that belong to the client. Click here for the sample output.

1.1. srm-request�� srm://bestman.lbl.gov:8443/srm/v2/server�� \
�� -getrequesttoken

1.2. srm-request�� srm://bestman.lbl.gov:8443/srm/v2/server�� \
�� -getrequesttoken \
�� -userdesc ��my request token�

5.5.7 Suspend a request

1. srm-request� srm://host:port/wsept� \

�� -suspend <request_token>

This command requests to suspend the request. Click here for the sample output.

1.1. srm-request�� srm://bestman.lbl.gov:8443/srm/v2/server�� \
�� -suspend TOKEN_GET_12345

5.5.8 Resume a request

1. srm-request� srm://host:port/wsept� \

�� -resume <request_token>

This command requests to resume a previously suspended request. Click here for the sample output.

1.1. srm-request�� srm://bestman.lbl.gov:8443/srm/v2/server�� \
�� -resume TOKEN_GET_12345

6 Exit codes

When SRM client commands exit, they have exit codes as following:

0	SRM_SUCCESS
51	SRM_FAILURE
52	SRM_AUTHENTICATION_FAILURE
53	SRM_AUTHORIZATION_FAILURE
54	SRM_INVALID_REQUEST
55	SRM_INVALID_PATH
56	SRM_FILE_LIFETIME_EXPIRED
57	SRM_SPACE_LIFETIME_EXPIRED
58	SRM_EXCEED_ALLOCATION
59	SRM_NO_USER_SPACE
60	SRM_NO_FREE_SPACE
61	SRM_DUPLICATION_ERROR
62	SRM_NON_EMPTY_DIRECTORY
63	SRM_TOO_MANY_RESULTS
64	SRM_INTERNAL_ERROR
65	SRM_FATAL_INTERNAL_ERROR
66	SRM_NOT_SUPPORTED
67	SRM_REQUEST_QUEUED
68	SRM_REQUEST_INPROGRESS
69	SRM_REQUEST_SUSPENDED
70	SRM_ABORTED
71	SRM_RELEASED
72	SRM_FILE_PINNED
73	SRM_FILE_IN_CACHE
74	SRM_SPACE_AVAILABLE
75	SRM_LOWER_SPACE_GRANTED
76	SRM_DONE
77	SRM_PARTIAL_SUCCESS
78	SRM_REQUEST_TIMED_OUT
79	SRM_LAST_COPY
80	SRM_FILE_BUSY
81	SRM_FILE_LOST
82	SRM_FILE_UNAVAILABLE
83	SRM_UNKNOWN_ERROR
90	Connection refused
91	GSI mapping not found
92	General unpredictable exception
93	Input error
94	Other error, not reached SRM yet
100	SRM returned no status, but it is a failure

7 Troubleshooting

� When a large request is submitted, the srm-request may not fill all request information into the memory before submitting to the server. It is mostlikely because the memory size of the java virtual machine.� In such case, you can increase the size of the virtual machine in srm-request by -Xmx###M, where # is the amount of memory which you want to allocate in megabytes. E.g. java �Xmx512M

� For memory conscious jobs, �-lite� option is provided to use less memory to handle the user request. The option the passes -Xms32M to the virtual machine.

8 See Also

srm-copy, srm-request