swift(1) OpenStack Swift swift(1)
NAME
swift - OpenStack Swift client tool
SYNOPSIS
swift [options] <command> [args]
DESCRIPTION
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.
COMMANDS
stat [
command-options] [
container] [
object]
Displays information for the account, container, or object
depending on the args given (if any). In verbose mode, the
Storage URL and the authentication token are displayed as well.
Option --lh reports sizes in human readable format similar to ls
-lh.
list [
command-options] [
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 list items beginning with that prefix. The -d
<delim> or --delimiter <delim> is option (for container listings
only) that will roll up items with the given delimiter (see
OpenStack Swift general documentation for what this means).
The -l or --long and --lh options provide more detail, similar to
ls -l and ls -lh, the latter providing sizes in human readable
format (eg 3K, 12M, etc). These latter 2 switches use more
overhead to get those details, which is directly proportional to
the number of container or objects being listed. With the -t or
--total option they only report totals.
upload [
command-options] container file_or_directory
[
file_or_directory] [...]
Uploads to the given container the files and directories
specified by the remaining args. The -c or --changed is an option
that will only upload files that have changed since the last
upload. The --object-name <object-name> is an option that will
upload file and name object to <object-name> or upload dir and
use <object-name> as object prefix. If the file name is "-",
reads the content from standard input. In this case,
--object-name is required and no other files may be given. The -S
<size> or --segment-size <size> and --leave-segments and others
are options as well (see swift upload --help for more).
post [
command-options] [
container] [
object]
Updates meta information for the account, container, or object
depending on the args given. If the container is not found, it
will be created automatically; but this is not true for accounts
and objects. Containers also allow the -r (or --read-acl) and -w
(or --write-acl) options. The -m or --meta option is allowed on
all and used to define the user meta data items to set in the
form Name:Value. This option can be repeated. For more details
and options see swift post --help.
Example: post -m Color:Blue
-m Size:Large
copy [
command-options]
container object Copies an object to a new destination or adds user metadata to
the object (current user metadata will be preserved, in contrast
with the post command) depending on the args given. The
--destination option sets the destination in the form
/container/object. If not set, the object will be copied onto
itself which is useful for adding metadata. The -M or
--fresh-metadata option copies the object without the existing
user metadata. The -m or --meta option is always allowed and is
used to define the user metadata items to set in the form
Name:Value (this option can be repeated). For more details and
options see swift copy --help.
download [
command-options] [
container] [
object] [
object] [...]
Downloads everything in the account (with --all), or everything
in a container, or a list of objects depending on the args given.
For a single object download, you may use the -o [--output]
<filename> option to redirect the output to a specific file or if
"-" then just redirect to stdout or with --no-download actually
not to write anything to disk. The --ignore-checksum is an
option that turns off checksum validation. You can specify
optional headers with the repeatable cURL-like option -H
[--header]. For more details and options see swift download
--help. The --ignore-mtime option ignores the
x-object-meta-mtime metadata entry on the object (if present) and
instead creates the downloaded files with fresh atime and mtime
values.
delete [
command-options] [
container] [
object] [
object] [...]
Deletes everything in the account (with --all), or everything in
a container, or all objects in a container that start with a
given string (given by --prefix), or a list of objects depending
on the args given. Segments of manifest objects will be deleted
as well, unless you specify the --leave-segments option. For
more details and options see swift delete --help.
capabilities [
command-options] [
proxy-url]
Displays cluster capabilities. If the proxy-url option is not
provided the storage-url retrieved after authentication is used
as proxy-url.
By default, the output includes the list of the activated Swift
middlewares as well as relevant options for each one.
Additionally the command displays relevant options for the Swift
core.
The --json option will print a json representation of the cluster
capabilities. This is typically more suitable for consumption by
other programs, such as jq.
Example: capabilities https://swift.example.com
capabilities --json
tempurl [
command-option]
method time path key Generates a temporary URL allowing unauthenticated access to the
Swift object at the given path, using the given HTTP method, for
the given time, using the given TempURL key.
The time can be specified either as an integer denoting the
amount of seconds the temporary URL is valid, or as an ISO 8601
timestamp in one of following formats: Complete date: YYYY-MM-DD
(eg 1997-07-16), complete date plus hours, minutes and seconds:
YYYY-MM-DDThh:mm:ss (eg 1997-07-16T19:20:30) or complete date
plus hours, minutes and seconds with UTC designator:
YYYY-MM-DDThh:mm:ssZ (eg 1997-07-16T19:20:30Z). Be aware that if
you do not use the latter format, the timestamp is generated
using your locale timezone. If the first format is used, the time
part used will equal to 00:00:00.
With the --prefix-based option a prefix-based URL is generated.
The option --iso8601 provides ISO 8601 UTC timestamps instead of
Unix timestamps inside the generated URL.
If optional --absolute argument is provided and the time argument
is specified in seconds, the seconds are interpreted as a Unix
timestamp at which the URL should expire.
Example: tempurl GET $(date -d "Jan 1 2016" +%s)
/v1/AUTH_foo/bar_container/quux.md my_secret_tempurl_key
--absolute
auth Display auth related authentication variables in shell friendly
format. For examples see swift auth --help.
OPTIONS
--version Show program's version number and exit
-h, --help Show this (or any subcommand if after command)
help message and exit
-s, --snet Use SERVICENET internal network
-v, --verbose Print more info
-q, --quiet Suppress status output
-A AUTH, --auth=AUTH URL for obtaining an auth token
-U USER, --user=USER User name for obtaining an auth token
-V 1|2, --auth-version=VERSION Authentication protocol version
-K KEY, --key=KEY Key for obtaining an auth token
--os-storage-url=URL Use this instead of URL returned from auth
--os-help Show all OpenStack authentication options
For more options see swift --help and swift --os-help.
EXAMPLE
swift -A https://127.0.0.1:443/auth/v1.0 -U swiftops:swiftops -K
swiftops stat
Account: AUTH_43b42dae-dc0b-4a4b-ac55-97de614d6e6e
Containers: 1
Objects: 1
Bytes: 1124
Accept-Ranges: bytes
X-Trans-Id: txb21186a9eef64ed295a1e95896a0fc72
DOCUMENTATION
More in depth documentation about OpenStack Swift as a whole can be
found at
https://docs.openstack.org/swift/latest/Linux 8/26/2011 swift(1)
