S3cmd is a command line utility that you can use for any S3-compatible Object Storage.

Set up s3cmd

Review these sections to install and configure s3cmd.

Prerequisite

You need an Object Storage access key, to grant s3cmd access to your Object Storage buckets and objects. See Manage access keys for instructions, if you don't already have one. Specifically, you'll need these values:

The access key. After you create a key, a unique identifier is assigned to the key.
The secret key. This is a unique secret that Akamai generates for the access key.

📘
The secret key is only displayed a single time, after you create the access key. So, if you don't know this value, you'll need to generate a new access key and be sure to store its secret key.

Install s3cmd

Select a tab for instructions on installing s3cmd on a specific operating system.

To install s3cmd on a macOS, you can use Homebrew:

brew install s3cmd

📘
On macOS, s3cmd installation might fail if you don't have the XCode command line tools installed. Run this command following command:
xcode-select --install

Configure s3cmd

You need to configure s3cmd to work with the buckets and objects on your Akamai Cloud account.

Run the following command to start the configuration process.
```
s3cmd --configure
```
When you're prompted with various questions, answer them based on the recommendations below:
- Access Key. This is your Object Storage access key.
- Secret Key. This is the secret key that was generated for your Object Storage access key. If you don't know this value, you'll need to generate a new access key.
- Default Region. Ensure this is US. Don't set any other value, even if you use Object Storage in a different region.
- Amazon S3 Endpoint. This is the endpoint URL that can be used to access all of your Object Storage resources within a certain region. See Supported endpoint types by region and locate your specific endpoint type's Endpoint (S3 hostname), based on its region. Prepend https:// to it to create a full URL.
- DNS-style bucket+hostname:port template for accessing a bucket. This needs to be %(bucket)s.[region].linodeobjects.com, replacing [region] with the specific region or cluster value from your Amazon S3 Endpoint.
- Encryption password. Enter your GPG key if you need to store and retrieve encrypted files. This is optional.
- Path to GPG program. Enter the path to your GPG encryption program. This is optional, but required if you set an Encryption password.
- Use HTTPS protocol. Set this to Yes
- HTTP Proxy server name. Leave this blank.
- HTTP Proxy server port. Leave this blank.
When you're prompted to test access with the supplied credentials, enter n to skip. Currently, this process results in the following error, even if you include the correct values:
```
Please wait, attempting to list all buckets...
ERROR: Test failed: 403 (SignatureDoesNotMatch)
```
When you're prompted to save your settings, enter Y.

You should now have a configuration file named .s3cfg in your home directory.

Additional configuration options

The s3cmd utility offers several additional configuration options that aren't presented as prompts by the S3cmd --configure command. To modify any s3cmd configuration options, including the ones you've already set, you can edit the configuration file directly. This configuration file is named .s3cfg and should be stored in your local home directory. For our purposes, you can adjust the following option:

website_endpoint: http://%(bucket)s.website-[region].linodeobjects.com/, replacing [region] with the same region or cluster value from your Amazon S3 endpoint.

Example commands

Here are some basic commands you can use to interact with your buckets and objects.

List buckets

List all buckets in the region (or cluster) you set during the configuration process:

s3cmd ls

To list the buckets in a different region, use the --host parameter as shown below. Replace us-east-1 with the region (or cluster) you want to use. Here's an example listing all buckets on your account in the Newark data center, if you'd configured s3cmd for a different region:

s3cmd ls --host=https://us-east-1.linodeobjects.com

Create a bucket

Create a new bucket, by replacing [bucket-label] with a desired name:

s3cmd mb s3://[bucket-label]

📘
Bucket names have requirements
See Manage buckets for rules on naming the bucket.

Delete a bucket

Delete a specific bucket, by replacing [bucket-label] with the name of the target bucket:

s3cmd rb s3://[bucket-label]

You can only use this command to delete a bucket if it's empty. To delete a bucket that has objects in it, include the --recursive (or -r) option and the --force (or -f) option:

s3cmd rb -r -f s3://[bucket-label]

🚧
This command is permanent
Only use this command if you're sure you want to delete everything in the target bucket.

Check disk usage by bucket

You can view the amount of content in a bucket (in bytes) as well as the number of objects. Run this command and replace [bucket-label] with the name of the target bucket:

s3cmd du s3://[bucket-label]

List objects

