openstack/openstack-manuals
Code Issues Proposed changes

Migration of swift sections to RST

Browse Source 
DocBook to RST conversion of following sections:
- create containers
- manage access
- manage objects
- environment vars
- object versions
- serialized response formats
- large lists
- hierarchical folders
- discoverability
- large objects
- archive auto extract
- bulk delete
- static websites

The content is split from one large file into several smaller ones.

Change-Id: I17e67387a0fc5645539fcf1d3fe2d0d2859add6e
This commit is contained in:
Erik Wilson
2015-03-17 14:26:28 -05:00
committed by Andreas Jaeger
parent 69c6aee4e6
commit f898fa50da
16 changed files with 1436 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/playground-user-guide/source/cli.rst
View File

@@ -96,3 +96,4 @@ service with its package name and description.
nova_cli_manage_projects_security.rst
cli_manage_services.rst
cli_nova_migrate.rst
managing-openstack-object-storage-with-swift-cli.rst

132
doc/playground-user-guide/source/cli_swift_archive_auto_extract.rst Normal file
View File

@@ -0,0 +1,132 @@
.. _archive-auto-extract:
==========================
Auto-extract archive files
==========================
To discover whether your Object Storage system supports this feature,
see :ref:`discoverability`. Alternatively, check with your service
provider.
Use the auto-extract archive feature to upload a tar archive file.
The Object Storage system extracts files from the archive file and
creates an object.
Auto-extract archive request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To upload an archive file, make a ``PUT`` request. Add the
``extract-archive=format`` query parameter to indicate that you are
uploading a tar archive file instead of normal content.
Valid values for the ``format`` variable are ``tar``, ``tar.gz``, or
``tar.bz2``.
The path you specify in the ``PUT`` request is used for the location of
the object and the prefix for the resulting object names.
In the ``PUT`` request, you can specify the path for:
- An account
- Optionally, a specific container
- Optionally, a specific object prefix
For example, if the first object in the tar archive is
``/home/file1.txt`` and you specify the
``/v1/12345678912345/mybackup/castor/`` path, the operation creates the
``castor/home/file1.txt`` object in the ``mybackup`` container in the
``12345678912345`` account.
Create an archive for auto-extract
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You must use the tar utility to create the tar archive file.
You can upload regular files but you cannot upload other items (for
example, empty directories or symbolic links).
You must UTF-8-encode the member names.
The archive auto-extract feature supports these formats:
- The POSIX.1-1988 Ustar format.
- The GNU tar format. Includes the long name, long link, and sparse
extensions.
- The POSIX.1-2001 pax format.
Use gzip or bzip2 to compress the archive.
Use the ``extract-archive`` query parameter to specify the format.
Valid values for this parameter are ``tar``, ``tar.gz``, or
``tar.bz2``.
Auto-extract archive response
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When Object Storage processes the request, it performs multiple
sub-operations. Even if all sub-operations fail, the operation returns a
201 ``Created`` status. Some sub-operations might succeed while others
fail. Examine the response body to determine the results of each
auto-extract archive sub-operation.
You can set the ``Accept`` request header to one of these values to
define the response format:
``text/plain``
Formats response as plain text. If you omit the ``Accept`` header,
``text/plain`` is the default.
``application/json``
Formats response as JSON.
``application/xml``
Formats response as XML.
``text/xml``
Formats response as XML.
The following auto-extract archive files example shows a ``text/plain``
response body where no failures occurred:
.. code::
Number Files Created: 10
Errors:
The following auto-extract archive files example shows a ``text/plain``
response where some failures occurred. In this example, the Object
Storage system is configured to reject certain character strings so that
the 400 Bad Request error occurs for any objects that use the restricted
strings.
.. code::
Number Files Created: 8
Errors:
/v1/12345678912345/mycontainer/home/xx%3Cyy, 400 Bad Request
/v1/12345678912345/mycontainer/../image.gif, 400 Bad Request
The following example shows the failure response in ``application/json``
format.
.. code::
{
"Number Files Created":1,
"Errors":[
[
"/v1/12345678912345/mycontainer/home/xx%3Cyy",
"400 Bad Request"
],
[
"/v1/12345678912345/mycontainer/../image.gif",
"400 Bad Request"
]
]
}

93
doc/playground-user-guide/source/cli_swift_bulk_delete.rst Normal file
View File

