edit

S3-API Related Operations

Prior Knowledge

When choosing Amazon S3 API1 as LeoGateway's protocol, you need LeoFS' S3-API related operations including Endpoint, User, and Bucket operations.

You can access a LeoFS system whose LeoGateway's protocol is S3-API by following the flow.

  1. Create an endpoint to be able to access a LeoFS system's resources.
  2. Create a user to separately manage the user's buckets and objects.
  3. After creating a bucket, If you need to change ACL of a bucket, you can set it as an administrator of a LeoFS system. The current version, v1.3 of LeoFS does not support

Operations

Endpoint

You can continue to use a LeoFS system's DNS name to access its resources after you've set up an endpoint, which has a policy that controls the use of the endpoint to access the resources.

Create an endpoint, add-endpoint

Creates an endpoint so users can access a LeoFS system's resources.

1
2
3
4
5
$ leofs-adm add-endpoint <endpoint>

## Example
$ leofs-adm add-endpoint leo-project.net
OK

Remove an endpoint, delete-endpoint

Removes an endpoint if a LeoFS system's system does not need it.

1
2
3
4
5
$ leofs-adm delete-endpoint <endpoint>

## Example
$ leofs-adm delete-endpoint leo-project.net
OK

Retrieve a list of endpoints, get-endpoints

Retrieves a list of the endpoints if you need to know the existing endpoints.

1
2
3
4
5
6
7
8
9
$ leofs-adm get-endpoints

## Example
$ leofs-adm get-endpoints
endpoint         | created at
-----------------+---------------------------
leo-project.net  | 2017-04-07 10:07:31 +0900
localhost        | 2017-04-07 10:06:18 +0900
s3.amazonaws.com | 2017-04-07 10:06:18 +0900

User

To access a LeoFS system, its system's users need to create an account and retrieve AccessKeyID and SecretAccessKey.

Create a user, create-user

Creates a user's account so its user can access a LeoFS system.

1
2
3
4
5
6
$ leofs-adm create-user <user-id> <password>

## Example
$ leofs-adm create-user leofs-user-1 PASSWORD
access-key-id: b5f0413d45855fcc055e
secret-access-key: b74f9ae91dd0de81f71e19f8d455a7c081f34c57

Remove a user, delete-user

Removes a user account if a LeoFS system does not need it.

1
2
3
4
5
$ leofs-adm delete-user <user-id>

## Example
$ leofs-adm delete-user leofs-user-1
OK

Retrieve a list of users, get-users

Retrieves a list of the users if you need to know the existing users.

1
2
3
4
5
6
7
8
$ leofs-adm get-users

## Example
$ leofs-adm get-users
user_id      | role_id | access_key_id          | created_at
-------------+---------+------------------------+---------------------------
_test_leofs  | 9       | 05236                  | 2017-04-10 09:52:39 +0900
leofs-user-2 | 1       | b5f0413d45855fcc055e   | 2017-04-10 09:54:35 +0900

Change role of a user, update-user-role

Updates a user's role if you need to change the role of a LeoFS system. You can choose a role from Administrator or General user.

Role Id Description
1 Administrator
9 General User
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
$ leofs-adm update-user-role <user-id> <role-id>

## Example
$ leofs-adm update-user-role leofs-user-2 9
OK

## Confirm the latest list of the users
$ leofs-adm get-users
user_id      | role_id | access_key_id          | created_at
-------------+---------+------------------------+---------------------------
_test_leofs  | 9       | 05236                  | 2017-04-10 09:52:39 +0900
leofs-user   | 1       | 3c1d889cdd2088fb9482   | 2017-04-10 09:53:33 +0900
leofs-user-2 | 9       | b5f0413d45855fcc055e   | 2017-04-10 09:54:35 +0900

Bucket

To manage objects under a bucket, you need to create a bucket with leofs-adm or any client for Amazon S3 such as s3cmd2 and DragonDisk3.

Create a bucket, add-bucket

Creates a bucket so a LeoFS system' users can manage resources under its bucket.

1
2
3
4
5
$ leofs-adm add-bucket <bucket-name> <access-key-id>

## Example
$ leofs-adm add-bucket backup 05236
OK

Remove a bucket, delete-bucket

Removes a bucket if its user does not need it.

1
2
3
4
5
$ leofs-adm delete-bucket <bucket-name> <access-key-id>

## Example
$ leofs-adm delete-bucket backup 05236
OK

Retrieve a list of buckets, get-buckets

Retrieves a list of the buckets if you need to know the existing buckets.

1
2
3
4
5
6
7
$ leofs-adm get-buckets

## Example
$ leofs-adm get-buckets
cluster id   | bucket   | owner       | permissions      | redundancy method            | created at
-------------+----------+-------------+------------------+------------------------------+---------------------------
leofs_1      | test     | _test_leofs | Me(full_control) | copy, {n:1, w:1, r:1, d:1}   | 2017-04-10 10:57:29 +0900

Retrieve a bucket, get-bucket

Retrieves a bucket if you need to know its bucket's information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$ leofs-adm get-bucket <access-key-id>

## Example
$ leofs-adm get-bucket 05236
bucket   | permissions                            | created at
---------+----------------------------------------+---------------------------
backup   | Me(full_control), Everyone(read)       | 2017-04-10 10:39:01 +0900
docs     | Me(full_control), Everyone(read)       | 2017-04-10 10:39:25 +0900
logs     | Me(full_control), Everyone(read,write) | 2017-04-10 10:39:38 +0900
movie    | Me(full_control)                       | 2017-04-10 10:39:45 +0900

Change an owner of a bucket, chown-bucket

Updates an owner of a bucket if you need to change its owner to someone else.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
$ leofs-adm chown-bucket <bucket> <access-key-id>

## Example
$ leofs-adm chown-bucket test b5f0413d45855fcc055e
OK

## Confirm the latest list of the buckets
$ leofs-adm get-buckets
cluster id   | bucket   | owner        | permissions      | redundancy method            | created at
-------------+----------+--------------+------------------+------------------------------+---------------------------
leofs_1      | test     | leofs-user-2 | Me(full_control) | copy, {n:1, w:1, r:1, d:1}   | 2017-04-10 10:57:29 +0900

Update ACL of a bucket, update-acl

Updates ACL of a bucket if you need to change it.

1
2
3
4
5
6
7
8
9
$ leofs-adm update-acl <bucket> <access-key-id> <canned-ACL>

## Example
$ leofs-adm update-acl test 05236 private
ok
$ leofs-adm update-acl test 05236 public-read
ok
$ leofs-adm update-acl test 05236 public-read-write
ok
Canned ACL

When using S3-API, LeoFS supports a set of predefined grants, known as canned ACLs. Each canned ACL has a predefined a set of grantees and permissions. The following table lists the set of canned ACLs and the associated predefined grants.

Canned ACL Applies To Permissions Added To ACL
private Bucket and object [default] Owner gets FULL_CONTROL. No one else has access rights.
public-read Bucket and object Owner gets FULL_CONTROL. The AllUsers group gets READ access.
public-read-write Bucket and object Owner gets FULL_CONTROL. The AllUsers group gets READ and WRITE access. Granting this on a bucket is generally not recommended.