merged openstack-manuals content with existing content

Change-Id: I05bc8f80daefbb32f32727550a9cbe43e9754e2f

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,19 +252,61 @@ storage URL options shown below:
 CLI commands
 ~~~~~~~~~~~~
 
-Stat
+.. _swift_auth:
+
+Auth
 ----
 
-    ``stat [container [object]]``
+.. code-block:: console
+
+   Usage: swift auth
+
+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``.
+
+.. _swift_stat:
+
+swift stat
+----------
+
+.. code-block:: console
+
+   Usage: swift stat [--lh] [--header <header:value>]
+                     [<container> [<object>]]
 
 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.
 
-List
+**Positional arguments:**
-----
 
-    ``list [command-options] [container]``
+``[container]``
+  Name of container to stat from.
+
+``[object]``
+  Name of object to stat.
+
+**Optional arguments:**
+
+``--lh``
+  Report sizes in human readable format similar to
+  ls -lh.
+
+``-H, --header <header:value>``
+  Adds a custom request header to use for stat.
+
+.. _swift_list:
+
+swift list
+----------
+
+.. code-block:: console
+
+   Usage: swift list [--long] [--lh] [--totals] [--prefix <prefix>]
+                     [--delimiter <delimiter>] [--header <header:value>]
+                     [<container>]
 
 Lists the containers for the account or the objects for a container.
 The ``-p <prefix>`` or ``--prefix <prefix>`` is an option that will only
@@ -147,10 +322,47 @@ List
 overhead to retrieve the displayed details, which is directly proportional
 to the number of container or objects listed.
 
-Upload
+**Positional arguments:**
-------
 
-    ``upload [command-options] container file_or_directory [file_or_directory] [...]``
+``[container]``
+  Name of container to list object in.
+
+**Optional arguments:**
+
+``-l, --long``
+  Long listing format, similar to ls -l.
+
+``--lh``
+  Report sizes in human readable format similar to
+  ls -lh.
+
+``-t, --totals``
+  Used with -l or --lh, only report totals.
+
+``-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
+------------
+
+.. code-block:: console
+
+   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>] [...]
 
 Uploads the files and directories specified by the remaining arguments to the
 given container. The ``-c`` or ``--changed`` is an option that will only
@@ -160,10 +372,80 @@ Upload
 as object prefix. The ``-S <size>`` or ``--segment-size <size>`` and
 ``--leave-segments`` are options as well (see ``--help`` for more).
 
-Post
+Uploads specified files and directories to the given container.
-----
 
-    ``post [command-options] [container] [object]``
+**Positional arguments:**
+
+``<container>``
+  Name of container to upload to.
+
+``<file_or_directory>``
+  Name of file or directory to upload. Specify multiple
+  times for multiple uploads.
+
+**Optional arguments:**
+
+``-c, --changed``
+  Only upload files that have changed since the last
+  upload.
+
+``--skip-identical``
+  Skip uploading files that are identical on both sides.
+
+``-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``
@@ -177,10 +459,58 @@ Post
 For more information about ACL formats see the documentation:
 `ACLs <http://docs.openstack.org/developer/swift/misc.html#acls/>`_.
 
-Download
+**Positional arguments:**
---------
 
-    ``download [command-options] [container] [object] [object] [...]``
+``[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
@@ -192,20 +522,137 @@ Download
 ``x-object-meta-mtime`` metadata entry on the object (if present) and instead
 creates the downloaded files with fresh atime and mtime values.
 
-Delete
+**Positional arguments:**
-------
 
-    ``delete [command-options] [container] [object] [object] [...]``
+``<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.
 
-Copy
+**Positional arguments:**
-----
 
-    ``copy [command-options] container object``
+``[<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
@@ -216,10 +663,44 @@ Copy
 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``.
 
-Capabilities
+**Positional arguments:**
-------------
 
-    ``capabilities [proxy-url]``
+``<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.
@@ -227,13 +708,26 @@ Capabilities
 the ``proxy-url`` option is not provided, the storage URL retrieved after
 authentication is used as ``proxy-url``.
 
-Tempurl
+**Optional positional arguments:**
--------
 
-    ``tempurl [command-options] [method] [time] [path] [key]``
+``<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
+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``
@@ -264,15 +758,37 @@ Tempurl
 query portion) before sharing the URL. It is possible to use ISO 8601 UTC timestamps within the
 URL by using the ``--iso8601`` option.
 
-Auth
+**Positional arguments:**
-----
 
-    ``auth``
+``<method>``
+  An HTTP method to allow for this temporary URL.
+  Usually 'GET' or 'PUT'.
 
-       Display authentication variables in shell friendly format. Command to run to export storage
+``<seconds>``
-       URL and auth token into ``OS_STORAGE_URL`` and ``OS_AUTH_TOKEN``: ``swift auth``.
+  The amount of time in seconds the temporary URL will be
-       Command to append to a runcom file (e.g. ``~/.bashrc``, ``/etc/profile``) for automatic
+  valid for; or, if --absolute is passed, the Unix
-       authentication: ``swift auth -v -U test:tester -K testing``.
+  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:**
+
+``--absolute``
+  Interpret the <seconds> positional argument as a Unix
+  timestamp rather than a number of seconds in the
+  future.
+
+``--prefix-based``
+  If present, a prefix-based tempURL will be generated.
 
 Examples
 ~~~~~~~~