@@ -0,0 +1,93 @@
.. _bulk-delete:
===========
Bulk delete
===========
To discover whether your Object Storage system supports this feature,
see :ref:`discoverability`. Alternatively, check with your service provider.
With bulk delete, you can delete up to 10,000 objects or containers
(configurable) in one request.
Bulk delete request
~~~~~~~~~~~~~~~~~~~
To perform a bulk delete operation, add the ``bulk-delete`` query
parameter to the path of a ``POST`` or ``DELETE`` operation.
.. note:
The ``DELETE`` operation is supported for backwards compatibility.
The path is the account, such as ``/v1/12345678912345``, that contains
the objects and containers.
In the request body of the ``POST`` or ``DELETE`` operation, list the
objects or containers to be deleted. Separate each name with a newline
character. You can include a maximum of 10,000 items (configurable) in
the list.
In addition, you must:
- UTF-8-encode and then URL-encode the names.
- To indicate an object, specify the container and object name as:
``CONTAINER_NAME``/``OBJECT_NAME``.
- To indicate a container, specify the container name as:
``CONTAINER_NAME``. Make sure that the container is empty. If it
contains objects, Object Storage cannot delete the container.
- Set the ``Content-Type`` request header to ``text/plain``.
Bulk delete response
~~~~~~~~~~~~~~~~~~~~
When Object Storage processes the request, it performs multiple
sub-operations. Even if all sub-operations fail, the operation returns a
200 status. The bulk operation returns a response body that contains
details that indicate which sub-operations have succeeded and failed.
Some sub-operations might succeed while others fail. Examine the
response body to determine the results of each delete sub-operation.
You can set the ``Accept`` request header to one of the following values
to define the response format:
``text/plain``
Formats response as plain text. If you omit the
``Accept`` header, ``text/plain`` is the default.
``application/json``
Formats response as JSON.
``application/xml`` or ``text/xml``
Formats response as XML.
The response body contains the following information:
- The number of files actually deleted.
- The number of not found objects.
- Errors. A list of object names and associated error statuses for the
objects that failed to delete. The format depends on the value that
you set in the ``Accept`` header.
The following bulk delete response is in ``application/xml`` format. In
this example, the ``mycontainer`` container is not empty, so it cannot
be deleted.
.. code::
<delete>
<number_deleted>2</number_deleted>
<number_not_found>4</number_not_found>
<errors>
<object>
<name>/v1/12345678912345/mycontainer</name>
<status>409 Conflict</status>
</object>
</errors>
</delete>

53
doc/playground-user-guide/source/cli_swift_create_containers.rst Normal file
View File

@@ -0,0 +1,53 @@
============================
Create and manage containers
============================
- To create a container, run the following command and replace
``CONTAINER`` with the name of your container.
.. code::
$ swift post CONTAINER
- To list all containers, run the following command:
.. code::
$ swift list
- To check the status of containers, run the following command:
.. code::
$ swift stat
.. code::
Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
Containers: 2
Objects: 3
Bytes: 268826
Accept-Ranges: bytes
X-Timestamp: 1392683866.17952
Content-Type: text/plain; charset=utf-8
You can also use the ``swift stat`` command with the ``ACCOUNT`` or
``CONTAINER`` names as parameters.
.. code::
$ swift stat CONTAINER
.. code::
Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
Container: storage1
Objects: 2
Bytes: 240221
Read ACL:
Write ACL:
Sync To:
Sync Key:
Accept-Ranges: bytes
X-Timestamp: 1392683866.20180
Content-Type: text/plain; charset=utf-8

49
doc/playground-user-guide/source/cli_swift_discoverability.rst Normal file
View File

@@ -0,0 +1,49 @@
.. _discoverability:
===============
Discoverability
===============
Your Object Storage system might not enable all features that this
document describes. These features are:
* :ref:`large-object-creation`
* :ref:`archive-auto-extract`
* :ref:`bulk-delete`
* :ref:`static-website`
To discover which features are enabled in your Object Storage system,
use the ``/info`` request.
To use the ``/info`` request, send a ``GET`` request using the ``/info``
path to the Object Store endpoint as shown in this example:
.. code::
$ curl https://storage.example.com/info
This example shows a truncated response body:
.. code::
{
"swift":{
"version":"1.11.0"
},
"staticweb":{
},
"tempurl":{
}
}
This output shows that the Object Storage system has enabled the static
website and temporary URL features.
.. note:
In some cases, the ``/info`` request will return an error. This could be
because your service provider has disabled the ``/info`` request
function, or because you are using an older version that does not
support it.

36
doc/playground-user-guide/source/cli_swift_env_vars.rst Normal file
View File

@@ -0,0 +1,36 @@
.. _env-vars:
==============================================
Environment variables required to run examples
==============================================
To run the cURL command examples for the Object Storage API requests,
set these environment variables:
publicURL
The public URL that is the HTTP endpoint from where you can access
Object Storage. It includes the Object Storage API version number
and your account name. For example,
``https://23.253.72.207/v1/my_account``.
token
The authentication token for Object Storage.
To obtain these values, run the ``swift stat -v`` command.
As shown in this example, the public URL appears in the ``StorageURL``
field, and the token appears in the ``Auth Token`` field:
.. code::
StorageURL: https://23.253.72.207/v1/my_account
Auth Token: {token}
Account: my_account
Containers: 2
Objects: 3
Bytes: 47
Meta Book: MobyDick
X-Timestamp: 1389453423.35964
X-Trans-Id: txee55498935404a2caad89-0052dd3b77
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes

103
doc/playground-user-guide/source/cli_swift_large_lists.rst Normal file
View File

