openstack-manuals/doc/cli-reference/generated/ch_cli_swift_commands.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  version="5.0"
  xml:id="swiftclient_commands">

    <!-- This file is automatically generated, do not edit -->

    <?dbhtml stop-chunking?>

    <title>Object Storage command-line client</title>

    <para>The <command>swift</command> client is the command-line
        interface (CLI) for the OpenStack Object Storage API and its extensions.

       This chapter documents <command>swift</command> version
        <literal>2.6.0</literal>.
    </para>

    <para>For help on a specific <command>swift</command>
       command, enter:
    </para>
    <screen><prompt>$</prompt> <userinput><command>swift</command> <replaceable>COMMAND</replaceable> <option>--help</option></userinput></screen>

    <section xml:id="swiftclient_command_usage">
       <title>swift usage</title>
        <screen><computeroutput>             [--debug] [--info] [--quiet] [--auth &lt;auth_url&gt;]
             [--auth-version &lt;auth_version&gt;] [--user &lt;username&gt;]
             [--key &lt;api_key&gt;] [--retries &lt;num_retries&gt;]
             [--os-username &lt;auth-user-name&gt;] [--os-password &lt;auth-password&gt;]
             [--os-user-id &lt;auth-user-id&gt;]
             [--os-user-domain-id &lt;auth-user-domain-id&gt;]
             [--os-user-domain-name &lt;auth-user-domain-name&gt;]
             [--os-tenant-id &lt;auth-tenant-id&gt;]
             [--os-tenant-name &lt;auth-tenant-name&gt;]
             [--os-project-id &lt;auth-project-id&gt;]
             [--os-project-name &lt;auth-project-name&gt;]
             [--os-project-domain-id &lt;auth-project-domain-id&gt;]
             [--os-project-domain-name &lt;auth-project-domain-name&gt;]
             [--os-auth-url &lt;auth-url&gt;] [--os-auth-token &lt;auth-token&gt;]
             [--os-storage-url &lt;storage-url&gt;] [--os-region-name &lt;region-name&gt;]
             [--os-service-type &lt;service-type&gt;]
             [--os-endpoint-type &lt;endpoint-type&gt;]
             [--os-cacert &lt;ca-certificate&gt;] [--insecure]
             [--no-ssl-compression]
             &lt;subcommand&gt; [--help] [&lt;subcommand options&gt;]</computeroutput></screen>
  <variablelist wordsize="10">
    <title>Subcommands</title>
  <varlistentry>
    <term><command>delete</command></term>
    <listitem>
      <para>
        Delete a container or objects within a container.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>download</command></term>
    <listitem>
      <para>
        Download objects from containers.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>list</command></term>
    <listitem>
      <para>
        Lists the containers for the account or the objects
      for a container.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>post</command></term>
    <listitem>
      <para>
        Updates meta information for the account, container,
      or object; creates containers if not present.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>stat</command></term>
    <listitem>
      <para>
        Displays information for the account, container,
      or object.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>upload</command></term>
    <listitem>
      <para>
        Uploads files or directories to the given container.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>capabilities</command></term>
    <listitem>
      <para>
        List cluster capabilities.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>tempurl</command></term>
    <listitem>
      <para>
        Create a temporary URL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>auth</command></term>
    <listitem>
      <para>
        Display auth related environment variables.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
    <section xml:id="swiftclient_command_examples">
        <title>swift examples</title>
        <screen><computeroutput>  swift download --help
  swift -A https://auth.api.rackspacecloud.com/v1.0 -U user -K api_key stat -v
  swift --os-auth-url https://api.example.com/v2.0 --os-tenant-name tenant \
      --os-username user --os-password password list
  swift --os-auth-url https://api.example.com/v3 --auth-version 3\
      --os-project-name project1 --os-project-domain-name domain1 \
      --os-username user --os-user-domain-name domain1 \
      --os-password password list
  swift --os-auth-url https://api.example.com/v3 --auth-version 3\
      --os-project-id 0123456789abcdef0123456789abcdef \
      --os-user-id abcdef0123456789abcdef0123456789 \
      --os-password password list
  swift --os-auth-token 6ee5eb33efad4e45ab46806eac010566 \
      --os-storage-url https://10.1.5.2:8080/v1/AUTH_ced809b6a4baea7aeab61a \
      list
  swift list --lh</computeroutput></screen>
    </section>
    <section xml:id="swiftclient_command_optional">
        <title>swift optional arguments</title>
  <variablelist wordsize="10">
  <varlistentry>
    <term><command>--version</command></term>
    <listitem>
      <para>
        show program's version number and exit
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-h, --help</command></term>
    <listitem>
      <para>
        show this help message and exit
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-help</command></term>
    <listitem>
      <para>
        Show OpenStack authentication options.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-s, --snet</command></term>
    <listitem>
      <para>
        Use SERVICENET internal network.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-v, --verbose</command></term>
    <listitem>
      <para>
        Print more info.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--debug</command></term>
    <listitem>
      <para>
        Show the curl commands and results of all http queries
      regardless of result status.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--info</command></term>
    <listitem>
      <para>
        Show the curl commands and results of all http queries
      which return an error.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-q, --quiet</command></term>
    <listitem>
      <para>
        Suppress status output.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-A AUTH, --auth=AUTH URL</command></term>
    <listitem>
      <para>
        for obtaining an auth token.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-V AUTH_VERSION, --auth-version=AUTH_VERSION</command></term>
    <listitem>
      <para>
      Specify a version for authentication. Defaults to 1.0.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-U USER, --user=USER</command></term>
    <listitem>
      <para>
        User name for obtaining an auth token.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-K KEY, --key=KEY</command></term>
    <listitem>
      <para>
        Key for obtaining an auth token.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-R RETRIES, --retries=RETRIES</command></term>
    <listitem>
      <para>
      The number of times to retry a failed connection.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--insecure</command></term>
    <listitem>
      <para>
        Allow swiftclient to access servers without having to
      verify the SSL certificate. Defaults to
      <code>env[SWIFTCLIENT_INSECURE]</code> (set to 'true' to enable).
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--no-ssl-compression</command></term>
    <listitem>
      <para>
        This option is deprecated and not used anymore. SSL
      compression should be disabled by default by the
      system SSL library.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
    <section xml:id="swiftclient_subcommand_capabilities">
        <title>swift capabilities</title>

        <screen><computeroutput>Usage: swift capabilities</computeroutput></screen>
        <para>
