swift command line tool usage guide

swifttool is a command line tool for communicating with OpenStack Object Storage (swift) environments. It allows people to perform several types of operations.

For help on a specific Swift command, enter:

$swift COMMAND --help

swift usage

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>]

Child instructions:

• delete

  Delete a container or objects within a container.

• download

  Download the object from the container.

• list

  A container or container object that lists accounts.

• post

  Updates metainformation for an account, container, or object; creates the container if it does not exist.

• copy

  Copy the object, optionally adding meta information

• stat

  Displays information about an account, container, or object.

• upload

  Upload a file or directory to the given container.

• capabilities

  List cluster capabilities.

• tempurl

  Create a temporary URL.

• auth

  Displays authentication-related environment variables.

swift optional parameters

• --version

  Display the program version number and exit

• -h, --help

  Show this help message and exit

• --os-help

  Displays OpenStack certification options.

• -s, --snet

  Use SERVICENET internal network.

• -v, --verbose

  Print more information.

• --debug

  Displays the results of curl commands and all http queries, regardless of result status.

• --info

  Displays the results of the curl command and all http queries that returned errors.

• -q, --quiet

  Suppress status output.

• -A AUTH, --auth=AUTH

  Get the URL of the authentication token.

• -V AUTH_VERSION, --auth-version=AUTH_VERSION, --os-identity-api-version=AUTH_VERSION

  Specifies the version used for authentication. Defaults to env[ST_AUTH_VERSION], env[OS_AUTH_VERSION], env[OS_IDENTITY_API_VERSION]or 1.0.

• -U USER, --user=USER

  Get the username of the authentication token. The username is best enclosed in single quotes, this is required when using a Tempauth authenticated tenant.

• -K KEY, --key=KEY

  Get the key for the authentication token.

• -R RETRIES, --retries=RETRIES

  Number of times to retry failed connections.

• --insecure

  Allow swiftclient to access the server without verifying the SSL certificate. Defaults to env[SSWIFTCLIENT_INSECURE](set to trueenabled).

• --no-ssl-compression

  This option is deprecated and is no longer used. By default, the system SSL library should disable SSL compression.

• --prompt

  Prompts the user for a password, which overrides any password provided by --key, or environment variables.--os-password

Certification

This section describes options for authentication with Swift Object Storage. The required combinations of options for each certification version are detailed below, but these are only a subset of the options available for successful certification. These are the most common and recommended combinations.

Details of the certification version and credentials should be obtained from the storage provider. These details will give you a clearer idea of ​​which certification sections below are most likely to allow connections to your storage account.

Keystone v3

swift --os-auth-url https://api.example.com:5000/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:5000/v3 --auth-version 3 \
      --os-project-id 0123456789abcdef0123456789abcdef \
      --os-user-id abcdef0123456789abcdef0123456789 \
      --os-password password list

You can avoid manually specifying the above options on the command line by setting the following combination of environment variables:

ST_AUTH_VERSION=3
OS_USERNAME=user
OS_USER_DOMAIN_NAME=domain1
OS_PASSWORD=password
OS_PROJECT_NAME=project1
OS_PROJECT_DOMAIN_NAME=domain1
OS_AUTH_URL=https://api.example.com:5000/v3

ST_AUTH_VERSION=3
OS_USER_ID=abcdef0123456789abcdef0123456789
OS_PASSWORD=password
OS_PROJECT_ID=0123456789abcdef0123456789abcdef
OS_AUTH_URL=https://api.example.com:5000/v3

Keystone v2

swift --os-auth-url https://api.example.com:5000/v2.0 \
      --os-tenant-name tenant \
      --os-username user --os-password password list

You can avoid manually specifying the above options on the command line by setting the following environment variable:

ST_AUTH_VERSION=2.0
OS_USERNAME=user
OS_PASSWORD=password
OS_TENANT_NAME=tenant
OS_AUTH_URL=https://api.example.com:5000/v2.0

Traditional authentication system

Swift can be configured to work with any number of other authentication systems, which we will not cover in this document. If your storage provider does not provide access tokens with Keystone, contact them for instructions on the options you need. Most likely you will need to specify options as follows:

swift -A https://api.example.com/v1.0 -U user -K api_key list

You can avoid manually specifying the above options on the command line by setting the following environment variable:

ST_AUTH_VERSION=1.0
ST_AUTH=https://api.example.com/v1.0
ST_USER=user
ST_KEY=key

It may also be necessary to use a completely separate authentication system, in which case swiftclientthe token cannot be requested. In this case, a separate authentication request should be made and the storage accessed using the token and storage URL options shown below:

swift --os-auth-token 6ee5eb33efad4e45ab46806eac010566 \
      --os-storage-url https://10.1.5.2:8080/v1/AUTH_ced809b6a4baea7aeab61a \
      list

illustrate

Leftover environment variables are a common cause of confusion when authorization fails.

CLI commands

swift auth

Usage: swift auth

Display authentication variables in shell-friendly format. The command to run will export the storage URL and authentication token OS_storage_URLinto OS_auth_token: swift auth. Command to append to a runcom file (for example ~/.bashrc, /etc/profile) for automatic authentication: swift auth -v -U test:tester -K testing.

swift stat

Usage: swift stat [--lh] [--header <header:value>]
                  [<container> [<object>]]

Displays information for an account, container, or object based on the given parameters (if any). In verbose mode, the storage URL and authentication token are also displayed.

Positional parameters:

• [container]

  The name of the container to take statistics from.

• [object]

  The name of the object to be counted.

Optional parameters:

• --lh

  ls -lhReport size in a human-readable format similar to .

• -H, --header <header:value>

  Add custom request headers for statistics.

swift list

Usage: swift list [--long] [--lh] [--totals] [--prefix <prefix>]
                  [--delimiter <delimiter>] [--header <header:value>]
                  [<container>]

Lists containers in an account or objects within containers. -p <prefix>Or--prefix <prefix> an option to list only items starting with that prefix. -d <delimiter>Or--delimiter <delimiter> an option (only for listing containers) that will aggregate projects using a given delimiter (see the OpenStack Swift general documentation https://docs.openstack.org/swift/latest/ for its meaning).

-lThe and --lhoptions provide more details, similar to ls -lwith ls -lh, which provides the size in a human-readable format (eg: , 3K, 12Metc.). The latter two switches use more overhead to retrieve the displayed details, proportional to the number of containers or objects listed.

Positional parameters:

• [container]

  The name of the container in which the object is to be listed.

Optional parameters:

• -l, --long

  Long list format, similar to ls -l.

• --lh

  ls -lhReport size in a human-readable format similar to .

• -t, --totals

  Used with -lor to report only totals.--lh

• -p <prefix>, --prefix <prefix>

  Only items starting with the prefix are listed.

• -d <delim>, --delimiter <delim>

  Summarizes items using the given delimiter. Applies to containers only. Please refer to the OpenStack Swift API documentation to understand its meaning.

• -H, --header <header:value>

  Add custom request headers for listing.

swift upload

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 parameters to the given container. -cor --changedis an option that will only upload files that have changed since the last upload. --object-name <object-name>is an option to upload a file and use a <object-name>named object or upload a directory and use <object-name>as the object prefix. If the file is named -, the client will read the contents from standard input. In this case, is required --object-nameto set the name of the object, and no other files can be given. -S <size>or --segment-size <size>and --leave-segmentsare also options (see for details --help).

Positional parameters:

• <container>

  The name of the container to upload to.

• <file_or_directory>

  The name of the file or directory to upload. Specify multiple times for multiple uploads.

Optional parameters:

• -c, --changed

  Only upload files that have changed since the last upload.

• --skip-identical

  Skip uploading identical files on both sides.

• -S, --segment-size <size>

  Upload a multipart upload file no larger than (in bytes) and then create a "manifest" file that will download all the parts as if it were the original file.

• --segment-container <container>

  Upload parts into the specified container. If not specified, segments will be uploaded into the _segments container to avoid polluting the main list.

• --leave-segments

  Indicates that you wish to keep the old segment of the manifest object alone (in case of overwriting).

• --object-threads <threads>

  The number of threads used to upload complete objects. The default value is 10.

• --segment-threads <threads>

  The number of threads used to upload object segments. The default value is 10.

• -H, --header <header:value>

  Add custom request headers. This option can be repeated. Example: -H "content-type:text/plain" -H "Content-Length:4000".

• --use-slo

  When –-segment sizeused with , it creates a static large object instead of the default dynamic large object.

• --object-name <object-name>

  Upload file and name object to or upload dir and use as object prefix instead of folder name.

  Upload a file and use <object-name>a named object or upload a directory and use <object-name>as the object prefix instead of the folder name.

• --ignore-checksum

  Turn off checksum verification for uploads.

swift post

Usage: swift post [--read-acl <acl>] [--write-acl <acl>] [--sync-to <sync-to>]
                  [--sync-key <sync-key>] [--meta <name:value>]
                  [--header <header>]
                  [<container> [<object>]]

Updates the metainformation of an account, container, or object based on the given parameters. If the container is not found, swiftclientit will be created automatically, but this is not true for accounts and objects. Containers also allow -r <read-acl>(or --read-acl <read-acl>) and -w <write-acl>(or --write-acl <write-acl>) options. -mor --metaoption allowed on accounts, containers and objects to define Name:Valueuser metadata items to be set in the form. This option can be repeated. For example:post -m Color:Blue -m Size:Large

For more information about the ACL format, see the documentation: ACL .

Positional parameters:

• [container]

  The name of the container to send to.

• [object]

  The name of the object to publish.

Optional parameters:

• -r, --read-acl <acl>

  The container's read ACL.

  A quick summary of the ACL syntax: .r:*, .r:-.example.com, .r:www.example.com, account1(only v1.0 Identity API supported), account1:*, account2:user2(v2.0+ Identity API).

• -w, --write-acl <acl>

  Container's write ACL.

  A quick summary of ACL syntax: account1only v1.0 Identity API), account1:*, account2:user2(v2.0+ Identity API) are supported.

