swift命令行工具使用指南

swift工具是一个命令行工具，用于与OpenStack Object Storage (swift)环境通信。它允许人们执行几种类型的操作。

有关特定swift命令的帮助，输入:

$swift COMMAND --help

swift用法

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

子命令:

• delete

  删除容器或容器中的对象。

• download

  从容器中下载对象。

• list

  列出帐户的容器或容器的对象。

• post

  更新帐户、容器或对象的元信息;如果不存在则创建容器。

• copy

  复制对象，可选地添加元信息

• stat

  显示帐户、容器或对象的信息。

• upload

  上传文件或目录到给定的容器。

• capabilities

  列出集群功能。

• tempurl

  创建一个临时URL。

• auth

  显示认证相关的环境变量。

swift可选参数

• --version

  显示程序的版本号并退出

• -h, --help

  显示此帮助消息并退出

• --os-help

  显示OpenStack认证选项。

• -s, --snet

  使用SERVICENET内部网络。

• -v, --verbose

  打印更多信息。

• --debug

  显示curl命令和所有http查询的结果，无论结果状态如何。

• --info

  显示curl命令和所有返回错误的http查询的结果。

• -q, --quiet

  抑制状态输出。

• -A AUTH, --auth=AUTH

  获取认证令牌的URL。

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

  指定用于认证的版本。默认为env[ST_AUTH_VERSION]， env[OS_AUTH_VERSION]， env[OS_IDENTITY_API_VERSION]或1.0。

• -U USER, --user=USER

  获取认证令牌的用户名。用户名最好以单引号括起来，使用Tempauth认证的租户时，必须这样做。

• -K KEY, --key=KEY

  获取认证令牌的密钥。

• -R RETRIES, --retries=RETRIES

  重试失败连接的次数。

• --insecure

  允许swiftclient访问服务器，而无需验证SSL证书。默认为env[SSWIFTCLIENT_INSECURE]（设置为true以启用）。

• --no-ssl-compression

  此选项已弃用，不再使用。默认情况下，系统SSL库应该禁用SSL压缩。

• --prompt

  提示用户输入密码，该密码覆盖通过--key， --os-password或环境变量提供的任何密码。

认证

本节介绍使用swift对象存储进行认证的选项。下面详细介绍了每个认证版本所需的选项组合，但这些只是可用于成功认证的选项的一个子集。这些是最常见和推荐的组合。

应该从存储提供商处获取认证版本和凭据的详细信息。这些详细信息将使您更清楚地了解下面哪些认证部分最有可能允许连接到您的存储帐户。

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

可以通过设置以下环境变量组合来避免在命令行上手动指定上述选项:

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

可以通过设置以下环境变量来避免在命令行上手动指定上述选项:

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

传统认证系统

可以将swift配置为与其他任何数量的认证系统一起工作，我们不会在本文档中介绍这些系统。如果您的存储提供商没有使用Keystone提供访问令牌，请与他们联系以获取所需选项的说明。很可能需要按以下方式指定选项:

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

通过设置以下环境变量，可以避免在命令行上手动指定上述选项:

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

也可能需要使用一个完全独立的认证系统，在这种情况下，swiftclient无法请求令牌。在这种情况下，应该单独提出认证请求，并使用下面显示的令牌和存储URL选项访问存储：

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

说明

当授权失败时，遗留的环境变量是造成混乱的常见原因。

CLI命令

swift auth

Usage: swift auth

以shell友好格式显示认证变量。要运行的命令将存储URL和认证令牌导出到OS_storage_URL和OS_auth_token中：swift auth。用于附加到runcom文件（例如~/.bashrc、/etc/profile）以进行自动认证的命令：swift auth -v -U test:tester -K testing 。

swift stat

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

根据给定的参数(如果有的话)显示帐户、容器或对象的信息。在详细模式下，还会显示存储URL和认证令牌。

位置参数:

• [container]

  要从中进行统计的容器的名称。

• [object]

  要统计的对象的名称。

可选参数:

• --lh

  以类似于ls -lh的人类可读格式的报告大小。

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

  添加用于统计的自定义请求头。

swift list

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

