Supported by the National Science Foundation Collaborator: University of Michigan Collaborator: Michigan State University Collaborator: Wayne State University Collaborator: Indiana University

The S3 protocol is best known from Amazon S3 services. This is a well established ecosystem with many compatible clients. S3 is based on simple http operations such as GET / PUT / HEAD / DELETE.

The OSiRIS S3 endpoint is:
https://rgw.osris.org

This is actually a DNS pointer to S3 gateways located at all of the OSiRIS sites. It is best to use this URL.

Some of our users may only be able to reach the S3 endpoint located on their campus (typically private compute cluster users).

Campus specific endpoints are:
https://rgw-um.osris.org
https://rgw-wsu.osris.org
https://rgw-msu.osris.org

These are also DNS pointers but limited to specific campuses. Please do not use the hostnames or IP addresses that those pointers resolve to. You will have SSL certificate verification issues.

Obtaining an access token

Once you have been enrolled into OSiRIS you can retrieve an access token for S3 access from comanage

From the COmanage ‘person menu’ on the upper-right part of the screen click ‘OSiRIS Tokens’:

COmanage token menu

Initially the token will not exist, you must click the “Generate Token” button to generate the token:

COmanage tokens before being generated
COmanage token screen after generating S3 token

The CephRgwToken access token string should be used for the access key in your S3 client, leaving secret key field blank. If your client does not accept an empty secret key any value is fine - it is ignored.

For example, in python boto3 this token goes into the credential argument aws_access_key_id. The aws_secret_access_key is blank/ignored. This argument might be specified in the boto.client function or a credential file on your host. More information for that particular client is in their documentation.

S3 Bucket ACL

When you create new buckets they will be associated with your identity. Other users cannot see them. You must set bucket ACLs to allow other users.

S3 users in OSiRIS are identified by cou and uid identifier all lowercase. On the service token page you will note that each token says “S3 Access key for YourOrg COU (yourname_yourorg)”. Therefore ‘yourname_yourorg’ is the S3 user to be used to grant access via S3 ACL configuration. You may potentially be in several OSiRIS COU and each will have a different S3 identifier for you.

COmanage S3 user

The examples below include information on how to set a bucket ACL using various clients.

Examples

A common S3 client library is python Boto. We’ve assembled some Python Boto examples and sample scripts.

You can access S3 storage from a command line using the s3cmd utility.

You can access S3 storage from a GUI using Cyberduck.

There are many other clients and we do not endorse or prefer you to use any one specifically. The expectation is that Ceph S3 is fully compatible with any S3 client though it may not support all the same functionality as Amazon S3. The Ceph docs should cover what is supported, and common data upload/retrieval operations will have no issues.

** Please note that with any client you will have to specify one of the OSiRIS S3 URLS noted above when creating your S3 connections. Clients often default to Amazon’s configuration. **

Information Resources

More information about the Ceph S3 API and available clients is available at ceph.com.

The Boto examples at ceph.com as well as our examples refer to boto2 but you may be using the most current boto3. Links for both are below:

S3 Docs for Boto3

S3 Docs for Boto2

Further docs on CLI s3cmd.

Further docs on Cyberduck.