• -t, --sync-to <sync-to>

  Used for container synchronization and multi-cluster replication.

• -k, --sync-key <sync-key>

  Container's synchronization key, used for multi-cluster replication.

• -m, --meta <name:value>

  Set metadata items. This option may be duplicated. For example:-m Color:Blue -m Size:Large

• -H, --header <header:value>

  Add custom request headers. This option can be repeated. Example: -H "content-type:text/plain" -H "Content-Length:4000".

swift download

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 an account (using --all), or everything in a container, or a list of objects based on the given parameters. For single object downloads, you can use the -o <filename>or --output <filename>option to redirect the output to a specific file or -the option to redirect the output to stdout. --ignore-checksumIs an option to turn off checksum verification. -H [--header <name:value>]Optional headers can be specified using the repeatable cURL option . Ignore metadata entries --ignore-mtimeon the object (if present) and instead create the downloaded file with new time and mtime values.x-object-meta-mtime

Positional parameters:

• <container>

  The name of the container to download from. To download the entire account, omit this and specify -all.

• <object>

  The name of the object to download. Specified multiple times for multiple objects. Omitting this option will download all objects from the container.

Optional parameters:

• -a, --all

  Indicate that you really want to download all content in this account.

• -m, --marker <marker>

  The flag to use when starting a container or account download.

• -p, --prefix <prefix>

  Only download items starting with

• -r, --remove-prefix

  --prefix <prefix>Optional flag for , use this option to download items that do not have

• -o, --output <out_file>

  For single file downloads, stream the output to <out_file>. Specify -as <out_file>to redirect to standard output.

• -D, --output-dir <out_directory>

  Optional directory to store objects. By default, all objects will be recreated in the current directory.

• --object-threads <threads>

  The number of threads used to download objects. The default value is 10.

• --container-threads <threads>

  The number of threads used to download the container. The default value is 10.

• --no-download

  Performs a download but does not actually write anything to disk.

• -H, --header <header:value>

  Add custom request headers to the query, such as Rangeor If-Match. This option can be repeated. Example:--header "content-type:text/plain"

• --skip-identical

  Skip downloading identical files on both sides.

• --ignore-checksum

  Turn off checksum verification of downloads.