列出帐户中的容器或容器内的对象。-p <prefix>或--prefix <prefix>是一个仅列出以该前缀开头的项目的选项。-d <delimiter>或--delimiter <delimiter>是一个选项（仅用于列出容器），它将使用给定的分隔符汇总项目（请参阅OpenStack Swift常规文档https://docs.openstack.org/swift/latest/了解其含义）。

-l和--lh选项提供了更多细节，类似于ls -l与ls -lh，后者提供了人类可读格式的大小（例如：3K、12M等）。后两个开关使用更多的开销来检索显示的详细信息，这与列出的容器或对象的数量成正比。

位置参数:

• [container]

  要在其中列出对象的容器的名称。

可选参数:

• -l, --long

  长列表格式，类似于ls -l。

• --lh

  以类似于ls -lh的人类可读格式的报告大小。

• -t, --totals

  与-l或--lh一起使用，仅报告总计。

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

  仅列出以前缀开头的项目。

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

  用给定的分隔符汇总项目。仅适用于容器。请参阅OpenStack Swift API文档了解其含义。

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

  添加用于列出的自定义请求头。

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

将其余参数指定的文件和目录上传到给定的容器。-c或--changed 是一个选项，它将只上传自上次上传以来已更改的文件。--object-name <object-name>是一个选项，上传文件并且使用<object-name>命名对象或上传目录并使用<object-name> 作为对象前缀。如果文件名为-，客户端将从标准输入中读取内容。在这种情况下，需要--object-name 来设置对象的名称，并且不能给出其他文件。 -S <size>或--segment-size <size>和--leave-segments也是选项（有关详细信息，请参阅 --help）。

位置参数:

• <container>

  要上传到的容器的名称。

• <file_or_directory>

  要上传的文件或目录的名称。为多次上传指定多次。

可选参数:

• -c, --changed

  仅上传自上次上传以来已更改的文件。

• --skip-identical

  跳过上传双方完全相同的文件。

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

  上传不大于(以字节为单位)的分段上传文件，然后创建一个“manifest”文件，该文件将下载所有分段，就像它是原始文件一样。

• --segment-container <container>

  将分段上传到指定的容器中。如果未指定，则分段将上载到_segments容器中，以免污染主列表。

• --leave-segments

  表明您希望单独保留清单对象的旧段(在覆盖的情况下)。

• --object-threads <threads>

  用于上传完整对象的线程数。默认值是10。

• --segment-threads <threads>

  用于上传对象分段的线程数。默认值是10。

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

  添加自定义请求头。此选项可以重复。示例:-H "content-type:text/plain" -H "Content-Length:4000"。

• --use-slo

  当与–-segment size一起使用时，它将创建一个静态大对象，而不是默认的动态大对象。

• --object-name <object-name>

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

  上传文件并且使用<object-name>命名对象或上传目录并使用<object-name> 作为对象前缀而不是文件夹名称。

• --ignore-checksum

  关闭上传的校验和验证。

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

根据给定的参数更新帐户、容器或对象的元信息。如果没有找到容器，swiftclient 将自动创建它，但这对帐户和对象不是真的。容器还允许-r <read-acl>(或 --read-acl <read-acl>)和-w <write-acl>(或 --write-acl <write-acl>)选项。-m或--meta选项允许在帐户、容器和对象上使用，用于定义要以Name:Value形式设置的用户元数据项。可以重复此选项。例如:post -m Color:Blue -m Size:Large

有关ACL格式的更多信息，请参阅文档:ACL。

位置参数:

• [container]

  要发送到的容器的名称。

• [object]

  要发布的对象的名称。

可选参数:

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

  容器的读取ACL。

  ACL语法的快速摘要： .r:*, .r:-.example.com, .r:www.example.com, account1 (仅支持v1.0身份API), account1:*, account2:user2 (v2.0+身份API)。

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

  容器的写ACL。

  ACL语法的快速摘要：account1 仅支持v1.0身份API), account1:*, account2:user2 (v2.0+身份API)。

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

  用于容器同步，用于多集群复制。

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

  容器的同步密钥，用于多集群复制。

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

  设置元数据项。此选项可能会重复。例如：-m Color:Blue -m Size:Large

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

  添加自定义请求头。此选项可以重复。示例:-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>] [...]]

