Swift CLI

Owned by Chris Green
Last updated: Oct 27, 2023
19 min read

 

In order to use all the commands provided from Swift, it is recommended that you have the following python package installed:

pip install python-swiftclient

Note

See Using the OpenStack Command Line Interface for how to set up the Openstack command line client. This is the preferred client, but in some cases the Swift client provides coverage that is not yet supported.

To test whether the Swift client have been installed successfully and we can access Swift commands, we can try to list containers in our current project:

swift list

This should return nothing if there are no containers in your project, or a list of containers similar to below:

CONTAINER_1 CONTAINER_2 CONTAINER_3

We can also try to list containers using the Openstack client, to test that this has been installed successfully and that we can access Swift commands in the preferred manner:

This should return an empty line if there are no containers in your project, or a table containing the names of containers similar to the table below:

Commands

We are now able to run commands for working with containers and objects. Below is a list of some of the commands that can be used:

Warning

Equivalent commands using the Openstack and Swift clients may differ in behaviour. For example, openstack container delete <container> will fail unless the container is empty or -r is used, whereas swift delete <container> will delete the contents of the container, as well as the container itself.

Further details and options can be seen using openstack container <command> --help, openstack object <command> --help and swift <command> --help.

Listing Files

To list objects in CONTAINER_1:

Getting Information About Your Account, Containers and Files

To print information about your account:

To print basic information about CONTAINER_1:

To print more detailed information about CONTAINER_1:

To print basic information about FILE_1.txt in CONTAINER_1:

To print further information about FILE_1.txt in CONTAINER_1:

Creating Containers

Containers can be created using:

For example:

Note

Containers created using the Openstack client will not be publicly accessible. This can be changed via the GUI, or by updating the container’s metadata (Swift | Editing Container Metadata).

Uploading Files

Objects can be uploaded into containers using:

Multiple files may be uploaded simultaneously by listing then after the container name:

Note

Creating Folders

Folders can be created when uploading a file. For example, FOLDER_1 and FOLDER_2 can be created with the following:

To create an empty folder in a container, a local empty folder can be uploaded using the Swift client:

Note

Saving Containers

The full contents of a container can be saved using the Openstack client. For example:

All files will be downloaded to your current directory, with directories implied by object names being created as necessary to recreate the structure.

For example, saving the following container would save FILE_1.txt in ./FOLDER_1, which will be created if it does not exist:

Warning

However, this command will fail if folders exist as unique objects in the container. For example, FOLDER_1/ in the following:

Note

In this case, the Swift client must be used to save containers:

By default, this will save all files to the current directory, and, as before, any directories that do not exist will be created.

Deleting Files

Multiple objects can be deleted using:

This will return nothing if successful.

Saving Files

Individual files can be saved using the Openstack client. For example:

Multiple files can be saved using the Swift client. For example:

Saving Folders

The full contents of a folder can be saved by using the Swift client to download each file. For example:

Deleting Folders

If a folder is not a unique object, but exists through file names, it can be deleted by deleting all files within the folder. For example, if FILE_1.txt and FILE_2.txt are the only files in FOLDER_1, the following will delete the folder:

If a folder is stored as a unique object, this can be deleted in the same way as a file:

However, this will not delete any files within the folder. To delete the folder, both the folder object and the folder contents must be deleted:

Deleting Containers

A container can be deleted using:

This will return nothing if successful. An error will be thrown if the container is not empty, unless the -r or --recursive options are used to delete all objects within the container at the same time.

Large Files

Swift does not allow objects larger than 5GiB, so larger files must be segmented. This must be done using the Swift client:

Warning

This will upload the segments into a separate container, by default named <container>_segments, and create a “manifest” file describing the entire object in <container>.

Note

The entire object can be downloaded via the manifest file as if it were any other file, through the GUI or using the Openstack client:

To delete the entire object, the Swift client must be used. For example:

If successful, this will output the manifest file name, as well as the file names of each segment, all of which will have been deleted. The segments container must be deleted separately.

Warning

Copying Files

Multiple files can be copied within a container, or between containers, using the Swift client. For example, copying FILE_1.txt and FILE_2.txt from CONTAINER_1 to CONTAINER_2:

Warning

If successful, this will create any containers and folders specified that do not exist, and output <file> copied to <destination> for each file.

Note

Editing Container Metadata

Multiple custom properties of a container can be added or overwritten simultaneously through repeated use of the --property option:

Note

These properties will be listed when printing information about the container:

Custom properties may also be removed from a container:

Setting system metadata, such making a container public, can be done through the Swift client using:

Warning

Similarly, containers can be made private using:

Note

Editing Object Metadata

As for containers, multiple custom properties for object may be set simultaneously:

Warning

Note

These properties will be listed when printing information about the object:

Custom properties may also be removed from objects:

Creating a Temporary URL

Secret keys used in the cryptographic signature for temporary URLs can be created using the Swift client. For example, to set the secret key to MYKEY:

Note

A temporary URL for a Swift object can then be generated using the Swift client, typically to allow GET or PUT access. For example:

Note

References