@@ -0,0 +1,103 @@
=================================================
Page through large lists of containers or objects
=================================================
If you have a large number of containers or objects, you can use the
``marker``, ``limit``, and ``end_marker`` parameters to control
how many items are returned in a list and where the list starts or ends.
* marker
When you request a list of containers or objects, Object Storage
returns a maximum of 10,000 names for each request. To get
subsequent names, you must make another request with the
``marker`` parameter. Set the ``marker`` parameter to the name of
the last item returned in the previous list. You must URL-encode the
``marker`` value before you send the HTTP request. Object Storage
returns a maximum of 10,000 names starting after the last item
returned.
* limit
To return fewer than 10,000 names, use the ``limit`` parameter. If
the number of names returned equals the specified ``limit`` (or
10,000 if you omit the ``limit`` parameter), you can assume there
are more names to list. If the number of names in the list is
exactly divisible by the ``limit`` value, the last request has no
content.
* end_marker
Limits the result set to names that are less than the
``end_marker`` parameter value. You must URL-encode the
``end_marker`` value before you send the HTTP request.
To page through a large list of containers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Assume the following list of container names:
.. code::
apples
bananas
kiwis
oranges
pears
#. Use a ``limit`` of two:
.. code::
# curl -i $publicURL/?limit=2 -X GET -H "X-Auth-Token: $token"
.. code::
apples
bananas
Because two container names are returned, there are more names to
list.
#. Make another request with a ``marker`` parameter set to the name of
the last item returned:
.. code::
# curl -i $publicURL/?limit=2&amp;marker=bananas -X GET -H \
“X-Auth-Token: $token"
.. code::
kiwis
oranges
Again, two items are returned, and there might be more.
#. Make another request with a ``marker`` of the last item returned:
.. code::
# curl -i $publicURL/?limit=2&amp;marker=oranges -X GET -H \”
X-Auth-Token: $token"
.. code::
pears
You receive a one-item response, which is fewer than the ``limit``
number of names. This indicates that this is the end of the list.
#. Use the ``end_marker`` parameter to limit the result set to object
names that are less than the ``end_marker`` parameter value:
.. code::
# curl -i $publicURL/?end_marker=oranges -X GET -H \”
X-Auth-Token: $token"
.. code::
apples
bananas
kiwis
You receive a result set of all container names before the
``end-marker`` value.

306
doc/playground-user-guide/source/cli_swift_large_object_creation.rst Normal file
View File

