Install Swiftly#

Swiftly is a client tool that you can use to upload objects to and download objects from your Rackspace Cloud Files account. Swiftly manages the storage of large objects in Cloud Files. If you have a very large object (such as a virtual disk image file), Swiftly splits the file into smaller segments and then creates the large object manifest for you.

For more information about Swiftly, see the following sites:

The Python® package index page: https://pypi.python.org/pypi/swiftly/2.02
Swiftly documentation: https://gholt.github.io/swiftly/
Swiftly source code: https://github.com/gholt/swiftly

Install Swiftly on the Ubuntu operating system#

These instructions were built by Rackspace on an Ubuntu® 13.10 public image.

Use the following instructions from a Bash shell on your server:

Update the apt-get database.
```
sudo apt-get update
```
Install the Python installer, pip, by using apt-get.
```
sudo apt-get install python-pip
```
Install Swiftly by using pip.
```
sudo pip install swiftly
```

Install Swiftly on CentOS#

These instructions were verified by Rackspace on a CentOS® 6.5 public image.

Use the following instructions from a Bash shell on your server:

Install the Python installer, pip, by using yum.
```
sudo yum install python-pip
```
If you get an error saying the package can’t be found, the EPEL repository needs to be enabled. For information on setting up the EPEL repository on your system, see Install EPEL and additional repositories on CentOS and Red Hat. When EPEL is enabled, run the install command for pip again.
Install Swiftly by using pip.
```
sudo pip install swiftly
```

Configure Swiftly for Cloud Files#

Edit or create the file ~/.swiftly.conf. By default, Swiftly uses the configuration file in the same local directory where it is run, or you can define a file path while running Swiftly commands by using the --conf=PATH flag. Include the following contents in your .swiftly.conf file:

    [swiftly]
    auth_user = <yourUserName>
    auth_key = <yourAPIkey>
    auth_url = https://identity.api.rackspacecloud.com/v2.0
    region = <datacenter>

For the full list of options available in the .swiftly.conf file, see the sample config file in the Swiftly repo.

Install Eventlet (optional)#

Eventlet is an optional pip package that allows you to set a concurrency count when using Swiftly. This count is useful when performing bulk actions that are threaded because the Cloud Files application programming interface (API) has a limit of 100 concurrent write requests per container.

Install Eventlet on the Ubuntu operating system#

Use the following instructions from a Bash shell on your server:

Install the Python developer library package by using apt-get.
```
 sudo apt-get python-dev
```
Install Eventlet by using pip.
```
 sudo pip install eventlet
```

Install Eventlet on CentOS#

Use the following instructions from a Bash shell on your server:

Install the Python developer library package by using yum.
```
 sudo yum install python-devel
```
Install Eventlet by using pip.
```
 sudo pip install eventlet
```

Install GNU Screen (optional)#

GNU Screen is a program that you can use to start a Screen session. A Screen session looks just like an ordinary shell except that you can detach a terminal from a Screen session, and whatever commands you are running continue running in the session. This functionality is useful when you start a long running process (such as a large object upload) from the command line. If your laptop battery dies, or your wireless connection is lost, or you are otherwise disconnected, the process continues to run in your Screen session.

Install Screen in the Ubuntu operating system#

Use the following instructions from a Bash shell on your server to install Screen in the Ubuntu operating system:

sudo apt-get install screen

Installing Screen in CentOS#

Invoke the following instructions from a Bash shell on your server to install Screen in CentOS:

sudo yum install screen

Get started with Screen#

To start Screen, run the following command. The -s option tells the program what shell to use. The -S option provides a name for the session, which is helpful if you have several Screen sessions running at the same time.

screen -s /bin/bash -S display-Name-For-Screen

After you start Screen, you can enter regular Bash commands. Screen commands, that is, commands requesting Screen to do something, are escaped with Control-a (or C-a) . Some Screen commands are single character. For example, to detach from Screen, type the following command:

C-a d

Other Screen commands are longer. To use these, you first type C-a: and then you type the rest of the command in the status line of the Screen window. For example, you can log Screen’s output to a file so that you can go back and review it later by typing the following command:

C-a :

C-a : logfile name-of-log-file
C-a : log