下载帐户中的所有内容(使用--all)，或容器中的所有内容，或根据给定的参数下载对象列表。对于单个对象下载，可以使用-o <filename>或--output <filename>选项将输出重定向到特定文件或 -选项将输出重定向到stdout。--ignore-checksum 是一个关闭校验和验证的选项。可以使用可重复的cURL的选项-H [--header <name:value>]来指定可选的标头。--ignore-mtime 忽略对象上的x-object-meta-mtime 元数据条目(如果存在)，而是使用新的时间和mtime值创建下载的文件。

位置参数:

• <container>

  要从中下载的容器的名称。要下载整个帐户，请省略此并指定-all。

• <object>

  要下载的对象的名称。为多个对象指定多次。省略此选项将从容器中下载所有对象。

可选参数:

• -a, --all

  表明您确实想下载该帐户中的所有内容。

• -m, --marker <marker>

  启动容器或帐户下载时使用的标记。

• -p, --prefix <prefix>

  只下载以开头的项目

• -r, --remove-prefix

  --prefix <prefix>的可选标志，使用此选项下载没有的项

• -o, --output <out_file>

  对于单个文件下载，将输出流式传输到<out_file>。指定-作为<out_file>将重定向到标准输出。

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

  存储对象的可选目录。默认情况下，将在当前目录中重新创建所有对象。

• --object-threads <threads>

  用于下载对象的线程数。默认值是10。

• --container-threads <threads>

  用于下载容器的线程数。默认值是10。

• --no-download

  执行下载，但实际上不向磁盘写入任何内容。

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

  为查询添加自定义请求头，如Range或If-Match。此选项可以重复。示例:--header "content-type:text/plain"

• --skip-identical

  跳过下载双方完全相同的文件。

• --ignore-checksum

  关闭下载的校验和验证。

• --no-shuffle

  默认情况下，当下载一个完整的帐户或容器时，下载顺序是随机的，以便在多个客户端同时执行下载同一组对象时减少单个驱动器上的负载(例如，每晚自动下载脚本到多个服务器)。启用此选项以按照在对象存储中列出的顺序将下载作业提交到线程池。

swift delete

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

删除帐户中的所有内容(使用 --all)，或容器中的所有内容，或根据给定参数删除对象列表。manifest对象的段也会被删除，除非指定了 --leave-segments 选项。

位置参数:

• [<container>]

  要从中删除的容器的名称。

• [<object>]

  要删除的对象的名称。为多个对象指定多次。

可选参数:

• -a, --all

  删除所有容器和对象。

• --leave-segments

  不要删除清单对象的分段。

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

  添加自定义请求头，用于删除对象或整个容器。

• --object-threads <threads>

  用于删除对象的线程数。默认值是10。

• --container-threads <threads>

  用于删除容器的线程数。默认值是10。

swift copy

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

将对象复制到新的目标或将用户元数据添加到对象。根据提供的选项，可以保留现有的元数据，而不是post命令。 --destination 选项以/container/object的形式设置复制目标目的地。如果未设置，对象将被复制到自身上，这对于添加元数据非常有用。可以使用-M或--fresh-metadata选项复制没有现有用户元数据的对象，使用-m 或 --meta选项定义要以Name:Value形式设置的用户元数据项。可以重复此选项。例如：copy -m Color:Blue -m Size:Large。

位置参数:

• <container>

  要从中复制的容器的名称。

• <object>

  要复制的对象的名称。为多个对象指定多次

可选参数:

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

  目标对象的容器和名称。目标对象的名称可以省略，然后和源对象的名称相同。为多个对象提供含对象名称的目标是无效的。

• -M, --fresh-metadata

  复制没有任何现有元数据的对象，如果没有设置，将保留或追加元数据

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

  设置元数据项。此选项可以重复。示例:-m Color:Blue -m Size:Large

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

  添加自定义请求头。此选项可以重复。示例:-H "content-type:text/plain" -H "Content-Length:4000"。

swift capabilities

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

