python-swiftclient/doc/manpages/swift.1

.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" Copyright (c) 2010-2011 OpenStack Foundation.
.\"
.\" Licensed under the Apache License, Version 2.0 (the "License");
.\" you may not use this file except in compliance with the License.
.\" You may obtain a copy of the License at
.\"
.\"    http://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS,
.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
.\" implied.
.\" See the License for the specific language governing permissions and
.\" limitations under the License.
.\"
.TH swift 1 "8/26/2011" "Linux" "OpenStack Swift"

.SH NAME
.LP
.B swift
\- OpenStack Swift client tool

.SH SYNOPSIS
.LP
.B swift
[options] <command> [args]

.SH DESCRIPTION
.PP
The \fBswift\fR tool is a command line utility for communicating with
an OpenStack Object Storage (Swift) environment. It allows one to perform
several types of operations.

.SH COMMANDS
.PP

\fBstat\fR [\fIcontainer\fR] [\fIobject\fR]
.RS 4
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.
.RE

\fBlist\fR [\fIcommand-options\fR] [\fIcontainer\fR]
.RS 4
Lists the containers for the account or the objects for a container.
The \-p or \-\-prefix is an option that will only list items beginning
with that prefix. The \-d or \-\-delimiter 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 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.
.RE

\fBupload\fR [\fIcommand-options\fR] container file_or_directory [\fIfile_or_directory\fR] [...]
.RS 4
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. The \-S <size> or \-\-segment\-size <size>
and \-\-leave\-segments are options as well (see \-\-help for more).
.RE

\fBpost\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR]
.RS 4
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.
\fBExample\fR: post \-m Color:Blue \-m Size:Large
.RE

\fBdownload\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] [\fIobject\fR] [...]
.RS 4
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.
You can specify optional headers with the repeatable cURL-like option
\-H [\-\-header].
.RE

\fBdelete\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] [\fIobject\fR] [...]
.RS 4
Deletes everything in the account (with \-\-all), or everything in a container,
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.
.RE

\fBcapabilities\fR [\fIproxy-url\fR]
.RS 4
Displays cluster capabilities. The output includes the list of the activated
Swift middlewares as well as relevant options for each ones. Addtionaly the
command displays relevant options for the Swift core. If the proxy-url option
is not provided the storage-url retrieved after authentication is used as
proxy-url.
.RE

\fBtempurl\fR method seconds path key
.RS 4
Generates a temporary URL allowing unauthenticated access to the Swift object at
the given path, using the given HTTP method, for the given number of seconds,
using the given TempURL key. \fBExample\fR: tempurl GET 86400
/v1/AUTH_foo/bar_container/quux.md my_secret_tempurl_key
.RE

.SH OPTIONS
.PD 0
.IP "--version              Show program's version number and exit"
.IP "-h, --help             Show this (or any subcommand) help message and exit"
.IP "-s, --snet             Use SERVICENET internal network"
.IP "-v, --verbose          Print more info"
.IP "-q, --quiet            Suppress status output"
.IP "-A AUTH, --auth=AUTH   URL for obtaining an auth token "
.IP "-U USER, --user=USER   User name for obtaining an auth token"
.IP "-V 1|2                 Authentication protocol version"
.IP "-K KEY, --key=KEY      Key for obtaining an auth token"
.IP "--os-storage-url=URL   Use this instead of URL returned from auth"

.PD


.SH EXAMPLE
.PP
swift \-A https://127.0.0.1:443/auth/v1.0 \-U swiftops:swiftops \-K swiftops stat

.RS 2
.PD 0
.IP "   Account: AUTH_43b42dae-dc0b-4a4b-ac55-97de614d6e6e"
.IP "Containers: 1"
.IP "   Objects: 1"
.IP "     Bytes: 1124"
.IP "Accept-Ranges: bytes"
.IP "X-Trans-Id: txb21186a9eef64ed295a1e95896a0fc72"
.PD
.RE


.SH DOCUMENTATION
.LP
More in depth documentation about OpenStack Swift as a whole can be found at
.BI http://swift.openstack.org