.. _Managing S3 Users:

Managing S3 Users
-----------------

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

You can manage users with the ``ostor-s3-admin`` tool. To do this, you will need to know the ID of the volume that the users 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.

.. _Adding S3 Users:

Adding S3 Users
~~~~~~~~~~~~~~~

You can generate a unique random S3 user ID and an access key pair (S3 Access Key ID, S3 Secret Access Key) using the ``ostor-s3-admin create-user`` command. You need to specify a user email. For example:

::

    # ostor-s3-admin create-user -e user@email.com -V 0100000000000002
    UserEmail:user@email.com
    UserId:a49e12a226bd760f
    KeyPair[0]:S3AccessKeyId:a49e12a226bd760fGHQ7
    KeyPair[0]:S3SecretAccessKey:HSDu2DA00JNGjnRcAhLKfhrvlymzOVdLPsCK2dcq
    Flags:none

S3 user ID is a 16-digit hexadecimal string. The generated access key pair is used to sign requests to the S3 object storage according to the Amazon S3 Signature Version 2 authentication scheme.

.. _Listing S3 Users:

Listing S3 Users
~~~~~~~~~~~~~~~~

You can list all object storage users with the ``ostor-s3-admin query-users`` command. Information for each user can take one or more sequential rows in the table. Additional rows are used to lists S3 access key pairs associated with the user. If the user does not have any active key pairs, minus signs are shown in the corresponding table cells. For example:

::

    # ostor-s3-admin query-users -V 0100000000000002
          S3 USER ID      S3 ACCESS KEY ID              S3 SECRET ACCESS KEY  S3 USER EMAIL
    bf0b3b15eb7c9019  bf0b3b15eb7c9019I36Y                               ***  user2@abc.com
    d866d9d114cc3d20  d866d9d114cc3d20G456                               ***  user1@abc.com
                      d866d9d114cc3d20D8EW                               ***
    e86d1c19e616455                      -                                 -  user3@abc.com

To output the list in XML, use the ``-X`` option; to output secret keys, use the ``-a`` option. For example:

.. only:: latex

   ::

       # ostor-s3-admin query-users -V 0100000000000002 -a -X
       <?xml version="1.0" encoding="UTF-8"?><QueryUsersResult><Users><User><Id>a49e12a226bd760f</Id><Ema
       il>user@email.com</Email><Keys><OwnerId>0000000000000000</OwnerId><KeyPair><S3AccessKeyId>a49e12a2
       26bd760fGHQ7</S3AccessKeyId><S3SecretAccessKey>HSDu2DA00JNGjnRcAhLKfhrvlymzOVdLPsCK2dcq</S3SecretA
       ccessKey></KeyPair></Keys></User><User><Id>d7c53fc1f931661f</Id><Email>user@email.com</Email><Keys
       ><OwnerId>0000000000000000</OwnerId><KeyPair><S3AccessKeyId>d7c53fc1f931661fZLIV</S3AccessKeyId><S
       3SecretAccessKey>JL7gt1OH873zR0Fzv8Oh9ZuA6JtCVnkgV7lET6ET</S3SecretAccessKey></KeyPair></Keys></Us
       er></Users></QueryUsersResult>

.. only:: html

   ::

       # ostor-s3-admin query-users -V 0100000000000002 -a -X
       <?xml version="1.0" encoding="UTF-8"?><QueryUsersResult><Users><User><Id>a49e12a226bd760f</Id><Email>user@email.com</Email><Keys><OwnerId>0000000000000000</OwnerId><KeyPair><S3AccessKeyId>a49e12a226bd760fGHQ7</S3AccessKeyId><S3SecretAccessKey>HSDu2DA00JNGjnRcAhLKfhrvlymzOVdLPsCK2dcq</S3SecretAccessKey></KeyPair></Keys></User><User><Id>d7c53fc1f931661f</Id><Email>user@email.com</Email><Keys><OwnerId>0000000000000000</OwnerId><KeyPair><S3AccessKeyId>d7c53fc1f931661fZLIV</S3AccessKeyId><S3SecretAccessKey>JL7gt1OH873zR0Fzv8Oh9ZuA6JtCVnkgV7lET6ET</S3SecretAccessKey></KeyPair></Keys></User></Users></QueryUsersResult>

.. _Querying S3 User Information:

Querying S3 User Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To display information about the specified user, use the ``ostor-s3-admin query-user-info`` command. You need to specify either the user email (``-e``) or S3 ID (``-i``). For example:

::

    # ostor-s3-admin query-user-info -e user@email.com -V 0100000000000002
    Query user: user id=d866d9d114cc3d20, user email=user@email.com
    Key pair[0]: access key id=d866d9d114cc3d20G456,
    secret access key=5EAne6PLL1jxprouRqq8hmfONMfgrJcOwbowCoTt
    Key pair[1]: access key id=d866d9d114cc3d20D8EW,
    secret access key=83tTsNAuuRyoBBqhxMFqHAC60dhKHtTCCkQe54zu

.. _Disabling S3 Users:

Disabling S3 Users
~~~~~~~~~~~~~~~~~~

You can disable a user with the ``ostor-s3-admin disable-user`` command. You need to specify either the user email (``-e``) or S3 ID (``-i``). For example:

::

   # ostor-s3-admin disable-user -e user@email.com -V 0100000000000002

.. _Deleting S3 Users:

Deleting S3 Users
~~~~~~~~~~~~~~~~~

You can delete existing object storage users with the ``ostor-s3-admin delete-user`` command. Users who own any buckets cannot be deleted, so delete user's buckets first. You need to specify either the user email (``-e``) or S3 ID (``-i``). For example:

::

    # ostor-s3-admin delete-user -i bf0b3b15eb7c9019 -V 0100000000000002
    Deleted user: user id=bf0b3b15eb7c9019

.. _Generating S3 User Access Key Pairs:

Generating S3 User Access Key Pairs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can generate a new access key pair for the specified user with the ``ostor-s3-admin gen-access-key`` command. The maximum of 2 active access key pairs are allowed per user (same as with the Amazon Web Services). You need to specify either the user email (``-e``) or S3 ID (``-i``). For example:

::

    # ostor-s3-admin gen-access-key -e user@email.com -V 0100000000000002
    Generate access key: user id=d866d9d114cc3d20, access key id=d866d9d114cc3d20D8EW,
    secret access key=83tTsNAuuRyoBBqhxMFqHAC60dhKHtTCCkQe54zu

.. note:: It is recommended to periodically revoke old and generate new access key pairs.

.. _Revoking S3 User Access Key Pairs:

Revoking S3 User Access Key Pairs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can revoke the specified access key pair of the specified user with the ``ostor-s3-admin revoke-access-key`` command. You need to specify the access key in the key pair you want to delete as well as  the user email or S3 ID. For example:

::

    # ostor-s3-admin revoke-access-key -e user@email.com -k de86d1c19e616455YIPU -V 0100000000000002
    Revoke access key: user id=de86d1c19e616455, access key id=de86d1c19e616455YIPU