@@ -0,0 +1,306 @@
.. _large-object-creation:
=============
Large objects
=============
To discover whether your Object Storage system supports this feature,
see :ref:`discoverability`. Alternatively, check with your service
provider.
By default, the content of an object cannot be greater than 5 GB.
However, you can use a number of smaller objects to construct a large
object. The large object is comprised of two types of objects:
* ``Segment objects`` store the object content. You can divide your
content into segments, and upload each segment into its own segment
object. Segment objects do not have any special features. You create,
update, download, and delete segment objects just as you would normal
objects.
* A ``manifest object`` links the segment objects into one logical
large object. When you download a manifest object, Object Storage
concatenates and returns the contents of the segment objects in the
response body of the request. This behavior extends to the response
headers returned by ``GET`` and ``HEAD`` requests. The
``Content-Length`` response header value is the total size of all
segment objects. Object Storage calculates the ``ETag`` response
header value by taking the ``ETag`` value of each segment,
concatenating them together, and returning the MD5 checksum of the
result. The manifest object types are:
Static large objects
The manifest object content is an ordered list of the names of
the segment objects in JSON format. See :ref:`static_large_objects`.
Dynamic large objects
The manifest object has no content but it has a
``X-Object-Manifest`` metadata header. The value of this header
is ``CONTAINER/PREFIX``, where ``CONTAINER`` is the name of
the container where the segment objects are stored, and
``PREFIX`` is a string that all segment objects have in common.
See :ref:`dynamic_large_objects`.
.. note:
If you make a ``COPY`` request by using a manifest object as the source,
the new object is a normal, and not a segment, object. If the total size
of the source segment objects exceeds 5 GB, the ``COPY`` request fails.
However, you can make a duplicate of the manifest object and this new
object can be larger than 5 GB.
.. _static_large_objects:
Static large objects
~~~~~~~~~~~~~~~~~~~~
To create a static large object, divide your content into pieces and
create (upload) a segment object to contain each piece.
You must record the ``ETag`` response header that the ``PUT`` operation
returns. Alternatively, you can calculate the MD5 checksum of the
segment prior to uploading and include this in the ``ETag`` request
header. This ensures that the upload cannot corrupt your data.
List the name of each segment object along with its size and MD5
checksum in order.
Create a manifest object. Include the ``?multipart-manifest=put``
query string at the end of the manifest object name to indicate that
this is a manifest object.
The body of the ``PUT`` request on the manifest object comprises a JSON
list, where each element contains the following attributes:
path
The container and object name in the format:
``CONTAINER_NAME/OBJECT_NAME``.
etag
The MD5 checksum of the content of the segment object. This value
must match the ``ETag`` of that object.
size_bytes
The size of the segment object. This value must match the
``Content-Length`` of that object.
Static large object manifest list
---------------------------------
This example shows three segment objects. You can use several containers
and the object names do not have to conform to a specific pattern, in
contrast to dynamic large objects.
.. code::
[
{
"path": "mycontainer/objseg1",
"etag": "0228c7926b8b642dfb29554cd1f00963",
"size_bytes": 1468006
},
{
"path": "mycontainer/pseudodir/seg-obj2",
"etag": "5bfc9ea51a00b790717eeb934fb77b9b",
"size_bytes": 1572864
},
{
"path": "other-container/seg-final",
"etag": "b9c3da507d2557c1ddc51f27c54bae51",
"size_bytes": 256
}
]
|
The ``Content-Length`` request header must contain the length of the
JSON content—not the length of the segment objects. However, after the
``PUT`` operation completes, the ``Content-Length`` metadata is set to
the total length of all the object segments. A similar situation applies
to the ``ETag``. If used in the ``PUT`` operation, it must contain the
MD5 checksum of the JSON content. The ``ETag`` metadata value is then
set to be the MD5 checksum of the concatenated ``ETag`` values of the
object segments. You can also set the ``Content-Type`` request header
and custom object metadata.
When the ``PUT`` operation sees the ``?multipart-manifest=put`` query
parameter, it reads the request body and verifies that each segment
object exists and that the sizes and ETags match. If there is a
mismatch, the ``PUT`` operation fails.
If everything matches, the manifest object is created. The
``X-Static-Large-Object`` metadata is set to ``true`` indicating that
this is a static object manifest.
Normally when you perform a ``GET`` operation on the manifest object,
the response body contains the concatenated content of the segment
objects. To download the manifest list, use the
``?multipart-manifest=get`` query parameter. The resulting list is not
formatted the same as the manifest you originally used in the ``PUT``
operation.
If you use the ``DELETE`` operation on a manifest object, the manifest
object is deleted. The segment objects are not affected. However, if you
add the ``?multipart-manifest=delete`` query parameter, the segment
objects are deleted and if all are successfully deleted, the manifest
object is also deleted.
To change the manifest, use a ``PUT`` operation with the
``?multipart-manifest=put`` query parameter. This request creates a
manifest object. You can also update the object metadata in the usual
way.
.. _dynamic_large_objects:
Dynamic large objects
~~~~~~~~~~~~~~~~~~~~~
You must segment objects that are larger than 5 GB before you can upload
them. You then upload the segment objects like you would any other
object and create a dynamic large manifest object. The manifest object
tells Object Storage how to find the segment objects that comprise the
large object. The segments remain individually addressable, but
retrieving the manifest object streams all the segments concatenated.
There is no limit to the number of segments that can be a part of a
single large object.
To ensure the download works correctly, you must upload all the object
segments to the same container and ensure that each object name is
prefixed in such a way that it sorts in the order in which it should be
concatenated. You also create and upload a manifest file. The manifest
file is a zero-byte file with the extra ``X-Object-Manifest``
``CONTAINER/PREFIX`` header, where ``CONTAINER`` is the container
the object segments are in and ``PREFIX`` is the common prefix for all
the segments. You must UTF-8-encode and then URL-encode the container
and common prefix in the ``X-Object-Manifest`` header.
It is best to upload all the segments first and then create or update
the manifest. With this method, the full object is not available for
downloading until the upload is complete. Also, you can upload a new set
of segments to a second location and update the manifest to point to
this new location. During the upload of the new segments, the original
manifest is still available to download the first set of segments.
Upload segment of large object request: HTTP
--------------------------------------------
.. code::
PUT /API_VERSION/ACCOUNT/CONTAINER/OBJECT HTTP/1.1
Host: storage.example.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
X-Object-Meta-PIN: 1234
No response body is returned. A status code of 2``nn`` (between 200
and 299, inclusive) indicates a successful write; status 411 Length
Required denotes a missing ``Content-Length`` or ``Content-Type`` header
in the request. If the MD5 checksum of the data written to the storage
system does NOT match the (optionally) supplied ETag value, a 422
Unprocessable Entity response is returned.
You can continue uploading segments, like this example shows, prior to
uploading the manifest.
Upload next segment of large object request: HTTP
-------------------------------------------------
.. code::
PUT /API_VERSION/ACCOUNT/CONTAINER/OBJECT HTTP/1.1
Host: storage.example.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
X-Object-Meta-PIN: 1234
Next, upload the manifest you created that indicates the container where
the object segments reside. Note that uploading additional segments
after the manifest is created causes the concatenated object to be that
much larger but you do not need to recreate the manifest file for
subsequent additional segments.
Upload manifest request: HTTP
-----------------------------
.. code::
PUT /API_VERSION/ACCOUNT/CONTAINER/OBJECT HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Content-Length: 0
X-Object-Meta-PIN: 1234
X-Object-Manifest: CONTAINER/PREFIX
Upload manifest response: HTTP
------------------------------
.. code::
[...]
The ``Content-Type`` in the response for a ``GET`` or ``HEAD`` on the
manifest is the same as the ``Content-Type`` set during the ``PUT``
request that created the manifest. You can change the ``Content-Type``
by reissuing the ``PUT`` request.
Comparison of static and dynamic large objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
While static and dynamic objects have similar behavior, this table
describes their differences:
+-------------------------+-----------------------------------------+-------------------------------------------+
| | Static large object | Dynamic large object |
+=========================+=========================================+===========================================+
| **End-to-end | Assured. The list of segments | Not guaranteed. The eventual consistency |
| integrity** | includes the MD5 checksum (``ETag``) of | model means that although you |
| | each segment. You cannot upload the | have uploaded a segment object, it |
| | the manifest object if the ``ETag`` in | might not appear in the container |
| | the list differs from the uploaded | listing until later. If you download |
| | segment object. If a segment is | the manifest before it appears in |
| | somehow lost, an attempt to download | the container, it does not form part |
| | the manifest object results in an | of the content returned in response |
| | error. | to a ``GET`` request. |
+-------------------------+-----------------------------------------+-------------------------------------------+
| **Upload order** | You must upload the segment objects | You can upload manifest and segment |
| | before upload the manifest object. | objects in any order. You are recommended |
| | | to upload the manifest object after the |
| | | segments in case a premature download of |
| | | the manifest occurs. However, this is not |
| | | enforced. |
+-------------------------+-----------------------------------------+-------------------------------------------+
| **Removal or addition | You cannot add or remove segment | You can upload new segment objects or |
| of segment objects** | objects from the manifest. However, you | remove existing segments. The names |
| | can create a completely new manifest | must simply match the ``PREFIX`` |
| | object of the same name with a | supplied in ``X-Object-Manifest``. |
| | different manifest list. | |
+-------------------------+-----------------------------------------+-------------------------------------------+
| **Segment object | Segment objects must be at least 1 MB | Segment objects can be any size. |
| size and number** | in size (by default). The final segment | |
| | object can be any size. At most, 1000 | |
| | segments are supported (by default). | |
| | | |
+-------------------------+-----------------------------------------+-------------------------------------------+
| **Segment object | The manifest list includes the | All segment objects must be in the |
| container name** | container name of each object. Segment | same container. |
| | objects can be in different containers. | |
| | | |
+-------------------------+-----------------------------------------+-------------------------------------------+
| **Manifest object | The object has ``X-Static-Large-Object``| The ``X-Object-Manifest`` value is the |
| metadata** | set to ``true``. You do not set this | ``CONTAINER/PREFIX``, which indicates |
| | metadata directly. Instead the system | where the segment objects are located. |
| | sets it when you ``PUT`` a static | You supply this request header in the |
| | manifest object. | ``PUT`` operation. |
+-------------------------+-----------------------------------------+-------------------------------------------+
| **Copying the manifest | Include the ``?multipart-manifest=get`` | The ``COPY`` operation does not create |
| object** | query string in the ``COPY`` request. | a manifest object. To duplicate a |
| | The new object contains the same | manifest object, use the ``GET`` |
| | manifest as the original. The segment | operation to read the value of |
| | objects are not copied. Instead,both | ``X-Object-Manifest`` and use this value |
| | the original and new manifest objects | in the ``X-Object-Manifest`` request |
| | share the same set of segment objects. | header in a ``PUT`` operation. This |
| | | creates a new manifest object that shares |
| | | the same set of segment objects as the |
| | | original manifest object. |
+-------------------------+-----------------------------------------+-------------------------------------------+