Retrieve capability of the proxy.
Optional positional arguments:
  &lt;proxy_url&gt;           Proxy URL of the cluster to retrieve capabilities.
        </para>
    </section>
    <section xml:id="swiftclient_subcommand_delete">
        <title>swift delete</title>

        <screen><computeroutput>Usage: swift delete</computeroutput></screen>
        <para>
Delete a container or objects within a container.
        </para>  <variablelist wordsize="10">
    <title>Positional arguments</title>
  <varlistentry>
    <term><command>&lt;container&gt;</command></term>
    <listitem>
      <para>
        Name of container to delete from.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>[object]</command></term>
    <listitem>
      <para>
        Name of object to delete. Specify multiple times
      for multiple objects.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
  <variablelist wordsize="10">
    <title>Optional arguments</title>
  <varlistentry>
    <term><command>-a, --all</command></term>
    <listitem>
      <para>
        Delete all containers and objects.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--leave-segments</command></term>
    <listitem>
      <para>
        Do not delete segments of manifest objects.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--object-threads &lt;threads&gt;</command></term>
    <listitem>
      <para>
      Number of threads to use for deleting objects.
      Default is 10.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--container-threads &lt;threads&gt;</command></term>
    <listitem>
      <para>
      Number of threads to use for deleting containers.
      Default is 10.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
    <section xml:id="swiftclient_subcommand_download">
        <title>swift download</title>

        <screen><computeroutput>Usage: swift download</computeroutput></screen>
        <para>