List all of the objects in a bucket, by replacing [bucket-label] with the name of the target bucket, and [path] with the pseudo directory path, in that bucket:

s3cmd ls s3://[bucket-label]/[path]

Upload an object

Add an object to a bucket with this command. Replace these variable values in the command:

[file]. The complete path and filename of the object you want to upload.
[bucket-label]. The name of the target bucket.
[path]. The pseudo directory path in the bucket where you want to the object to live.

s3cmd put [file] s3://[bucket-label]/[path]

Additionally, you can include these options in this command:

-P. This makes the object publicly accessible. Anyone with the URL to the uploaded object will be able to access it. Once an object is successfully uploaded, s3cmd will output the public URL.
-e. Encrypts the object, if you've configured the correct s3cmd options to enable encryption.

🚧
If you upload an object that uses non-standard special characters or unusual ASCII/Unicode characters in its name, the upload may fail. This includes the characters: : " ' < > & + =.

Download an object or directory

To download a directory or specific object, replace these variable values in the command:

[bucket-label]. The name of the target bucket.
[path]. The full pseudo path to the directory on the bucket you want to download, or the full pseudo path and filename of the specific object to download.

s3cmd get s3://[bucket-label]/[path]

You can also include the -e flag to decrypt an encrypted object.

Delete an object or directory

To delete a directory or a specific object, replace the variable values in the command:

[bucket-label]. The name of the bucket where the target object lives.
[path]. The full pseudo path to the target directory to delete, or the full pseudo path and filename of the specific object to delete.

s3cmd rm s3://[bucket-label]/[path]

Delete all files in a bucket

Use the standard delete command and specify the [bucket-lable] for the target bucket. Also, include the --recursive (or -r) option and the --force (or -f) option:

s3cmd rm -r -f s3://[bucket-label]

🚧
This command is permanent
Only use this specific command and flags if you're sure you want to delete all of the files in the target bucket.

Apply a bucket policy

Bucket policies let you manage permissions and access to Object Storage. They require specific configuration and you can apply them using s3cmd. See Manage access and permissions with bucket policies for complete details.

Create a signed url with s3cmd

A signed URL lets you create a link to objects, with limited permissions and a time limit to access them. To create a signed URL on a preexisting object with s3cmd, use this command, replacing the variable values:

[bucket-label]. The name of the bucket where the target object lives.
[path]. The full pseudo path and filename of the specific object.
[seconds]. The amount of time in seconds that the link remains active.

s3cmd signurl s3://[bucket-label]/[path] +[seconds]

The output of the command is a URL that you can be for [seconds] to access the object, even if the ACL is set to private. After this time has passed, the link expires and can no longer be used.

Create a static site with s3cmd

You can also create a static website using Object Storage and s3cmd:

📘
Legacy endpoints, only
Static websites are only supported with legacy endpoints (E0 and E1).

To create a website from a bucket, use the ws-create command:
```
s3cmd ws-create --ws-index=index.html --ws-error=404.html s3://my-example-bucket
```
The --ws-index and --ws-error flags specify which objects the bucket should use to serve the static site's index page and error page, respectively.

Upload the index.html and 404.html files (or however you have named the index and error pages) to the bucket:

echo 'Index page' > index.html
echo 'Error page' > 404.html
s3cmd put index.html 404.html s3://my-example-bucket

The static site is accessed from a different URL than the generic URL for the Object Storage bucket. Static sites are available at the website-us-east-1 subdomain for the Newark data center, the website-eu-central-1 subdomain for the Frankfurt data center, and the website-ap-south-1 subdomain for the Singapore data center. Using my-example-bucket as an example, you would navigate to either:
- http://my-example-bucket.website-us-east-1.linodeobjects.com or
- http://my-example-bucket.website-eu-central-1.linodeobjects.com.

For more information on hosting a static website with Object Storage, see Deploy a Static Site using Hugo and Object Storage.

Sync files and directories

While you can use the put command to upload entire directories, the sync command may offer more desirable behavior. The sync command identifies which files have been added or modified and only uploads those files. This can help if you're managing large amounts of files, such as the contents of a static site.

Run this command, replacing these variable values:

[local-path]. The path to the folder you wish to upload. To upload the current directory, set this to ./.
[bucket-label]. The name of the target bucket.
[path]. The pseudo path in the bucket you want to target for the upload.

s3cmd sync [local-path] s3://[bucket-label]/[path]