32
doc/playground-user-guide/source/cli_swift_manage_access_swift.rst Normal file
View File

@@ -0,0 +1,32 @@
=============
Manage access
=============
- Users have roles on accounts. For example, a user with the admin role
has full access to all containers and objects in an account. You can
set access control lists (ACLs) at the container level and support
lists for read and write access, which you set with the
``X-Container-Read`` and ``X-Container-Write`` headers.
To give a user read access, use the ``swift post`` command with the
``-r`` parameter. To give a user write access, use the ``-w``
parameter.
The following example enables the ``testuser`` user to read objects
in the container:
.. code::
$ swift post -r 'testuser'
You can also use this command with a list of users.
- If you use StaticWeb middleware to enable Object Storage to serve
public web content, use ``.r:``, followed by a list of allowed
referrers.
The following command gives object access to all referring domains:
.. code::
$ swift post -r '.r:*'

46
doc/playground-user-guide/source/cli_swift_manage_objects.rst Normal file
View File

@@ -0,0 +1,46 @@
==============
Manage objects
==============
- To upload an object to a container, run the following command:
.. code::
$ swift upload CONTAINER OBJECT_FILENAME
To upload in chunks, for large files, run the following command:
.. code::
$ swift upload -S CHUNK_SIZE CONTAINER OBJECT_FILENAME
- To check the status of the object, run the following command:
.. code::
$ swift stat CONTAINER OBJECT_FILENAME
.. code::
Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
Container: storage1
Object: images
Content Type: application/octet-stream
Content Length: 211616
Last Modified: Tue, 18 Feb 2014 00:40:36 GMT
ETag: 82169623d55158f70a0d720f238ec3ef
Meta Orig-Filename: images.jpg
Accept-Ranges: bytes
X-Timestamp: 1392684036.33306
- To list the objects in a container, run the following command:
.. code::
$ swift list CONTAINER
- To download an object from a container, run the following command:
.. code::
$ swift download CONTAINER OBJECT_FILENAME

103
doc/playground-user-guide/source/cli_swift_pseudo_hierarchical_folders_directories.rst Normal file
View File