Download objects from containers.
        </para>  <variablelist wordsize="10">
    <title>Positional arguments</title>
  <varlistentry>
    <term><command>&lt;container&gt;</command></term>
    <listitem>
      <para>
        Name of container to download from. To download a
      whole account, omit this and specify --all.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>&lt;object&gt;</command></term>
    <listitem>
      <para>
        Name of object to download. Specify multiple times
      for multiple objects. Omit this to download all
      objects from the container.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
  <variablelist wordsize="10">
    <title>Optional arguments</title>
  <varlistentry>
    <term><command>-a, --all</command></term>
    <listitem>
      <para>
        Indicates that you really want to download
      everything in the account.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-m, --marker</command></term>
    <listitem>
      <para>
        Marker to use when starting a container or account
      download.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-p, --prefix &lt;prefix&gt;</command></term>
    <listitem>
      <para>
        Only download items beginning with &lt;prefix&gt;
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-r, --remove-prefix</command></term>
    <listitem>
      <para>
        An optional flag for --prefix &lt;prefix&gt;, use this
      option to download items without &lt;prefix&gt;
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-o, --output &lt;out_file&gt;</command></term>
    <listitem>
      <para>
      For a single file download, stream the output to
      &lt;out_file&gt;. Specifying "-" as &lt;out_file&gt; will
      redirect to stdout.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-D, --output-dir &lt;out_directory&gt;</command></term>
    <listitem>
      <para>
      An optional directory to which to store objects.
      By default, all objects are recreated in the current
      directory.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--object-threads &lt;threads&gt;</command></term>
    <listitem>
      <para>
      Number of threads to use for downloading objects.
      Default is 10.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--container-threads &lt;threads&gt;</command></term>
    <listitem>
      <para>
      Number of threads to use for downloading containers.
      Default is 10.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--no-download</command></term>
    <listitem>
      <para>
        Perform download(s), but don't actually write anything
      to disk.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-H, --header &lt;header:value&gt;</command></term>
    <listitem>
      <para>
      Adds a customized request header to the query, like
      "Range" or "If-Match". This option may be repeated.
      Example --header "content-type:text/plain"
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--skip-identical</command></term>
    <listitem>
      <para>
        Skip downloading files that are identical on both
      sides.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--no-shuffle</command></term>
    <listitem>
      <para>
        By default, when downloading a complete account or
      container, download order is randomised in order to
      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.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
    <section xml:id="swiftclient_subcommand_list">
        <title>swift list</title>

        <screen><computeroutput>Usage: swift list</computeroutput></screen>
        <para>
Lists the containers for the account or the objects for a container.
        </para>  <variablelist wordsize="10">
    <title>Positional arguments</title>
  <varlistentry>
    <term><command>[container]</command></term>
    <listitem>
      <para>
        Name of container to list object in.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
  <variablelist wordsize="10">
    <title>Optional arguments</title>
  <varlistentry>
    <term><command>-l, --long</command></term>
    <listitem>
      <para>
        Long listing format, similar to ls -l.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--lh</command></term>
    <listitem>
      <para>
        Report sizes in human readable format similar to
      ls -lh.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-t, --totals</command></term>
    <listitem>
      <para>
        Used with -l or --lh, only report totals.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-p, --prefix</command></term>
    <listitem>
      <para>
        Only list items beginning with the prefix.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-d, --delimiter</command></term>
    <listitem>
      <para>
        Roll up items with the given delimiter. For containers
      only. See OpenStack Swift API documentation for what
      this means.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
    <section xml:id="swiftclient_subcommand_post">
        <title>swift post</title>

        <screen><computeroutput>Usage: swift post</computeroutput></screen>
        <para>
Updates meta information for the account, container, or object.
If the container is not found, it will be created automatically.
        </para>  <variablelist wordsize="10">
    <title>Positional arguments</title>
  <varlistentry>
    <term><command>[container]</command></term>
    <listitem>
      <para>
        Name of container to post to.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>[object]</command></term>
    <listitem>
      <para>
        Name of object to post.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
  <variablelist wordsize="10">
    <title>Optional arguments</title>
  <varlistentry>
    <term><command>-r, --read-acl &lt;acl&gt;</command></term>
    <listitem>
      <para>
        Read ACL for containers. Quick summary of ACL syntax:
      .r:*, .r:-.example.com, .r:www.example.com, account1,
      account2:user2
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-w, --write-acl &lt;acl&gt;</command></term>
    <listitem>
      <para>
        Write ACL for containers. Quick summary of ACL syntax:
      account1 account2:user2
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-t, --sync-to &lt;sync-to&gt;</command></term>
    <listitem>
      <para>
      Sync To for containers, for multi-cluster replication.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-k, --sync-key &lt;sync-key&gt;</command></term>
    <listitem>
      <para>
      Sync Key for containers, for multi-cluster replication.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-m, --meta &lt;name:value&gt;</command></term>
    <listitem>
      <para>
      Sets a meta data item. This option may be repeated.
      Example: -m Color:Blue -m Size:Large
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-H, --header &lt;header:value&gt;</command></term>
    <listitem>
      <para>
      Adds a customized request header.
      This option may be repeated. Example
      -H "content-type:text/plain" -H "Content-Length: 4000"
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
    <section xml:id="swiftclient_subcommand_stat">
        <title>swift stat</title>

        <screen><computeroutput>Usage: swift stat</computeroutput></screen>
        <para>
