Merge "Add full working example of sharing a container with another user"

doc/source/overview_acl.rst

@@ -249,6 +249,98 @@ However, the request from the user **must** contain the appropriate
     `Referer` header, the referrer ACL has very weak security.
 
 
+Example: Sharing a Container with Another User
+----------------------------------------------
+
+Sharing a Container with another user requires the knowledge of few
+parameters regarding the users.
+
+The sharing user must know:
+
+- the ``OpenStack user id`` of the other user
+
+The sharing user must communicate to the other user:
+
+- the name of the shared container
+- the ``OS_STORAGE_URL``
+
+Usually the ``OS_STORAGE_URL`` is not exposed directly to the user
+because the ``swift client`` by default automatically construct the
+``OS_STORAGE_URL`` based on the User credential.
+
+We assume that in the current directory there are the two client
+environment script for the two users ``sharing.openrc`` and
+``other.openrc``.
+
+The ``sharing.openrc`` should be similar to the following:
+
+.. code-block:: bash
+
+    export OS_USERNAME=sharing
+    # WARNING: Save the password in clear text only for testing purposes
+    export OS_PASSWORD=password
+    export OS_TENANT_NAME=projectName
+    export OS_AUTH_URL=https://identityHost:portNumber/v2.0
+    # The following lines can be omitted
+    export OS_TENANT_ID=tenantIDString
+    export OS_REGION_NAME=regionName
+    export OS_CACERT=/path/to/cacertFile
+
+The ``other.openrc`` should be similar to the following:
+
+.. code-block:: bash
+
+    export OS_USERNAME=other
+    # WARNING: Save the password in clear text only for testing purposes
+    export OS_PASSWORD=otherPassword
+    export OS_TENANT_NAME=otherProjectName
+    export OS_AUTH_URL=https://identityHost:portNumber/v2.0
+    # The following lines can be omitted
+    export OS_TENANT_ID=tenantIDString
+    export OS_REGION_NAME=regionName
+    export OS_CACERT=/path/to/cacertFile
+
+For more information see `using the OpenStack RC file
+<https://docs.openstack.org/user-guide/common/cli-set-environment-variables-using-openstack-rc.html>`_
+
+First we figure out the other user id::
+
+    . other.openrc
+    OUID="$(openstack user show --format json "${OS_USERNAME}" | jq -r .id)"
+
+or alternatively::
+
+    . other.openrc
+    OUID="$(openstack token issue -f json | jq -r .user_id)"
+
+Then we figure out the storage url of the sharing user::
+
+    sharing.openrc
+    SURL="$(swift auth | awk -F = '/OS_STORAGE_URL/ {print $2}')"
+
+Running as the sharing user create a shared container named ``shared``
+in read-only mode with the other user using the proper acl::
+
+    sharing.openrc
+    swift post --read-acl "*:${OUID}" shared
+
+Running as the sharing user create and upload a test file::
+
+    touch void
+    swift upload shared void
+
+Running as the other user list the files in the ``shared`` container::
+
+    other.openrc
+    swift --os-storage-url="${SURL}" list shared
+
+Running as the other user download the ``shared`` container in the
+``/tmp`` directory::
+
+    cd /tmp
+    swift --os-storage-url="${SURL}" download shared
+
+
 .. _account_acls:
 
 ------------