@@ -0,0 +1,103 @@
===========================================
Pseudo-hierarchical folders and directories
===========================================
Although you cannot nest directories in OpenStack Object Storage, you
can simulate a hierarchical structure within a single container by
adding forward slash characters (``/``) in the object name. To navigate
the pseudo-directory structure, you can use the ``delimiter`` query
parameter. This example shows you how to use pseudo-hierarchical folders
and directories.
.. note::
In this example, the objects reside in a container called ``backups``.
Within that container, the objects are organized in a pseudo-directory
called ``photos``. The container name is not displayed in the example,
but it is a part of the object URLs. For instance, the URL of the
picture ``me.jpg`` is
``https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg``.
List pseudo-hierarchical folders request: HTTP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To display a list of all the objects in the storage container, use
``GET`` without a ``delimiter`` or ``prefix``.
.. code::
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups
The system returns status code 2xx (between 200 and 299, inclusive) and
the requested list of the objects.
.. code::
photos/animals/cats/persian.jpg
photos/animals/cats/siamese.jpg
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg
photos/me.jpg
photos/plants/fern.jpg
photos/plants/rose.jpg
Use the delimiter parameter to limit the displayed results. To use
``delimiter`` with pseudo-directories, you must use the parameter slash
(``/``).
.. code::
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups?delimiter=/
The system returns status code 2xx (between 200 and 299, inclusive) and
the requested matching objects. Because you use the slash, only the
pseudo-directory ``photos/`` displays. The returned values from a slash
``delimiter`` query are not real objects. They have a content-type of
``application/directory`` and are in the ``subdir`` section of JSON and
XML results.
.. code::
photos/
Use the ``prefix`` and ``delimiter`` parameters to view the objects
inside a pseudo-directory, including further nested pseudo-directories.
.. code::
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups?prefix=photos/&delimiter=/
The system returns status code 2xx (between 200 and 299, inclusive) and
the objects and pseudo-directories within the top level
pseudo-directory.
.. code::
photos/animals/
photos/me.jpg
photos/plants/
You can create an unlimited number of nested pseudo-directories. To
navigate through them, use a longer ``prefix`` parameter coupled with
the ``delimiter`` parameter. In this sample output, there is a
pseudo-directory called ``dogs`` within the pseudo-directory
``animals``. To navigate directly to the files contained within
``dogs``, enter the following command:
.. code::
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/
The system returns status code 2xx (between 200 and 299, inclusive) and
the objects and pseudo-directories within the nested pseudo-directory.
.. code::
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg

124
doc/playground-user-guide/source/cli_swift_serialized_response_formats.rst Normal file
View File

@@ -0,0 +1,124 @@
===========================
Serialized response formats
===========================
By default, the Object Storage API uses a ``text/plain`` response
format. In addition, both JSON and XML data serialization response
formats are supported.
.. note::
To run the cURL command examples, you must export environment variables. For more
information, see the section :ref:`env-vars`.
To define the response format, use one of these methods:
+-------------------+-------------------------------------------------------+
|Method |Description |
+===================+=======================================================+
|format= ``format`` |Append this parameter to the URL for a ``GET`` request,|
|query parameter |where ``format`` is ``json`` or ``xml``. |
+-------------------+-------------------------------------------------------+
|``Accept`` request |Include this header in the ``GET`` request. |
|header |The valid header values are: |
| | |
| |text/plain |
| | Plain text response format. The default. |
| |application/jsontext |
| | JSON data serialization response format. |
| |application/xml |
| | XML data serialization response format. |
| |text/xml |
| | XML data serialization response format. |
+-------------------+-------------------------------------------------------+
Example 1. JSON example with format query parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For example, this request uses the ``format`` query parameter to ask
for a JSON response:
.. code::
$ curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"
.. code::
HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT
Object Storage lists container names with additional information in JSON
format:
.. code::
[
{
"count":0,
"bytes":0,
"name":"janeausten"
},
{
"count":1,
"bytes":14,
"name":"marktwain"
}
]
Example 2. XML example with Accept header
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This request uses the ``Accept`` request header to ask for an XML
response:
.. code::
$ curl -i $publicURL -X GET -H "X-Auth-Token: $token" -H \
”Accept: application/xml; charset=utf-8"
.. code::
HTTP/1.1 200 OK
Content-Length: 263
X-Account-Object-Count: 3
X-Account-Meta-Book: MobyDick
X-Timestamp: 1389453423.35964
X-Account-Bytes-Used: 47
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: txf0b4c9727c3e491694019-0052e03420
Date: Wed, 22 Jan 2014 21:12:00 GMT
Object Storage lists container names with additional information in XML
format:
.. code::
<?xml version="1.0" encoding="UTF-8"?>
<account name="AUTH_73f0aa26640f4971864919d0eb0f0880">
<container>
<name>janeausten</name>
<count>2</count>
<bytes>33</bytes>
</container>
<container>
<name>marktwain</name>
<count>1</count>
<bytes>14</bytes>
</container>
</account>
The remainder of the examples in this guide use standard, non-serialized
responses. However, all ``GET`` requests that perform list operations
accept the ``format`` query parameter or ``Accept`` request header.

200
doc/playground-user-guide/source/cli_swift_set_object_versions.rst Normal file
View File

