.. -*- rst -*-
=============
Share actions
=============
Grants or revokes share access, lists the permissions for a share,
and explicitly updates the state of a share.
To grant or revoke share access, specify one of these supported
share access levels:
- ``rw``. Read and write (RW) access.
- ``ro``. Read-only (RO) access.
You must also specify one of these supported authentication
methods:
- ``ip``. Authenticates an instance through its IP address. A valid
format is ``XX.XX.XX.XX`` or ``XX.XX.XX.XX/XX``. For example
``0.0.0.0/0``.
- ``cert``. Authenticates an instance through a TLS certificate.
Specify the TLS identity as the IDENTKEY. A valid value is any
string up to 64 characters long in the common name (CN) of the
certificate. The meaning of a string depends on its
interpretation.
- ``user``. Authenticates by a user or group name. A valid value is
an alphanumeric string that can contain some special characters
and is from 4 to 32 characters long.
To verify that the access rules (ACL) were configured correctly for
a share, you list permissions for a share.
As administrator, you can reset the state of a share and force-
delete a share in any state. Use the ``policy.json`` file to grant
permissions for this action to other roles.
You can set the state of a share to one of these supported states:
- ``available``
- ``error``
- ``creating``
- ``deleting``
- ``error_deleting``
If API version 1.0-2.6 is used then all share actions, defined
below, should include prefix ``os-`` in top element of request
JSON's body.
For example: {"access_list": null} is valid for v2.7+. And {"os-
access_list": null} is valid for v1.0-2.6
Grant access
============
.. rest_method:: POST /v2/{tenant_id}/shares/{share_id}/action
Grants access to a share.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- allow_access: allow_access
- access_level: access_level
- access_type: access_type
- access_to: access_to
- share_id: share_id
- tenant_id: tenant_id_1
Request example
---------------
.. literalinclude:: samples/share-actions-grant-access-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- share_id: share_id_7
- created_at: created_at_6
- updated_at: updated_at_3
- access_type: access_type_2
- access_to: access_to_1
- access_key: access_key
- access: access
- access_level: access_level_2
- id: id_7
Response example
----------------
.. literalinclude:: samples/share-actions-grant-access-response.json
:language: javascript
Revoke access
=============
.. rest_method:: POST /v2/{tenant_id}/shares/{share_id}/action
Revokes access from a share.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- deny_access: deny_access
- access_id: access_id
- share_id: share_id
- tenant_id: tenant_id_1
Request example
---------------
.. literalinclude:: samples/share-actions-revoke-access-request.json
:language: javascript
List access rules
=================
.. rest_method:: POST /v2/{tenant_id}/shares/{share_id}/action
Lists access rules for a share.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- access_list: access_list
- share_id: share_id
- tenant_id: tenant_id_1
Request example
---------------
.. literalinclude:: samples/share-actions-list-access-rules-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- access_type: access_type_1
- access_key: access_key
- access_to: access_to_1
- access_level: access_level
- state: state
- access_list: access_list
- id: id_8
Response example
----------------
.. literalinclude:: samples/share-actions-list-access-rules-response.json
:language: javascript
Reset share state
=================
.. rest_method:: POST /v2/{tenant_id}/shares/{share_id}/action
Administrator only. Explicitly updates the state of a share.
Use the ``policy.json`` file to grant permissions for this action
to other roles.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- reset_status: reset_status
- status: status_11
- share_id: share_id
- tenant_id: tenant_id_1
Request example
---------------
.. literalinclude:: samples/share-actions-reset-state-request.json
:language: javascript
Force-delete share
==================
.. rest_method:: POST /v2/{tenant_id}/shares/{share_id}/action
Administrator only. Force-deletes a share in any state.
Use the ``policy.json`` file to grant permissions for this action
to other roles.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- force_delete: force_delete
- share_id: share_id
- tenant_id: tenant_id_1
Request example
---------------
.. literalinclude:: samples/share-actions-force-delete-request.json
:language: javascript
Extend share
============
.. rest_method:: POST /v2/{tenant_id}/shares/{share_id}/action
Increases the size of a share.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- extend: extend
- new_size: new_size
- share_id: share_id
- tenant_id: tenant_id_1
Request example
---------------
.. literalinclude:: samples/share-actions-extend-request.json
:language: javascript
Shrink share
============
.. rest_method:: POST /v2/{tenant_id}/shares/{share_id}/action
Shrinks the size of a share.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- shrink: shrink
- new_size: new_size
- share_id: share_id
- tenant_id: tenant_id_1
Request example
---------------
.. literalinclude:: samples/share-actions-shrink-request.json
:language: javascript
Unmanage share
==============
.. rest_method:: POST /v2/{tenant_id}/shares/{share_id}/action
This API is available in versions later than or equal to 2.7
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- unmanage: unmanage
- share_id: share_id
- tenant_id: tenant_id_1
Request example
---------------
.. literalinclude:: samples/share-actions-unmanage-request.json
:language: javascript