.. _Managing S3 Buckets:

Managing S3 Buckets
-------------------

.. include:: /includes/exporting-data-via-s3-part13.inc

You can manage buckets with the ``ostor-s3-admin`` tool as well as S3 API third-party S3 browsers like CyberDuck or DragonDisk. To manage buckets via CLI, you will need to know the ID of the volume that the buckets are in. You can obtain it with the ``ostor-ctl get-config`` command. For example:

::

   # ostor-ctl get-config -n 10.94.97.195
   VOL_ID             TYPE     STATE
   0100000000000002   OBJ     READY
   ...

.. note:: As ``ostor-s3-admin`` commands are assumed to be issued by object storage administrators, they do not include any authentication or authorization checks.

.. _Listing S3 Bucket Contents:

Listing S3 Bucket Contents
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/exporting-data-via-s3-part14.inc

.. _Listing S3 Storage Buckets:

Listing S3 Storage Buckets
~~~~~~~~~~~~~~~~~~~~~~~~~~

You can list all buckets in the S3 object storage with the ``ostor-s3-admin list-all-buckets`` command. For each bucket, the command shows owner, creation data, versioning status, and total size (the size of all objects stored in the bucket plus the size of all unfinished multipart uploads for this bucket). For example:

::

   # ostor-s3-admin list-all-buckets -V 0100000000000002
   Total 3 buckets
   BUCKET                OWNER             CREATION_DATE  VERSIONING     TOTAL SIZE, BYTES
   bucket1    968d1a79968d1a79  2015-08-18T09:32:35.000Z        none                  1024
   bucket2    968d1a79968d1a79  2015-08-18T09:18:20.000Z     enabled                     0
   bucket3    968d1a79968d1a79  2015-08-18T09:22:15.000Z   suspended               1024000

To output the list in XML, use the ``-X`` option. For example:

.. only:: latex

   ::

       # ostor-s3-admin list-all-buckets -X
       <?xml version="1.0" encoding="UTF-8"?><ListBucketsResult><Buckets><Bucket><Name>bucker2</Name><Own
       er>d7c53fc1f931661f</Owner><CreationDate>2017-04-03T17:11:44.000Z</CreationDate><Versioning>none</
       Versioning><Notary>off</Notary><TotalSize>0</TotalSize></Bucket><Bucket><Name>bucket1</Name><Owner
       >d7c53fc1f931661f</Owner><CreationDate>2017-04-03T17:11:33.000Z</CreationDate><Versioning>none</Ve
       rsioning><Notary>off</Notary><TotalSize>0</TotalSize></Bucket></Buckets></ListBucketsResult>

.. only:: html

   ::

       # ostor-s3-admin list-all-buckets -X
       <?xml version="1.0" encoding="UTF-8"?><ListBucketsResult><Buckets><Bucket><Name>bucker2</Name><Owner>d7c53fc1f931661f</Owner><CreationDate>2017-04-03T17:11:44.000Z</CreationDate><Versioning>none</Versioning><Notary>off</Notary><TotalSize>0</TotalSize></Bucket><Bucket><Name>bucket1</Name><Owner>d7c53fc1f931661f</Owner><CreationDate>2017-04-03T17:11:33.000Z</CreationDate><Versioning>none</Versioning><Notary>off</Notary><TotalSize>0</TotalSize></Bucket></Buckets></ListBucketsResult>

To filter buckets by user who owns them, use the ``-i`` option. For example:

::

   # ostor-s3-admin list-all-buckets -i d7c53fc1f931661f
   BUCKET   OWNER             CREATION_DATE             VERSIONING  TOTAL_SIZE NOTARY NOTARY_PROVIDER
   bucker2  d7c53fc1f931661f  2017-04-03T17:11:44.000Z  none        0          off    0

.. _Querying S3 Bucket Information:

Querying S3 Bucket Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can query bucket metadata information and ACL with the ``ostor-s3-admin query-bucket-info`` command. For example, for ``bucket1``:

::

   # ostor-s3-admin query-bucket-info -b bucket1 -V 0100000000000002
   BUCKET   OWNER             CREATION_DATE             VERSIONING  TOTAL_SIZE
   bucket1  d339edcf885eeafc  2017-12-21T12:42:46.000Z  none        0
   
   ACL: d339edcf885eeafc: FULL_CONTROL

.. _Changing S3 Bucket Owners:

Changing S3 Bucket Owners
~~~~~~~~~~~~~~~~~~~~~~~~~

You can pass ownership of a bucket to the specified user with the ``ostor-s3-admin change-bucket-owner`` command. For example, to make user with ID ``bf0b3b15eb7c9019`` the owner of ``bucket1``:

::

   # ostor-s3-admin change-bucket-owner -b bucket1 -i bf0b3b15eb7c9019 -V 0100000000000002
   Changed owner of the bucket bucket1. New owner bf0b3b15eb7c9019

.. _Deleting S3 Buckets:

Deleting S3 Buckets
~~~~~~~~~~~~~~~~~~~

You can delete the specified bucket with the ``ostor-s3-admin delete-bucket`` command. Deleting a bucket will delete all objects in it (including their old versions) as well as all unfinished multipart uploads for this bucket For example:

::

   # ostor-s3-admin delete-bucket -b bucket1 -V 0100000000000002
   Deleted bucket bucket1