@@ -0,0 +1,200 @@
=================
Object versioning
=================
You can store multiple versions of your content so that you can recover
from unintended overwrites. Object versioning is an easy way to
implement version control, which you can use with any type of content.
.. note::
You cannot version a large-object manifest file, but the large-object
manifest file can point to versioned segments.
We strongly recommended that you put non-current objects in a different
container than the container where current object versions reside.
To enable and use object versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. To enable object versioning, ask your cloud provider to set the
``allow_versions`` option to ``TRUE`` in the container configuration
file.
#. Create an ``archive`` container to store older versions of objects:
.. code::
$ curl -i $publicURL/archive -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
.. code::
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx46f8c29050834d88b8d7e-0052e1859d
Date: Thu, 23 Jan 2014 21:11:57 GMT
#. Create a ``current`` container to store current versions of objects.
Include the ``X-Versions-Location`` header. This header defines the
container that holds the non-current versions of your objects. You
must UTF-8-encode and then URL-encode the container name before you
include it in the ``X-Versions-Location`` header. This header enables
object versioning for all objects in the ``current`` container.
Changes to objects in the ``current`` container automatically create
non-current versions in the ``archive`` container.
.. code::
$ curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H \
”X-Auth-Token: $token" -H "X-Versions-Location: archive"
.. code::
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb91810fb717347d09eec8-0052e18997
Date: Thu, 23 Jan 2014 21:28:55 GMT
#. Create the first version of an object in the ``current`` container:
.. code::
$ curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H \
”Content-Length: 0" -H "X-Auth-Token: $token"
.. code::
HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:31:22 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx5992d536a4bd4fec973aa-0052e18a2a
Date: Thu, 23 Jan 2014 21:31:22 GMT
Nothing is written to the non-current version container when you
initially ``PUT`` an object in the ``current`` container. However,
subsequent ``PUT`` requests that edit an object trigger the creation
of a version of that object in the ``archive`` container.
These non-current versions are named as follows:
.. code::
<length><object_name><timestamp>
Where ``length`` is the 3-character, zero-padded hexadecimal
character length of the object, ``<object_name>`` is the object name,
and ``<timestamp>`` is the time when the object was initially created
as a current version.
#. Create a second version of the object in the ``current`` container:
.. code::
$ curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H \
“Content-Length: 0" -H "X-Auth-Token: $token"
.. code::
HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:41:32 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx468287ce4fc94eada96ec-0052e18c8c
Date: Thu, 23 Jan 2014 21:41:32 GMT
#. Issue a ``GET`` request to a versioned object to get the current
version of the object. You do not have to do any request redirects or
metadata lookups.
List older versions of the object in the ``archive`` container:
.. code::
$ curl -i $publicURL/archive?prefix=009my_object -X GET -H \
"X-Auth-Token: $token"
.. code::
HTTP/1.1 200 OK
Content-Length: 30
X-Container-Object-Count: 1
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx9a441884997542d3a5868-0052e18d8e
Date: Thu, 23 Jan 2014 21:45:50 GMT
009my_object/1390512682.92052
.. note::
A ``POST`` request to a versioned object updates only the metadata
for the object and does not create a new version of the object. New
versions are created only when the content of the object changes.
#. Issue a ``DELETE`` request to a versioned object to remove the
current version of the object and replace it with the next-most
current version in the non-current container.
.. code::
$ curl -i $publicURL/current/my_object -X DELETE -H \
"X-Auth-Token: $token"
.. code::
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx006d944e02494e229b8ee-0052e18edd
Date: Thu, 23 Jan 2014 21:51:25 GMT
List objects in the ``archive`` container to show that the archived
object was moved back to the ``current`` container:
.. code::
$ curl -i $publicURL/archive?prefix=009my_object -X GET -H \
"X-Auth-Token: $token"
.. code::
HTTP/1.1 204 No Content
Content-Length: 0
X-Container-Object-Count: 0
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx044f2a05f56f4997af737-0052e18eed
Date: Thu, 23 Jan 2014 21:51:41 GMT
This next-most current version carries with it any metadata last set
on it. If you want to completely remove an object and you have five
versions of it, you must ``DELETE`` it five times.
#. To disable object versioning for the ``current`` container, remove
its ``X-Versions-Location`` metadata header by sending an empty key
value.
.. code::
$ curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H \
"X-Auth-Token: $token" -H "X-Versions-Location: "
.. code::
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txe2476de217134549996d0-0052e19038
Date: Thu, 23 Jan 2014 21:57:12 GMT
<html><h1>Accepted</h1><p>The request is accepted for processing.</p></html>

124
doc/playground-user-guide/source/cli_swift_static_website.rst Normal file
View File