• --no-shuffle

  By default, when downloading a complete account or container, the download order is randomized to reduce the load on a single drive when multiple clients are performing simultaneous downloads of the same set of objects (for example, a nightly automatic download script to multiple server). Enable this option to submit download jobs to the thread pool in the order they are listed in object storage.

swift delete

Usage: swift delete [--all] [--leave-segments]
                    [--object-threads <threads>]
                    [--container-threads <threads>]
                    [--header <header:value>]
                    [<container> [<object>] [...]]

Removes everything in the account (using --all), or everything in the container, or a list of objects based on the given parameters. Sections of the manifest object are also deleted unless --leave-segmentsthe option is specified.

Positional parameters:

• [<container>]

  The name of the container to remove from.

• [<object>]

  The name of the object to delete. Specified multiple times for multiple objects.

Optional parameters:

• -a, --all

  Delete all containers and objects.

• --leave-segments

  Do not delete segments of inventory objects.

• -H, --header <header:value>

  Add custom request headers for deleting objects or entire containers.

• --object-threads <threads>

  The number of threads used to delete objects. The default value is 10.

• --container-threads <threads>

  The number of threads used to delete containers. The default value is 10.

swift copy

Usage: swift copy [--destination </container/object>] [--fresh-metadata]
                  [--meta <name:value>] [--header <header>] <container>
                  <object> [<object>] [...]

Copy the object to a new destination or add user metadata to the object. Depending on the options provided, existing metadata can be preserved instead of the post command. --destinationOptions in /container/objectthe form of set the copy target destination. If not set, the object will be copied to itself, which is useful for adding metadata. Objects without existing user metadata can be copied using -Mthe or option and the user metadata items to be set in the form are defined using the or option . This option can be repeated. For example: .--fresh-metadata-m--metaName:Valuecopy -m Color:Blue -m Size:Large

Positional parameters:

• <container>

  The name of the container to copy from.

• <object>

  The name of the object to copy. Specify multiple times for multiple objects

Optional parameters:

• -d, --destination </container[/object]>

  The container and name of the target object. The name of the target object can be omitted and then be the same as the name of the source object. It is invalid to provide targets with object names for multiple objects.

• -M, --fresh-metadata

  Copies an object without any existing metadata. If not set, metadata will be preserved or appended.

• -m, --meta <name:value>

  Set metadata items. This option can be repeated. Example:-m Color:Blue -m Size:Large

• -H, --header <header:value>

  Add custom request headers. This option can be repeated. Example: -H "content-type:text/plain" -H "Content-Length:4000".

swift capabilities

Usage: swift capabilities [--json] [<proxy_url>]

Show cluster capabilities. The output includes a list of activated Swift middlewares and associated options for each middleware. In addition, the command also displays relevant options for the Swift core. If no proxy-urloption is provided, the storage URL retrieved after authentication will be used proxy-url.

Optional positional parameters:

• <proxy_url>

  The proxy URL for the cluster used to retrieve the feature.

• --json

  Print cluster functions in JSON format.

swift tempurl

Usage: swift tempurl [--absolute] [--prefix-based]
                     <method> <seconds> <path> <key>

Generate a temporary URL for a Swift object. methodoption sets an HTTP method to allow this temporary URL, usually GETor PUT. timeOption sets how long the temporary URL is valid. timeCan be specified as an integer representing the number of seconds from now until the URL is valid; or, if passed in --absolute, the Unix timestamp at which the temporary URL will expire. But in addition, timeit can also be specified as an ISO 8601 timestamp in one of the following formats:

1. Full date: YYYY-MM-DD (eg. 1997-07-16)
2. Complete date plus hours, minutes and seconds: YYYY-MM-DDThh:mm:ss (eg. 1997-07-16T19:20:30)
3. Complete date plus hours, minutes and seconds with UTC designator: YYYY-MM-DDThh:mm:ssZ (eg. 1997-07-16T19:20:30Z)

Note that if you do not provide a UTC indicator (i.e. Z), the timestamp will be generated using your local time zone. If only the date is specified, the time portion used will be equal to 00:00:00.

