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 2.2.0.
    </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-tenant-id &lt;auth-tenant-id&gt;]
             [--os-tenant-name &lt;auth-tenant-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]</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>
 </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-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>-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>--os-username=&lt;auth-user-name&gt;</command></term>
    <listitem>
      <para>
      OpenStack username. Defaults to <code>env[OS_USERNAME]</code>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-password=&lt;auth-password&gt;</command></term>
    <listitem>
      <para>
      OpenStack password. Defaults to <code>env[OS_PASSWORD]</code>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-tenant-id=&lt;auth-tenant-id&gt;</command></term>
    <listitem>
      <para>
      OpenStack tenant ID. Defaults to <code>env[OS_TENANT_ID]</code>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-tenant-name=&lt;auth-tenant-name&gt;</command></term>
    <listitem>
      <para>
      OpenStack tenant name. Defaults to
      <code>env[OS_TENANT_NAME]</code>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-auth-url=&lt;auth-url&gt;</command></term>
    <listitem>
      <para>
      OpenStack auth URL. Defaults to <code>env[OS_AUTH_URL]</code>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-auth-token=&lt;auth-token&gt;</command></term>
    <listitem>
      <para>
      OpenStack token. Defaults to <code>env[OS_AUTH_TOKEN]</code>. Used
      with --os-storage-url to bypass the usual
      username/password authentication.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-storage-url=&lt;storage-url&gt;</command></term>
    <listitem>
      <para>
      OpenStack storage URL. Defaults to
      <code>env[OS_STORAGE_URL]</code>. Overrides the storage url
      returned during auth. Will bypass authentication when
      used with --os-auth-token.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-region-name=&lt;region-name&gt;</command></term>
    <listitem>
      <para>
      OpenStack region name. Defaults to
      <code>env[OS_REGION_NAME]</code>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-service-type=&lt;service-type&gt;</command></term>
    <listitem>
      <para>
      OpenStack Service type. Defaults to
      <code>env[OS_SERVICE_TYPE]</code>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-endpoint-type=&lt;endpoint-type&gt;</command></term>
    <listitem>
      <para>
      OpenStack Endpoint type. Defaults to
      <code>env[OS_ENDPOINT_TYPE]</code>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--os-cacert=&lt;ca-certificate&gt;</command></term>
    <listitem>
      <para>
      Specify a CA bundle file to use in verifying a TLS
      (https) server certificate. Defaults to
      <code>env[OS_CACERT]</code>.
      </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_delete">
        <title>swift delete command</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>--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 command</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>[object]</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>--all</command></term>
    <listitem>
      <para>
        Indicates that you really want to download everything
      in the account.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--marker</command></term>
    <listitem>
      <para>
        Marker to use when starting a container or account
      download.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--prefix &lt;prefix&gt;</command></term>
    <listitem>
      <para>
        Only download items beginning with &lt;prefix&gt;.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--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>--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>--header &lt;header_name:header_value&gt;</command></term>
    <listitem>
      <para>
      Adds a customized request header to the query, like
      "Range" or "If-Match". This argument is repeatable.
      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>
 </variablelist>
    </section>
    <section xml:id="swiftclient_subcommand_list">
        <title>swift list command</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>--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>--totals</command></term>
    <listitem>
      <para>
        Used with -l or --lh, only report totals.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--prefix</command></term>
    <listitem>
      <para>
        Only list items beginning with the prefix.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--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 command</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. Specify multiple times
      for multiple objects.
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
  <variablelist wordsize="10">
    <title>Optional arguments</title>
  <varlistentry>
    <term><command>--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>--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>--sync-to &lt;sync-to&gt;</command></term>
    <listitem>
      <para>
        Sync To for containers, for multi-cluster replication.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--sync-key &lt;sync-key&gt;</command></term>
    <listitem>
      <para>
        Sync Key for containers, for multi-cluster replication.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>--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>--header &lt;header&gt;</command></term>
    <listitem>
      <para>
        Set request headers. This option may be repeated.
      Example -H "content-type:text/plain"
      </para>
    </listitem>
  </varlistentry>
 </variablelist>
    </section>
    <section xml:id="swiftclient_subcommand_stat">
        <title>swift stat command</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. Specify multiple times
      for multiple objects.
      </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_upload">
        <title>swift upload command</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>--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>--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>--header &lt;header&gt;</command></term>
    <listitem>
      <para>
        Set request headers with the syntax header:value.
      This option may be repeated.
      Example -H "content-type:text/plain".
      </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>
 </variablelist>
    </section>
</chapter>