@@ -0,0 +1,124 @@
.. _static-website:
=====================
Create static website
=====================
To discover whether your Object Storage system supports this feature,
see :ref:`discoverability`. Alternatively, check with your service
provider.
You can use your Object Storage account to create a static website. This
static website is created with Static Web middleware and serves container
data with a specified index file, error file resolution, and optional
file listings. This mode is normally active only for anonymous requests,
which provide no authentication token. To use it with authenticated
requests, set the header ``X-Web-Mode`` to ``TRUE`` on the request.
The Static Web filter must be added to the pipeline in your
``/etc/swift/proxy-server.conf`` file below any authentication
middleware. You must also add a Static Web middleware configuration
section.
See the Cloud Administrator Guide for an example of the `static web configuration syntax <http://docs.openstack.org/juno/config-reference/content/object-storage-static-web.html>`_.
See the Cloud Administrator Guide for a complete example of the `/etc/swift/proxy-server.conf file <http://docs.openstack.org/juno/config-reference/content/proxy-server-conf.html>`_ (including static web).
Your publicly readable containers are checked for two headers,
``X-Container-Meta-Web-Index`` and ``X-Container-Meta-Web-Error``. The
``X-Container-Meta-Web-Error`` header is discussed below, in `the
section called :ref:`set_error_static_website`..
Use ``X-Container-Meta-Web-Index`` to determine the index file (or
default page served, such as ``index.html``) for your website. When
someone initially enters your site, the ``index.html`` file displays
automatically. If you create sub-directories for your site by creating
pseudo-directories in your container, the index page for each
sub-directory is displayed by default. If your pseudo-directory does not
have a file with the same name as your index file, visits to the
sub-directory return a 404 error.
You also have the option of displaying a list of files in your
pseudo-directory instead of a web page. To do this, set the
``X-Container-Meta-Web-Listings`` header to ``TRUE``. You may add styles
to your file listing by setting ``X-Container-Meta-Web-Listings-CSS:``
to a style sheet (for example, ``lists.css``).
Static Web middleware through Object Storage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following sections show how to use Static Web middleware through
Object Storage.
Make container publicly readable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Make the container publicly readable. Once the container is publicly
readable, you can access your objects directly, but you must set the
index file to browse the main site URL and its sub-directories.
.. code::
$ swift post -r '.r:*' container
Set site index file
^^^^^^^^^^^^^^^^^^^
Set the index file. In this case, ``index.html`` is the default file
displayed when the site appears.
.. code::
$ swift post -m 'web-index:index.html' container
Enable file listing
^^^^^^^^^^^^^^^^^^^
Turn on file listing. If you do not set the index file, the URL displays
a list of the objects in the container. Instructions on styling the list
with a CSS follow.
.. code::
$ swift post -m 'web-listings: true' container
Enable CSS for file listing
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Style the file listing using a CSS.
.. code::
$ swift post -m 'web-listings-css:listings.css' container
.. _set_error_static_website:
Set error pages for static website
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can create and set custom error pages for visitors to your website;
currently, only 401 (Unauthorized) and 404 (Not Found) errors are
supported. To do this, set the metadata header,
``X-Container-Meta-Web-Error``.
Error pages are served with the status code pre-pended to the name of
the error page you set. For instance, if you set
``X-Container-Meta-Web-Error`` to ``error.html``, 401 errors will
display the page ``401error.html``. Similarly, 404 errors will display
``404error.html``. You must have both of these pages created in your
container when you set the ``X-Container-Meta-Web-Error`` metadata, or
your site will display generic error pages.
You only have to set the ``X-Container-Meta-Web-Error`` metadata once
for your entire static website.
Set error pages for static website request
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code::
$ swift post -m 'web-error:error.html' container
Any 2\ ``nn`` response indicates success.

6
doc/playground-user-guide/source/manage_instances.rst
View File

@@ -22,12 +22,12 @@ Create instance snapshots
#. On the :guilabel:`Admin` tab, click the :guilabel:`Instances` category.
#. Select an instance to create a snapshot from it. From the :guilabel:`Actions`
drop-down list, select :guilabel:`Create Snapshot`.
#. Select an instance to create a snapshot from it. From the
:guilabel:`Actions` drop-down list, select :guilabel:`Create Snapshot`.
#. In the :guilabel:`Create Snapshot` window, enter a name for the snapshot.
# Click :guilabel:`Create Snapshot`. The dashboard shows the instance snapshot
#. Click :guilabel:`Create Snapshot`. The dashboard shows the instance snapshot
in the :guilabel:`Images & Snapshots` category.
#. To launch an instance from the snapshot, select the snapshot and

31
doc/playground-user-guide/source/managing-openstack-object-storage-with-swift-cli.rst Normal file
View File

@@ -0,0 +1,31 @@
=============================
Manage objects and containers
=============================
The OpenStack Object Storage service provides the ``swift`` client,
which is a command-line interface (CLI). Use this client to list
objects and containers, upload objects to containers, and download
or delete objects from containers. You can also gather statistics and
update metadata for accounts, containers, and objects.
This client is based on the native swift client library, ``client.py``,
which seamlessly re-authenticates if the current token expires during
processing, retries operations multiple times, and provides a processing
concurrency of 10.
.. toctree::
:maxdepth: 2
cli_swift_create_containers.rst
cli_swift_manage_access_swift.rst
cli_swift_manage_objects.rst
cli_swift_env_vars.rst
cli_swift_set_object_versions.rst
cli_swift_serialized_response_formats.rst
cli_swift_large_lists.rst
cli_swift_pseudo_hierarchical_folders_directories.rst
cli_swift_discoverability.rst
cli_swift_large_object_creation.rst
cli_swift_archive_auto_extract.rst
cli_swift_bulk_delete.rst
cli_swift_static_website.rst