Object Storage service (swift) command-line client¶

swift auth¶

Usage: swift auth

Display auth related authentication variables in shell friendly format.

Commands to run to export storage url and auth token into OS_STORAGE_URL and OS_AUTH_TOKEN:

$ swift auth

Commands to append to a runcom file (e.g. ~/.bashrc, /etc/profile) for automatic authentication:

$ swift auth -v -U test:tester -K testing -A http://localhost:8080/auth/v1.0

swift capabilities¶

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

Retrieve capability of the proxy.

Optional positional arguments:

<proxy_url>

Proxy URL of the cluster to retrieve capabilities.

--json

Print the cluster capabilities in JSON format.

swift copy¶

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

Copies object to new destination, optionally updates objects metadata. If destination is not set, will update metadata of object

Positional arguments:

<container>

Name of container to copy from.

<object>

Name of object to copy. Specify multiple times for multiple objects

Optional arguments:

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

The container and name of the destination object. Name of destination object can be omitted, then will be same as name of source object. Supplying multiple objects and destination with object name is invalid.

-M, --fresh-metadata

Copy the object without any existing metadata, If not set, metadata will be preserved or appended

-m, --meta <name:value>

Sets a meta data item. This option may be repeated.

Example: -m Color:Blue -m Size:Large

-H, --header <header:value>

Adds a customized request header. This option may be repeated.

Example: -H "content-type:text/plain" -H "Content-Length: 4000"

swift delete¶

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

Delete a container or objects within a container.

Positional arguments:

[<container>]

Name of container to delete from.

[<object>]

Name of object to delete. Specify multiple times for multiple objects.

Optional arguments:

-a, --all

Delete all containers and objects.

--leave-segments

Do not delete segments of manifest objects.

-H, --header <header:value>

Adds a custom request header to use for deleting objects or an entire container.

--object-threads <threads>

Number of threads to use for deleting objects. Default is 10.

--container-threads <threads>

Number of threads to use for deleting containers. Default is 10.

swift 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>] [...]]

Download objects from containers.

Positional arguments:

<container>

Name of container to download from. To download a whole account, omit this and specify --all.

<object>

Name of object to download. Specify multiple times for multiple objects. Omit this to download all objects from the container.

Optional arguments:

-a, --all

Indicates that you really want to download everything in the account.

-m, --marker <marker>

Marker to use when starting a container or account download.

-p, --prefix <prefix>

Only download items beginning with <prefix>

-r, --remove-prefix

An optional flag for --prefix <prefix>, use this option to download items without <prefix>

-o, --output <out_file>

For a single file download, stream the output to <out_file>. Specifying "-" as <out_file> will redirect to stdout.

-D, --output-dir <out_directory>

An optional directory to which to store objects. By default, all objects are recreated in the current directory.

--object-threads <threads>

Number of threads to use for downloading objects. Default is 10.

--container-threads <threads>

Number of threads to use for downloading containers. Default is 10.

--no-download

Perform download(s), but don't actually write anything to disk.

-H, --header <header:value>

Adds a customized request header to the query, like "Range" or "If-Match". This option may be repeated.

Example: --header "content-type:text/plain"

--skip-identical

Skip downloading files that are identical on both sides.

--ignore-checksum

Turn off checksum validation for downloads.

--no-shuffle

By default, when downloading a complete account or container, download order is randomised in order to reduce the load on individual drives when multiple clients are executed simultaneously to download the same set of objects (e.g. a nightly automated download script to multiple servers). Enable this option to submit download jobs to the thread pool in the order they are listed in the object store.

swift list¶

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.

Positional arguments:

[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 post¶

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. If the container is not found, it will be created automatically.

Positional arguments:

[container]

Name of container to post to.

[object]

Name of object to post.

Optional arguments:

-r, --read-acl <acl>

Read ACL for containers. Quick summary of ACL syntax: .r:*, .r:-.example.com, .r:www.example.com, account1 (v1.0 identity API only), account1:*, account2:user2 (v2.0+ identity API).

-w, --write-acl <acl>

Write ACL for containers. Quick summary of ACL syntax: account1 (v1.0 identity API only), account1:*, account2:user2 (v2.0+ identity API).

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

Sync To for containers, for multi-cluster replication.

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

Sync Key for containers, for multi-cluster replication.

-m, --meta <name:value>

Sets a meta data item. This option may be repeated.

Example: -m Color:Blue -m Size:Large

-H, --header <header:value>

Adds a customized request header. This option may be repeated.

Example: -H "content-type:text/plain" -H "Content-Length: 4000"

swift stat¶

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

Displays information for the account, container, or object.

Positional arguments:

[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 tempurl¶

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

Generates a temporary URL for a Swift object.

Positional arguments:

<method>

An HTTP method to allow for this temporary URL. Usually 'GET' or 'PUT'.

<seconds>

The amount of time in seconds the temporary URL will be valid for; or, if --absolute is passed, the Unix timestamp when the temporary URL will expire.

<path>

The full path to the Swift object.

Example: /v1/AUTH_account/c/o or: http://saio:8080/v1/AUTH_account/c/o

<key>

The secret temporary URL key set on the Swift cluster. To set a key, run 'swift post -m "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"'

Optional arguments:

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

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 specified files and directories to the given container.

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.