pathOption sets the full path of the Swift object. For example: /v1/AUTH_account/c/o. keyOptions are temporary URL keys set on the Swift cluster. To set the key, run swift post -m "Temp-URL-Key: <your secret key>". To generate a temporary prefix-based URL, use --prefix-basedthe option. This URL will contain the prefixed path. Don't forget to append the required objectname at the end of the path part (and before the query part) before sharing the URL. --iso8601ISO 8601 UTC timestamps can be used in URLs by using the option.

Positional parameters:

• <method>

  HTTP methods allowed for this temporary URL. Usually GETor PUT.

• <seconds>

  The time in seconds the temporary URL is valid for; or, if passed --absolute, the Unix timestamp at which the temporary URL expires.

• <path>

  The full path to the Swift object. For example: /v1/AUTH_account/c/oorhttp://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”’

  Temporary URL key set on the Swift cluster. To set the key, runswift post -m "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"

Optional parameters:

• --absolute

  Interpret positional arguments as Unix timestamps, not seconds in the future.

• --prefix-based

  If present, a prefix-based tempURL will be generated.

Example

In this section, some example usage of the swift command line will be shown. To keep the examples as short as possible, these examples assume that the relevant authentication options have been set using environment variables. The complete list of commands and options available on the swift command line can be obtained by executing:

> swift --help
> swift <command> --help

Simple example

List existing swift containers:

> swift list

container_1

Create a new container:

> swift post TestContainer

Upload an object into the container:

> swift upload TestContainer testSwift.txt

testSwift.txt

List the contents of a container:

> swift list TestContainer

testSwift.txt

Copy the object to the new destination:

> swift copy -d /DestContainer/testSwift.txt SourceContainer testSwift.txt

SourceContainer/testSwift.txt copied to /DestContainer/testSwift.txt

Remove an object from a container:

> swift delete TestContainer testSwift.txt

testSwift.txt

Delete container:

> swift delete TestContainer

TestContainer

Display auth-related authentication variables in a shell-friendly format:

> swift auth

export OS_STORAGE_URL=http://127.0.0.1:8080/v1/AUTH_bf5e63572f7a420a83fcf0aa8c72c2c7
export OS_AUTH_TOKEN=c597015ae19943a18438b52ef3762e79

Download objects from the container:

> swift download TestContainer testSwift.txt

testSwift.txt [auth 0.028s, headers 0.045s, total 0.045s, 0.002 MB/s]

illustrate

To upload an object to a container, the current working directory must be where the file is located, or the full path to the file must be provided. In other words, --object-name is an option that will upload a file and name the object as or upload a directory and use as object prefix. If a full path to the file is provided, the full path will be the name of the uploaded object.

For example:

> swift upload TestContainer /home/swift/testSwift/testSwift.txt

home/swift/testSwift/testSwift.txt

> swift list TestContainer

home/swift/testSwift/testSwift.txt

More complex example

Swift has a single object size limit of 5GiB. In order to upload a file larger than this, a large object composed of smaller segments must be created. The following example shows how to upload a large video file as a static large object in 1GiB segments:

> swift upload videos --use-slo --segment-size 1G myvideo.mp4

myvideo.mp4 segment 8
myvideo.mp4 segment 4
myvideo.mp4 segment 2
myvideo.mp4 segment 7
myvideo.mp4 segment 0
myvideo.mp4 segment 1
myvideo.mp4 segment 3
myvideo.mp4 segment 6
myvideo.mp4 segment 5
myvideo.mp4

This command uploads the fragment into videos_segmentsa container named and creates a manifest file describing videosthe entire object in the container. For more information on large objects, see the documentation here .

> swift list videos

myvideo.mp4

> swift list videos_segments

myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000000
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000001
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000002
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000003
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000004
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000005
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000006
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000007
myvideo.mp4/slo/1460229233.679546/9341553868/1073741824/00000008

First, the key should be set, and then a temporary URL should be generated for the Swift object:

> swift post -m "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"

> swift tempurl GET 6000 /v1/AUTH_bf5e63572f7a420a83fcf0aa8c72c2c7\
  /firstcontainer/clean.sh b3968d0207b54ece87cccc06515a89d4

/v1/AUTH_/firstcontainer/clean.sh?temp_url_sig=\
9218fc288cc09e5edd857b6a3d43cf2122b906dc&temp_url_expires=1472203614