summaryrefslogtreecommitdiff
path: root/doc/source/cli.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/source/cli.rst')
-rw-r--r--doc/source/cli.rst748
1 files changed, 632 insertions, 116 deletions
diff --git a/doc/source/cli.rst b/doc/source/cli.rst
index 8df95aa..1277caa 100644
--- a/doc/source/cli.rst
+++ b/doc/source/cli.rst
@@ -6,6 +6,139 @@ The ``swift`` tool is a command line utility for communicating with an OpenStack
Object Storage (swift) environment. It allows one to perform several types of
operations.
+
+For help on a specific :command:`swift` command, enter:
+
+.. code-block:: console
+
+ $ swift COMMAND --help
+
+.. _swift_command_usage:
+
+swift usage
+~~~~~~~~~~~
+
+.. code-block:: console
+
+ Usage: swift [--version] [--help] [--os-help] [--snet] [--verbose]
+ [--debug] [--info] [--quiet] [--auth <auth_url>]
+ [--auth-version <auth_version> |
+ --os-identity-api-version <auth_version> ]
+ [--user <username>]
+ [--key <api_key>] [--retries <num_retries>]
+ [--os-username <auth-user-name>] [--os-password <auth-password>]
+ [--os-user-id <auth-user-id>]
+ [--os-user-domain-id <auth-user-domain-id>]
+ [--os-user-domain-name <auth-user-domain-name>]
+ [--os-tenant-id <auth-tenant-id>]
+ [--os-tenant-name <auth-tenant-name>]
+ [--os-project-id <auth-project-id>]
+ [--os-project-name <auth-project-name>]
+ [--os-project-domain-id <auth-project-domain-id>]
+ [--os-project-domain-name <auth-project-domain-name>]
+ [--os-auth-url <auth-url>] [--os-auth-token <auth-token>]
+ [--os-storage-url <storage-url>] [--os-region-name <region-name>]
+ [--os-service-type <service-type>]
+ [--os-endpoint-type <endpoint-type>]
+ [--os-cacert <ca-certificate>] [--insecure]
+ [--os-cert <client-certificate-file>]
+ [--os-key <client-certificate-key-file>]
+ [--no-ssl-compression]
+ <subcommand> [--help] [<subcommand options>]
+
+**Subcommands:**
+
+``delete``
+ Delete a container or objects within a container.
+
+``download``
+ Download objects from containers.
+
+``list``
+ Lists the containers for the account or the objects
+ for a container.
+
+``post``
+ Updates meta information for the account, container,
+ or object; creates containers if not present.
+
+``copy``
+ Copies object, optionally adds meta
+
+``stat``
+ Displays information for the account, container,
+ or object.
+
+``upload``
+ Uploads files or directories to the given container.
+
+``capabilities``
+ List cluster capabilities.
+
+``tempurl``
+ Create a temporary URL.
+
+``auth``
+ Display auth related environment variables.
+
+.. _swift_command_options:
+
+swift optional arguments
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``--version``
+ show program's version number and exit
+
+``-h, --help``
+ show this help message and exit
+
+``--os-help``
+ Show OpenStack authentication options.
+
+``-s, --snet``
+ Use SERVICENET internal network.
+
+``-v, --verbose``
+ Print more info.
+
+``--debug``
+ Show the curl commands and results of all http queries
+ regardless of result status.
+
+``--info``
+ Show the curl commands and results of all http queries
+ which return an error.
+
+``-q, --quiet``
+ Suppress status output.
+
+``-A AUTH, --auth=AUTH``
+ URL for obtaining an auth token.
+
+``-V AUTH_VERSION, --auth-version=AUTH_VERSION, --os-identity-api-version=AUTH_VERSION``
+ Specify a version for authentication. Defaults to
+ ``env[ST_AUTH_VERSION]``, ``env[OS_AUTH_VERSION]``,
+ ``env[OS_IDENTITY_API_VERSION]`` or 1.0.
+
+``-U USER, --user=USER``
+ User name for obtaining an auth token.
+
+``-K KEY, --key=KEY``
+ Key for obtaining an auth token.
+
+``-R RETRIES, --retries=RETRIES``
+ The number of times to retry a failed connection.
+
+``--insecure``
+ Allow swiftclient to access servers without having to
+ verify the SSL certificate. Defaults to
+ ``env[SWIFTCLIENT_INSECURE]`` (set to 'true' to enable).
+
+``--no-ssl-compression``
+ This option is deprecated and not used anymore. SSL
+ compression should be disabled by default by the
+ system SSL library.
+
Authentication
~~~~~~~~~~~~~~
@@ -119,160 +252,543 @@ storage URL options shown below:
CLI commands
~~~~~~~~~~~~
-Stat
+.. _swift_auth:
+
+Auth
----
- ``stat [container [object]]``
+.. code-block:: console
- Displays information for the account, container, or object depending on
- the arguments given (if any). In verbose mode, the storage URL and the
- authentication token are displayed as well.
+ Usage: swift auth
-List
-----
+Display authentication variables in shell friendly format. Command to run to export storage
+URL and auth token into ``OS_STORAGE_URL`` and ``OS_AUTH_TOKEN``: ``swift auth``.
+Command to append to a runcom file (e.g. ``~/.bashrc``, ``/etc/profile``) for automatic
+authentication: ``swift auth -v -U test:tester -K testing``.
- ``list [command-options] [container]``
+.. _swift_stat:
- Lists the containers for the account or the objects for a container.
- The ``-p <prefix>`` or ``--prefix <prefix>`` is an option that will only
- list items beginning with that prefix. The ``-d <delimiter>`` or
- ``--delimiter <delimiter>`` is an option (for container listings only)
- that will roll up items with the given delimiter (see `OpenStack Swift
- general documentation <http://docs.openstack.org/developer/swift/>` for
- what this means).
+swift stat
+----------
- The ``-l`` and ``--lh`` options provide more detail, similar to ``ls -l``
- and ``ls -lh``, the latter providing sizes in human readable format
- (For example: ``3K``, ``12M``, etc). The latter two switches use more
- overhead to retrieve the displayed details, which is directly proportional
- to the number of container or objects listed.
+.. code-block:: console
-Upload
-------
+ Usage: swift stat [--lh] [--header <header:value>]
+ [<container> [<object>]]
- ``upload [command-options] container file_or_directory [file_or_directory] [...]``
+Displays information for the account, container, or object depending on
+the arguments given (if any). In verbose mode, the storage URL and the
+authentication token are displayed as well.
- Uploads the files and directories specified by the remaining arguments to the
- given container. The ``-c`` or ``--changed`` is an option that will only
- upload files that have changed since the last upload. The
- ``--object-name <object-name>`` is an option that will upload a file and
- name object to ``<object-name>`` or upload a directory and use ``<object-name>``
- as object prefix. The ``-S <size>`` or ``--segment-size <size>`` and
- ``--leave-segments`` are options as well (see ``--help`` for more).
+**Positional arguments:**
-Post
-----
+``[container]``
+ Name of container to stat from.
- ``post [command-options] [container] [object]``
+``[object]``
+ Name of object to stat.
- Updates meta information for the account, container, or object depending
- on the arguments given. If the container is not found, the ``swiftclient``
- will create it automatically, but this is not true for accounts and
- objects. Containers also allow the ``-r <read-acl>`` (or ``--read-acl
- <read-acl>``) and ``-w <write-acl>`` (or ``--write-acl <write-acl>``) options.
- The ``-m`` or ``--meta`` option is allowed on accounts, containers and objects,
- and is used to define the user metadata items to set in the form ``Name:Value``.
- You can repeat this option. For example: ``post -m Color:Blue -m Size:Large``
+**Optional arguments:**
- For more information about ACL formats see the documentation:
- `ACLs <http://docs.openstack.org/developer/swift/misc.html#acls/>`_.
+``--lh``
+ Report sizes in human readable format similar to
+ ls -lh.
-Download
---------
+``-H, --header <header:value>``
+ Adds a custom request header to use for stat.
- ``download [command-options] [container] [object] [object] [...]``
+.. _swift_list:
- Downloads everything in the account (with ``--all``), or everything in a
- container, or a list of objects depending on the arguments given. For a
- single object download, you may use the ``-o <filename>`` or ``--output <filename>``
- option to redirect the output to a specific file or ``-`` to
- redirect to stdout. The ``--ignore-checksum`` is an option that turn off
- checksum validation. You can specify optional headers with the repeatable
- cURL-like option ``-H [--header <name:value>]``. ``--ignore-mtime`` ignores the
- ``x-object-meta-mtime`` metadata entry on the object (if present) and instead
- creates the downloaded files with fresh atime and mtime values.
+swift list
+----------
-Delete
-------
+.. code-block:: console
- ``delete [command-options] [container] [object] [object] [...]``
+ Usage: swift list [--long] [--lh] [--totals] [--prefix <prefix>]
+ [--delimiter <delimiter>] [--header <header:value>]
+ [<container>]
- Deletes everything in the account (with ``--all``), or everything in a
- container, or a list of objects depending on the arguments given. Segments
- of manifest objects will be deleted as well, unless you specify the
- ``--leave-segments`` option.
+Lists the containers for the account or the objects for a container.
+The ``-p <prefix>`` or ``--prefix <prefix>`` is an option that will only
+list items beginning with that prefix. The ``-d <delimiter>`` or
+``--delimiter <delimiter>`` is an option (for container listings only)
+that will roll up items with the given delimiter (see `OpenStack Swift
+general documentation <http://docs.openstack.org/developer/swift/>` for
+what this means).
-Copy
-----
+The ``-l`` and ``--lh`` options provide more detail, similar to ``ls -l``
+and ``ls -lh``, the latter providing sizes in human readable format
+(For example: ``3K``, ``12M``, etc). The latter two switches use more
+overhead to retrieve the displayed details, which is directly proportional
+to the number of container or objects listed.
+
+**Positional arguments:**
+
+``[container]``
+ Name of container to list object in.
+
+**Optional arguments:**
+
+``-l, --long``
+ Long listing format, similar to ls -l.
- ``copy [command-options] container object``
+``--lh``
+ Report sizes in human readable format similar to
+ ls -lh.
- Copies an object to a new destination or adds user metadata to an object. Depending
- on the options supplied, you can preserve existing metadata in contrast to the post
- command. The ``--destination`` option sets the copy target destination in the form
- ``/container/object``. If not set, the object will be copied onto itself which is useful
- for adding metadata. You can use the ``-M`` or ``--fresh-metadata`` option to copy
- an object without existing user meta data, and the ``-m`` or ``--meta`` option
- to define user meta data items to set in the form ``Name:Value``. You can repeat
- this option. For example: ``copy -m Color:Blue -m Size:Large``.
+``-t, --totals``
+ Used with -l or --lh, only report totals.
-Capabilities
+``-p <prefix>, --prefix <prefix>``
+ Only list items beginning with the prefix.
+
+``-d <delim>, --delimiter <delim>``
+ Roll up items with the given delimiter. For containers
+ only. See OpenStack Swift API documentation for what
+ this means.
+
+``-H, --header <header:value>``
+ Adds a custom request header to use for listing.
+
+.. _swift_upload:
+
+swift upload
------------
- ``capabilities [proxy-url]``
+.. code-block:: console
- Displays cluster capabilities. The output includes the list of the
- activated Swift middlewares as well as relevant options for each ones.
- Additionally the command displays relevant options for the Swift core. If
- the ``proxy-url`` option is not provided, the storage URL retrieved after
- authentication is used as ``proxy-url``.
+ Usage: swift upload [--changed] [--skip-identical] [--segment-size <size>]
+ [--segment-container <container>] [--leave-segments]
+ [--object-threads <thread>] [--segment-threads <threads>]
+ [--header <header>] [--use-slo] [--ignore-checksum]
+ [--object-name <object-name>]
+ <container> <file_or_directory> [<file_or_directory>] [...]
-Tempurl
--------
+Uploads the files and directories specified by the remaining arguments to the
+given container. The ``-c`` or ``--changed`` is an option that will only
+upload files that have changed since the last upload. The
+``--object-name <object-name>`` is an option that will upload a file and
+name object to ``<object-name>`` or upload a directory and use ``<object-name>``
+as object prefix. The ``-S <size>`` or ``--segment-size <size>`` and
+``--leave-segments`` are options as well (see ``--help`` for more).
- ``tempurl [command-options] [method] [time] [path] [key]``
+Uploads specified files and directories to the given container.
- Generates a temporary URL for a Swift object. ``method`` option sets an HTTP method to
- allow for this temporary URL that is usually ``GET` or ``PUT``. ``time`` option sets
- the amount of time the temporary URL will be valid for.
- ``time`` can be specified as an integer, denoting the number of seconds
- from now on until the URL shall be valid; or, if ``--absolute``
- is passed, the Unix timestamp when the temporary URL will expire.
- But beyond that, ``time`` can also be specified as an ISO 8601 timestamp
- in one of following formats:
+**Positional arguments:**
- i) Complete date: YYYY-MM-DD (eg 1997-07-16)
+``<container>``
+ Name of container to upload to.
- ii) Complete date plus hours, minutes and seconds:
- YYYY-MM-DDThh:mm:ss
- (eg 1997-07-16T19:20:30)
+``<file_or_directory>``
+ Name of file or directory to upload. Specify multiple
+ times for multiple uploads.
- iii) Complete date plus hours, minutes and seconds with UTC designator:
- YYYY-MM-DDThh:mm:ssZ
- (eg 1997-07-16T19:20:30Z)
+**Optional arguments:**
- Please be aware that if you don't provide the UTC designator (i.e., Z)
- the timestamp is generated using your local timezone. If only a date is
- specified, the time part used will equal to ``00:00:00``.
+``-c, --changed``
+ Only upload files that have changed since the last
+ upload.
- ``path`` option sets the full path to the Swift object.
- Example: ``/v1/AUTH_account/c/o``. ``key`` option is
- the secret temporary URL key set on the Swift cluster. To set a key, run
- ``swift post -m "Temp-URL-Key: <your secret key>"``. To generate a prefix-based temporary
- URL use the ``--prefix-based`` option. This URL will contain the path to the prefix. Do not
- forget to append the desired objectname at the end of the path portion (and before the
- query portion) before sharing the URL. It is possible to use ISO 8601 UTC timestamps within the
- URL by using the ``--iso8601`` option.
+``--skip-identical``
+ Skip uploading files that are identical on both sides.
-Auth
-----
+``-S, --segment-size <size>``
+ Upload files in segments no larger than <size> (in
+ Bytes) and then create a "manifest" file that will
+ download all the segments as if it were the original
+ file.
+
+``--segment-container <container>``
+ Upload the segments into the specified container. If
+ not specified, the segments will be uploaded to a
+ <container>_segments container to not pollute the
+ main <container> listings.
+
+``--leave-segments``
+ Indicates that you want the older segments of manifest
+ objects left alone (in the case of overwrites).
+
+``--object-threads <threads>``
+ Number of threads to use for uploading full objects.
+ Default is 10.
+
+``--segment-threads <threads>``
+ Number of threads to use for uploading object segments.
+ Default is 10.
+
+``-H, --header <header:value>``
+ Adds a customized request header. This option may be
+ repeated. Example: -H "content-type:text/plain"
+ -H "Content-Length: 4000".
+
+``--use-slo``
+ When used in conjunction with --segment-size it will
+ create a Static Large Object instead of the default
+ Dynamic Large Object.
+
+``--object-name <object-name>``
+ Upload file and name object to <object-name> or upload
+ dir and use <object-name> as object prefix instead of
+ folder name.
+
+``--ignore-checksum``
+ Turn off checksum validation for uploads.
+
+
+.. _swift_post:
+
+swift post
+----------
+
+.. code-block:: console
+
+ Usage: swift post [--read-acl <acl>] [--write-acl <acl>] [--sync-to]
+ [--sync-key <sync-key>] [--meta <name:value>]
+ [--header <header>]
+ [<container> [<object>]]
+
+Updates meta information for the account, container, or object depending
+on the arguments given. If the container is not found, the ``swiftclient``
+will create it automatically, but this is not true for accounts and
+objects. Containers also allow the ``-r <read-acl>`` (or ``--read-acl
+<read-acl>``) and ``-w <write-acl>`` (or ``--write-acl <write-acl>``) options.
+The ``-m`` or ``--meta`` option is allowed on accounts, containers and objects,
+and is used to define the user metadata items to set in the form ``Name:Value``.
+You can repeat this option. For example: ``post -m Color:Blue -m Size:Large``
+
+For more information about ACL formats see the documentation:
+`ACLs <http://docs.openstack.org/developer/swift/misc.html#acls/>`_.
+
+**Positional arguments:**
+
+``[container]``
+ Name of container to post to.
+
+``[object]``
+ Name of object to post.
+
+**Optional arguments:**
+
+``-r, --read-acl <acl>``
+ Read ACL for containers. Quick summary of ACL syntax:
+ ``.r:*``, ``.r:-.example.com``, ``.r:www.example.com``,
+ ``account1`` (v1.0 identity API only),
+ ``account1:*``, ``account2:user2`` (v2.0+ identity API).
+
+``-w, --write-acl <acl>``
+ Write ACL for containers. Quick summary of ACL syntax:
+ ``account1`` (v1.0 identity API only),
+ ``account1:*``, ``account2:user2`` (v2.0+ identity API).
+
+``-t, --sync-to <sync-to>``
+ Sync To for containers, for multi-cluster replication.
+
+``-k, --sync-key <sync-key>``
+ Sync Key for containers, for multi-cluster replication.
+
+``-m, --meta <name:value>``
+ Sets a meta data item. This option may be repeated.
+
+ Example: -m Color:Blue -m Size:Large
+
+``-H, --header <header:value>``
+ Adds a customized request header.
+ This option may be repeated.
+
+ Example: -H "content-type:text/plain" -H "Content-Length: 4000"
+
+.. _swift_download:
+
+swift download
+--------------
+
+.. code-block:: console
+
+ Usage: swift download [--all] [--marker <marker>] [--prefix <prefix>]
+ [--output <out_file>] [--output-dir <out_directory>]
+ [--object-threads <threads>] [--ignore-checksum]
+ [--container-threads <threads>] [--no-download]
+ [--skip-identical] [--remove-prefix]
+ [--header <header:value>] [--no-shuffle]
+ [<container> [<object>] [...]]
+
+Downloads everything in the account (with ``--all``), or everything in a
+container, or a list of objects depending on the arguments given. For a
+single object download, you may use the ``-o <filename>`` or ``--output <filename>``
+option to redirect the output to a specific file or ``-`` to
+redirect to stdout. The ``--ignore-checksum`` is an option that turn off
+checksum validation. You can specify optional headers with the repeatable
+cURL-like option ``-H [--header <name:value>]``. ``--ignore-mtime`` ignores the
+``x-object-meta-mtime`` metadata entry on the object (if present) and instead
+creates the downloaded files with fresh atime and mtime values.
+
+**Positional arguments:**
+
+``<container>``
+ Name of container to download from. To download a
+ whole account, omit this and specify --all.
+
+``<object>``
+ Name of object to download. Specify multiple times
+ for multiple objects. Omit this to download all
+ objects from the container.
+
+**Optional arguments:**
+
+``-a, --all``
+ Indicates that you really want to download
+ everything in the account.
+
+``-m, --marker <marker>``
+ Marker to use when starting a container or account
+ download.
+
+``-p, --prefix <prefix>``
+ Only download items beginning with <prefix>
+
+``-r, --remove-prefix``
+ An optional flag for --prefix <prefix>, use this
+ option to download items without <prefix>
+
+``-o, --output <out_file>``
+ For a single file download, stream the output to
+ <out_file>. Specifying "-" as <out_file> will
+ redirect to stdout.
+
+``-D, --output-dir <out_directory>``
+ An optional directory to which to store objects.
+ By default, all objects are recreated in the current
+ directory.
+
+``--object-threads <threads>``
+ Number of threads to use for downloading objects.
+ Default is 10.
+
+``--container-threads <threads>``
+ Number of threads to use for downloading containers.
+ Default is 10.
+
+``--no-download``
+ Perform download(s), but don't actually write anything
+ to disk.
+
+``-H, --header <header:value>``
+ Adds a customized request header to the query, like
+ "Range" or "If-Match". This option may be repeated.
+
+ Example: --header "content-type:text/plain"
+
+``--skip-identical``
+ Skip downloading files that are identical on both
+ sides.
+
+``--ignore-checksum``
+ Turn off checksum validation for downloads.
+
+``--no-shuffle``
+ By default, when downloading a complete account or
+ container, download order is randomised in order to
+ reduce the load on individual drives when multiple
+ clients are executed simultaneously to download the
+ same set of objects (e.g. a nightly automated download
+ script to multiple servers). Enable this option to
+ submit download jobs to the thread pool in the order
+ they are listed in the object store.
+
+.. _swift_delete:
+
+swift delete
+------------
+
+.. code-block:: console
+
+ Usage: swift delete [--all] [--leave-segments]
+ [--object-threads <threads>]
+ [--container-threads <threads>]
+ [--header <header:value>]
+ [<container> [<object>] [...]]
+
+Deletes everything in the account (with ``--all``), or everything in a
+container, or a list of objects depending on the arguments given. Segments
+of manifest objects will be deleted as well, unless you specify the
+``--leave-segments`` option.
+
+**Positional arguments:**
+
+``[<container>]``
+ Name of container to delete from.
+
+``[<object>]``
+ Name of object to delete. Specify multiple times
+ for multiple objects.
+
+**Optional arguments:**
+
+``-a, --all``
+ Delete all containers and objects.
+
+``--leave-segments``
+ Do not delete segments of manifest objects.
+
+``-H, --header <header:value>``
+ Adds a custom request header to use for deleting
+ objects or an entire container.
+
+
+``--object-threads <threads>``
+ Number of threads to use for deleting objects.
+ Default is 10.
+
+``--container-threads <threads>``
+ Number of threads to use for deleting containers.
+ Default is 10.
+
+.. _swift_copy:
+
+swift copy
+----------
+
+.. code-block:: console
+
+ Usage: swift copy [--destination </container/object>] [--fresh-metadata]
+ [--meta <name:value>] [--header <header>] <container>
+ <object> [<object>] [...]
+
+Copies an object to a new destination or adds user metadata to an object. Depending
+on the options supplied, you can preserve existing metadata in contrast to the post
+command. The ``--destination`` option sets the copy target destination in the form
+``/container/object``. If not set, the object will be copied onto itself which is useful
+for adding metadata. You can use the ``-M`` or ``--fresh-metadata`` option to copy
+an object without existing user meta data, and the ``-m`` or ``--meta`` option
+to define user meta data items to set in the form ``Name:Value``. You can repeat
+this option. For example: ``copy -m Color:Blue -m Size:Large``.
+
+**Positional arguments:**
+
+``<container>``
+ Name of container to copy from.
+
+``<object>``
+ Name of object to copy. Specify multiple times for multiple objects
+
+**Optional arguments:**
+
+``-d, --destination </container[/object]>``
+ The container and name of the destination object. Name
+ of destination object can be omitted, then will be
+ same as name of source object. Supplying multiple
+ objects and destination with object name is invalid.
+
+``-M, --fresh-metadata``
+ Copy the object without any existing metadata,
+ If not set, metadata will be preserved or appended
+
+``-m, --meta <name:value>``
+ Sets a meta data item. This option may be repeated.
+
+ Example: -m Color:Blue -m Size:Large
+
+``-H, --header <header:value>``
+ Adds a customized request header. This option may be repeated.
+
+ Example: -H "content-type:text/plain" -H "Content-Length: 4000"
+
+.. _swift_capabilities:
+
+swift capabilities
+------------------
+
+.. code-block:: console
+
+ Usage: swift capabilities [--json] [<proxy_url>]
+
+Displays cluster capabilities. The output includes the list of the
+activated Swift middlewares as well as relevant options for each ones.
+Additionally the command displays relevant options for the Swift core. If
+the ``proxy-url`` option is not provided, the storage URL retrieved after
+authentication is used as ``proxy-url``.
+
+**Optional positional arguments:**
+
+``<proxy_url>``
+ Proxy URL of the cluster to retrieve capabilities.
+
+``--json``
+ Print the cluster capabilities in JSON format.
+
+.. _swift_tempurl:
+
+swift tempurl
+-------------
+
+.. code-block:: console
+
+ Usage: swift tempurl [--absolute] [--prefix-based]
+ <method> <seconds> <path> <key>
+
+Generates a temporary URL for a Swift object. ``method`` option sets an HTTP method to
+allow for this temporary URL that is usually ``GET`` or ``PUT``. ``time`` option sets
+the amount of time the temporary URL will be valid for.
+``time`` can be specified as an integer, denoting the number of seconds
+from now on until the URL shall be valid; or, if ``--absolute``
+is passed, the Unix timestamp when the temporary URL will expire.
+But beyond that, ``time`` can also be specified as an ISO 8601 timestamp
+in one of following formats:
+
+ i) Complete date: YYYY-MM-DD (eg 1997-07-16)
+
+ ii) Complete date plus hours, minutes and seconds:
+ YYYY-MM-DDThh:mm:ss
+ (eg 1997-07-16T19:20:30)
+
+ iii) Complete date plus hours, minutes and seconds with UTC designator:
+ YYYY-MM-DDThh:mm:ssZ
+ (eg 1997-07-16T19:20:30Z)
+
+Please be aware that if you don't provide the UTC designator (i.e., Z)
+the timestamp is generated using your local timezone. If only a date is
+specified, the time part used will equal to ``00:00:00``.
+
+``path`` option sets the full path to the Swift object.
+Example: ``/v1/AUTH_account/c/o``. ``key`` option is
+the secret temporary URL key set on the Swift cluster. To set a key, run
+``swift post -m "Temp-URL-Key: <your secret key>"``. To generate a prefix-based temporary
+URL use the ``--prefix-based`` option. This URL will contain the path to the prefix. Do not
+forget to append the desired objectname at the end of the path portion (and before the
+query portion) before sharing the URL. It is possible to use ISO 8601 UTC timestamps within the
+URL by using the ``--iso8601`` option.
+
+**Positional arguments:**
+
+``<method>``
+ An HTTP method to allow for this temporary URL.
+ Usually 'GET' or 'PUT'.
+
+``<seconds>``
+ The amount of time in seconds the temporary URL will be
+ valid for; or, if --absolute is passed, the Unix
+ timestamp when the temporary URL will expire.
+
+``<path>``
+ The full path to the Swift object.
+
+ Example: /v1/AUTH_account/c/o
+ or: http://saio:8080/v1/AUTH_account/c/o
+
+``<key>``
+ The secret temporary URL key set on the Swift cluster.
+ To set a key, run 'swift post -m
+ "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"'
+
+**Optional arguments:**
- ``auth``
+``--absolute``
+ Interpret the <seconds> positional argument as a Unix
+ timestamp rather than a number of seconds in the
+ future.
- Display authentication variables in shell friendly format. Command to run to export storage
- URL and auth token into ``OS_STORAGE_URL`` and ``OS_AUTH_TOKEN``: ``swift auth``.
- Command to append to a runcom file (e.g. ``~/.bashrc``, ``/etc/profile``) for automatic
- authentication: ``swift auth -v -U test:tester -K testing``.
+``--prefix-based``
+ If present, a prefix-based tempURL will be generated.
Examples
~~~~~~~~