显示集群功能。输出包括激活的Swift中间件列表以及每个中间件的相关选项。此外，该命令还显示了Swift核心的相关选项。如果未提供proxy-url选项，则认证后检索的存储URL将被用作proxy-url。

Optional 位置参数:

• <proxy_url>

  用于检索功能的集群的代理URL。

• --json

  以JSON格式打印集群功能。

swift tempurl

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

为Swift对象生成一个临时URL。method 选项设置一个HTTP方法来允许此临时URL，通常是GET或PUT。time选项设置临时URL的有效时间。time可以指定为整数，表示从现在开始到URL有效为止的秒数;或者，如果传入--absolute，则表示临时URL到期的Unix时间戳。但除此之外，time也可以以以下格式之一指定为ISO 8601时间戳:

1. 完整日期: YYYY-MM-DD (例如. 1997-07-16)
2. 完整的日期加上小时，分钟和秒: YYYY-MM-DDThh:mm:ss (例如. 1997-07-16T19:20:30)
3. 完整的日期加上小时，分钟和秒与UTC指示符: YYYY-MM-DDThh:mm:ssZ (例如. 1997-07-16T19:20:30Z)

请注意，如果您不提供UTC指示符（即Z），则时间戳将使用您的本地时区生成。如果只指定了日期，则使用的时间部分将等于00:00:00。

path 选项设置Swift对象的完整路径。例如:/v1/AUTH_account/c/o。key选项是Swift集群上设置的临时URL密钥。要设置密钥，请运行swift post -m "Temp-URL-Key: <your secret key>"。要生成基于前缀的临时URL，请使用 --prefix-based选项。此URL将包含前缀的路径。在共享URL之前，不要忘记在路径部分的末尾(以及查询部分之前)附加所需的objectname。通过使用--iso8601 选项可以在URL中使用ISO 8601 UTC时间戳。

位置参数:

• <method>

  此临时URL允许的HTTP方法。通常为GET或PUT。

• <seconds>

  临时URL的有效时间(以秒为单位);或者，如果传递--absolute，则表示临时URL到期的Unix时间戳。

• <path>

  Swift对象的完整路径。例如: /v1/AUTH_account/c/o 或 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”’

  Swift集群上设置的临时URL密钥。要设置密钥，请运行swift post -m "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"

可选参数:

• --absolute

  将位置参数解释为Unix时间戳，而不是未来的秒数。

• --prefix-based

  如果存在，将生成一个基于前缀的tempURL。

示例

在本节中，将展示一些swift命令行的示例用法。为了使示例尽可能简短，这些示例假设已经使用环境变量设置了相关的认证选项。可以通过执行以下命令获得swift命令行中可用的命令和选项的完整列表:

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

简单示例

列出现有的swift容器：

> swift list

container_1

创建一个新容器:

> swift post TestContainer

上传一个对象到容器中:

> swift upload TestContainer testSwift.txt

testSwift.txt

列出容器的内容:

> swift list TestContainer

testSwift.txt

将对象复制到新目标：

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

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

从容器中删除对象:

> swift delete TestContainer testSwift.txt

testSwift.txt

删除容器:

> swift delete TestContainer

TestContainer

以shell友好的格式显示auth相关的认证变量:

> swift auth

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

从容器中下载对象:

> swift download TestContainer testSwift.txt

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

说明

要将对象上传到容器，当前工作目录必须是该文件所在的位置，或者必须提供该文件的完整路径。换句话说，–object-name 是一个选项，它将上传文件和命名对象为或上传目录并使用作为对象前缀。如果提供了文件的完整路径，则该完整路径将是上传对象的名称。

例如:

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

home/swift/testSwift/testSwift.txt

> swift list TestContainer

home/swift/testSwift/testSwift.txt

更复杂的示例

Swift的单个对象大小限制为5GiB。为了上传比这个大的文件，必须创建一个由较小分段组成的大对象。以下示例显示了如何将大型视频文件作为1GiB分段中的静态大型对象上传：

> 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

该命令将片段上传到名为videos_segments的容器中，并创建一个清单文件，描述videos容器中的整个对象。有关大型对象的更多信息，请参阅文档在这里。

> 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

首先，应该设置密钥，然后为Swift对象生成一个临时URL：

> 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