The first command sets the name of the file in which the log is recorded. The second command toggles logging on and off. Because this is the first time you typed it, it turns logging on.

We encourage you to create a log of Screen output so that you have a record of everything that happened while you were detached from Screen.

To exit Screen, just type Control-d (without prefacing it with Control-a).

You can learn more about Screen by visiting https://www.gnu.org/software/screen/manual/screen.html.

Reattach to a running Screen session#

You can get a list of what Screen sessions you currently have running by invoking this command from a Bash shell:

screen -list

Your response looks something like the following output:

There are screens on:
some-other-stuff   (Detached)
large-obj-transfer (Detached)
even-more-stuff    (Detached)
Sockets in /var/run/screen/S-root.

To reattach to the Screen session named large-obj-transfer, for example, note the session number (in this example, 3004) and then use the following command:

screen -r 3004

Swiftly example commands#

Important: Swiftly allows destructive actions to run against one or all containers on an account. Use caution when performing updates and deletes to Cloud Files objects because these cannot be undone. Test your commands against test containers wherever possible before running them in production.

Following are some common Swiftly command examples.

Get a list of containers#

Run the following command to get a list of containers for the configured account:

    swiftly get

The response is similar to the following list:

    .ACCESS_LOGS
    .CDN_ACCESS_LOGS
    Books

Get a list of containers with details#

Run the following command to get a list of containers including detailed information:

    swiftly get --raw

The response displays in JavaScript® Object Notation (JSON) format:

    [{"count": 103, "bytes": 22296, "name": ".ACCESS_LOGS"},
    {"count": 126, "bytes": 32708, "name": ".CDN_ACCESS_LOGS"},
    {"count": 417, "bytes": 1177376576, "name": "Books"}]

Get a list of objects in a container#

Run the following command to get a list of objects in a container:

    swiftly get <containerName>

Get containers or objects that match a beginning prefix#

Run the following command to get containers or objects that match a beginning prefix (case sensitive):

    swiftly get --prefix <startingText>

    swiftly get <containerName> --prefix <startingText>

Post new headers to an object#

Run the following command to post new headers to an object (supports multiple headers in a single command, separated as shown):

    swiftly post -h "<headerName1>:<headerValue1>" -h "<headerName2>:<headerValue2>" <containerName>/<objectName>

Upload an object#

The following example uploads the local directory file somefile.png, renames it to newfilename.png in the specified container, and places the object into the pseudo directory /images/).

Run the following command to upload an object:

    swiftly put -i ~/somefile.png <containerName>/images/newfilename.png

Delete an object#

Run the following command to delete an object, or delete an object within a pseudo directory:

    swiftly delete <containerName>/somefile.png
    swiftly delete <containerName>/images/newfilename.png

Delete all objects within a container and delete the container#

Run the following command to delete all objects within a container and delete the container:

    swiftly delete <containerName> --until-empty --recursive

Bulk update#

This command performs a bulk update of all files in a container to add the header HEADERNAME with a value of HEADERVALUE. Note that Swiftly for/do commands contain literal open and close angle bracket characters (< and >), such as <item> in the examples shown here. The angle brackets are part of the command, not placeholders for variable content.

As a best practice with for/do commands, --cache-auth is set to temporarily store the authentication token rather than make repeated calls to the Identity API, and --concurrency is limited to 100 maximum API calls to Cloud Files:

Run the following command to perform a bulk update:

    swiftly --cache-auth --eventlet --concurrency=100 for CONTAINER do post -H "HEADERNAME:HEADERVALUE" "<item>"

Bulk delete specified objects#

Run the following command to perform a bulk delete of only objects within a container whose name begins with a certain prefix (caching the Identity token and limiting to 100 concurrent API calls):

    swiftly --cache-auth --eventlet --concurrency=100 for CONTAINER --prefix STARTINGTEXT --output-names do delete "<item>"

Bulk delete specified containers#

Run the following command to perform a bulk delete of only containers whose name begins with a certain prefix (caching the Identity token and limiting to 100 concurrent API calls):

    swiftly --cache-auth --eventlet --concurrency=100 for "" --prefix STARTINGTEXT --output-names do delete "<item>" --recursive --until-empty