Displays information for the account, container, or object.
        </para>  <variablelist wordsize="10">
    <title>Positional arguments</title>
  <varlistentry>
    <term><command>[container]</command></term>
    <listitem>
      <para>
        Name of container to stat from.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>[object]</command></term>
    <listitem>
      <para>
        Name of object to stat.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
  <variablelist wordsize="10">
    <title>Optional arguments</title>
  <varlistentry>
    <term><command>--lh</command></term>
    <listitem>
      <para>
        Report sizes in human readable format similar to
      ls -lh.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
    <section xml:id="swiftclient_subcommand_tempurl">
        <title>swift tempurl</title>

        <screen><computeroutput>Usage: swift tempurl</computeroutput></screen>
        <para>
Generates a temporary URL for a Swift object.
        </para>  <variablelist wordsize="10">
    <title>Positional arguments</title>
  <varlistentry>
    <term><command>&lt;method&gt;</command></term>
    <listitem>
      <para>
        An HTTP method to allow for this temporary URL.
      Usually 'GET' or 'PUT'.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>&lt;seconds&gt;</command></term>
    <listitem>
      <para>
        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.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>&lt;path&gt;</command></term>
    <listitem>
      <para>
        The full path to the Swift object. Example:
      /v1/AUTH_account/c/o.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>&lt;key&gt;</command></term>
    <listitem>
      <para>
        The secret temporary URL key set on the Swift cluster.
      To set a key, run 'swift post -m
      "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"'
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
  <variablelist wordsize="10">
    <title>Optional arguments</title>
  <varlistentry>
    <term><command>--absolute</command></term>
    <listitem>
      <para>
        Interpet the &lt;seconds&gt; positional argument as a Unix
      timestamp rather than a number of seconds in the
      future.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
    <section xml:id="swiftclient_subcommand_upload">
        <title>swift upload</title>

        <screen><computeroutput>Usage: swift upload</computeroutput></screen>
        <para>
 Uploads specified files and directories to the given container.
        </para>  <variablelist wordsize="10">
    <title>Positional arguments</title>
  <varlistentry>
    <term><command>&lt;container&gt;</command></term>
    <listitem>
      <para>
        Name of container to upload to.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>&lt;file_or_directory&gt;</command></term>
    <listitem>
      <para>
        Name of file or directory to upload. Specify multiple
      times for multiple uploads.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
  <variablelist wordsize="10">
    <title>Optional arguments</title>
  <varlistentry>
    <term><command>-c, --changed</command></term>
    <listitem>
      <para>
        Only upload files that have changed since the last
      upload.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--skip-identical</command></term>
    <listitem>
      <para>
        Skip uploading files that are identical on both sides.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-S, --segment-size &lt;size&gt;</command></term>
    <listitem>
      <para>
      Upload files in segments no larger than &lt;size&gt; (in
      Bytes) and then create a "manifest" file that will
      download all the segments as if it were the original
      file.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--segment-container &lt;container&gt;</command></term>
    <listitem>
      <para>
      Upload the segments into the specified container. If
      not specified, the segments will be uploaded to a
      &lt;container&gt;_segments container to not pollute the
      main &lt;container&gt; listings.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--leave-segments</command></term>
    <listitem>
      <para>
        Indicates that you want the older segments of manifest
      objects left alone (in the case of overwrites).
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--object-threads &lt;threads&gt;</command></term>
    <listitem>
      <para>
      Number of threads to use for uploading full objects.
      Default is 10.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--segment-threads &lt;threads&gt;</command></term>
    <listitem>
      <para>
      Number of threads to use for uploading object segments.
      Default is 10.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-H, --header &lt;header:value&gt;</command></term>
    <listitem>
      <para>
      Adds a customized request header. This option may be
      repeated. Example -H "content-type:text/plain"
      -H "Content-Length: 4000".
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--use-slo</command></term>
    <listitem>
      <para>
        When used in conjunction with --segment-size it will
      create a Static Large Object instead of the default
      Dynamic Large Object.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--object-name &lt;object-name&gt;</command></term>
    <listitem>
      <para>
      Upload file and name object to &lt;object-name&gt; or upload
      dir and use &lt;object-name&gt; as object prefix instead of
      folder name.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--ignore-checksum</command></term>
    <listitem>
      <para>
        Turn off checksum validation for uploads.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
</chapter>