rest_libsam - StorageTek QFS and Oracle HSM RESTful Application Programmer Interface (API) routines
https:∕∕server:port∕v0∕function?path=path[[&ops=op[, op …]]operation-list]
SUNWqfs
SUNWsamfs
Oracle HSM rest_libsam is a representational state
transfer (REST) API, a lightweight mechanism that lets
application programs access files in StorageTek QFS file
systems and control Oracle HSM operations over an
authenticated HTTPS connection. The rest_libsam API
is implemented on top of the existing libsam library
and supports a subset of the libsam functions.
rest_libsam WorksTo call an API function, an application addresses an HTTPS POST request to the URL of a REST server running on the Oracle HSM∕StorageTek QFS file system's metadata server host.
The REST server then calls the corresponding function in the
libsam library. The library software performs the
requested operation on the QFS file system and returns the
result to the REST server.
The REST server then passes the result of the libsam
library call to the application as a JavaScript Object
Notation (JSON) data object. For details, see the section
UNDERSTANDING rest-libsam JSON RESPONSES below.
rest_libsam Differs from libsamrpcThe rest-libsam API differs from the libsam
remote procedure call API in a couple of key respects:
The libsam library handles function calls by requesting
services from the local host operating system. Requests are
handled one at a time.
The rest-libsam library handles function calls by posting
requests to the Uniform Resource Locator (URL) of an HTTPS server
running on the QFS file-system server host. Multiple requests can
be processed in parallel.
rest_libsam Handles AuthenticationThe REST server authenticates API clients using basic AUTH over HTTPS and either of two types of backend authentication:
LDAP authentication
static username and password-file authentication.
The rest-libsam library resides in the subdirectory
∕opt∕SUNWsamfs∕lib∕util.
The rest-libsam API supports a subset of the library calls
supported by libsam, as shown in the list below. Optional
query parameter arguments are delimited by square brackets
([argument]). All other arguments are required:
sam_archiveSets archive attributes on a file.
Availability: Oracle HSM environments.
Calling Syntax:
https:∕∕server:port∕v0∕sam_archive?path=path[[&ops=op[, op …]]operation-list]
sam_cancelstageCancels a pending or in-progress stage on a file.
Availability: Oracle HSM environments.
Calling Syntax:
https:∕∕server:port∕v0∕sam_cancelstage?path=path
sam_releaseReleases and sets release attributes on a file.
Availability: Oracle HSM environments.
Calling Syntax:
https:∕∕server:port∕v0∕sam_release?path=path[[&ops=op[, op …]]operation-list]
sam_ssumSets checksum attributes on a file.
Availability: Oracle HSM environments.
Calling Syntax:
https:∕∕server:port∕v0∕sam_ssum?path=path[[&ops=op[, op …]]operation-list]
sam_stageStages and sets stage attributes on a file.
Availability: Oracle HSM environments.
Calling Syntax:
https:∕∕server:port∕v0∕sam_stage?path=path[[&ops=op[, op …]]operation-list]
sam_statObtains file information and follows symbolic links to the file.
Availability: StorageTek QFS and Oracle HSM environments.
Calling Syntax:
https:∕∕server:port∕v0∕sam_stat?path=path
sam_getdigestGets message-digest hash value for a file.
Availability: Oracle HSM environments.
Calling Syntax:
https:∕∕server:port∕v0∕sam_getdigest?path=path
For more details, see man the pages for individual library
routines in section 3 of the online man pages. These man
pages are listed in the SEE ALSO section of this page.
Before you can use the rest-libsam service, you must
install it, configure it, and enable it.
To install rest-libsam webservice, proceed as follows:
1.
Log in to the Oracle HSM metadata server as root.
Change to the ∕opt∕SUNWsamfs∕util∕rest-libsam subdirectory.
Create SSL certificates for the HTTPS protocol. Run the
script install.sh.
Configure the service following installation and prior to
starting the service. Proceed as follows:
1.
Log in to the Oracle HSM metadata server as root.
Install any packages that are prerequisites for your configuration.
In the example, we install the package required for LDAP authentication:
root@mds:~# pkg install python-ldap
Change to the ∕opt∕SUNWsamfs∕util∕rest-libsam
subdirectory.
Enter the command python libsam.py --config
On-screen prompts lead you through the rest of the configuration process.
In the examples below, we select an authentication method by entering the number corresponding to our required method.
In the first example, we enter [1] for LDAP and supply information as prompted:
Please choose an authentication type: LDAP[1] or username∕password file[2]: 1 Original rest-libsam config: ldaps_url is 'ldaps:∕∕example_server:636' Do you want to overwrite (y∕N): y Enter a ldaps complete url, including ldaps:∕∕server:port_num: ldaps:∕∕example_server:636 Original rest-libsam config: ldaps search component is 'cn' Do you want to overwrite (y∕N): y Enter a ldaps search component, for example cn: uid Original rest-libsam config: Ldap admin user dn is 'cn=example_user,ou=adminusers,dc=example,dc=com' Do you want to overwrite (y∕N): y Please Enter a ldap admin user dn: cn=example_user,ou=adminusers,dc=example,dc=com Please Enter a Password: Please Enter a ldap base dn: dc=example,dc=com ldap connection successful Update config successfully
In the second example, we enter [2] for local password authentication:
Please choose an authentication type: LDAP[1] or username∕password file[2]: 2 Please Enter a User Name: test Please Enter a Password: Update config successfully
Log in to the Oracle HSM metadata server as root.
Enter the command ∕sbin∕svcadm enable rest-libsam
To disable and, if desired, uninstall the rest-libsam service,
follow the instructions below.
Log in to the Oracle HSM metadata server as root.
Enter the command ∕sbin∕svcadm disable rest-libsam.
To uninstall rest-libsam service, proceed as follows:
Log in to the Oracle HSM metadata server as root.
Change to the ∕opt∕SUNWsamfs∕util∕rest-libsam subdirectory.
Run the script uninstall.sh.
Successful rest-libsam function calls return status 200.
Unsuccessful calls return errno, errmsg and stderr
in JSON types.
The first example shows a JSON response for a successful call that returns status 200:
{ "st_ctime": 1459552924,
"rperiod_start_time": 0,
"stripe_width": 2,
"creation_time": 1459537622,
"st_ino": 2265,
"admin_id": 0,
"cs_algo": 4,
"partial_size": 0,
"residence_time": 1461090890,
"st_mtime": 1459537622,
"segment_number": 0,
"st_size": 4096957,
"stripe_group": 0,
"segment_size": 0,
"st_atime": 1460665122,
"st_blocks": 0,
"st_nlink": 1,
"projid": 1,
"st_gid": 0,
"allocahead": 0,
"st_dev": 323133294738669568,
"obj_depth": 0,
"st_mode": 33188,
"copy": [{
"media": "dk",
"offset": 67045,
"creation_time": 1461090833,
"flags": 128,
"n_vsns": 1,
"position": 267,
"vsn": "diskvol001"
}],
"gen": 1,
"cs_val": [0, 0],
"rperiod_duration": 0,
"stage_ahead": 0,
"attr": 101632,
"rdev": 0,
"flags": 0,
"old_attr": 101632,
"st_uid": 0,
"attribute_time": 1459537622
}
The second example shows a JSON response for an unsuccessful call that returns something other than status 200:
{
"errno": 65061,
"errmsg": "File is offline"
}
