You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- '[S3cmd usage and command reference](https://s3tools.org/usage)'
17
17
---
18
-
19
18
{{< note >}}
20
19
Object Storage is currently in a closed early access Beta, and you may not have access to Object Storage through the Cloud Manager or other tools. To gain access to the Early Access Program (EAP), open up a Customer Support ticket noting that you'd like to be included in the program, or e-mail objbeta@linode.com -- beta access is completely free.
21
20
@@ -26,11 +25,21 @@ Linode's Object Storage is a globally-available, S3- and Swift-compatible method
26
25
27
26
Additionally, **Object Storage does not require the use of a Linode.** Instead, Object Storage gives each object a unique URL with which you can access your data. An object can be publicly accessible, or you can set it to be private and only visible to you. This makes Object Storage great for sharing and storing unstructured data like images, documents, archives, streaming media assets, and file backups, and the amount of data you store can range from small collections of files up to massive libraries of information. Lastly, Linode Object Storage has the built-in ability to [host a static site](/docs/platform/object-storage/host-static-site-object-storage/).
28
27
29
-
Below you will find instructions on how to connect to Object Storage, and how to upload and access objects:
28
+
In this guide you will learn:
29
+
30
+
- How to get set-up for object storage by [creating an Object Storage Key Pair](/docs/platform/object-storage/how-to-use-object-storage/#object-storage-key-pair).
31
+
32
+
- About the variety of first-party and third-party [tools available](/docs/platform/object-storage/how-to-use-object-storage/#object-storage-tools) to access and use the service.
33
+
34
+
- How to connect to Object Storage, how to upload and access objects, and how to host a static site using:
@@ -78,6 +87,8 @@ There are a number of tools that are available to help manage Linode Object Stor
78
87
79
88
- The [Linode Cloud Manager](#cloud-manager) can be used to create buckets (you are currently not able to upload objects to a bucket from the Cloud Manager).
80
89
90
+
- The [Linode CLI](#linode-cli) has an Object Storage plugin and can be used to create and remove buckets, add and remove objects, and convert a bucket into a static site from the command line.
91
+
81
92
-[s3cmd](#s3cmd) is a powerful command line utility that can be used with any S3-compatible object storage service, including Linode's. s3cmd can be used to create and remove buckets, add and remove objects, convert a bucket into a static site from the command line, plus other functions like syncing entire directories up to a bucket.
82
93
83
94
-[Cyberduck](#cyberduck) is a graphical utility available for Windows and macOS and is a great option if you prefer a GUI tool.
@@ -98,12 +109,131 @@ The Cloud Manager provides a web interface for creating buckets. To create a buc
98
109
99
110
100
111
101
-
3. Add a label for your bucket. A bucket's label needs to be unique within the cluster that it lives in, and this includes buckets of the same name on different Linode accounts. If the label you enter is already in use, you will have to choose a different label.
112
+
3. Add a label for your bucket.
113
+
114
+
{{< note >}}
115
+
Bucket labels need to be unique within the same cluster, including buckets on other users' Linode accounts. If the label you enter is already in use, you will have to choose a different label. Additionally, bucket labels have the following rules:</br>
116
+
• Cannot be formatted as IP addresses</br>
117
+
• Must be between 3 and 63 characters in length</br>
118
+
• Can only contain lower-case characters, numbers, periods, and dashes</br>
119
+
• Must start with a lowercase letter or number</br>
120
+
• Cannot contain underscores (_), end with a dash (-) or period (.), have consecutive periods (.), or use dashes (-) adjacent to periods (.)
121
+
{{< /note >}}
102
122
103
123
4. Choose a cluster location for the bucket to reside in.
104
124
105
125
5. Click **Submit**. You are now ready to upload objects to your bucket using one of the other tools outlined in this guide.
106
126
127
+
## Linode CLI
128
+
129
+
The Linode Command Line Interface (CLI) is a command line utility that allows you complete control over your Linode account. With the Object Storage plugin, you can also create and remove buckets, upload objects, and more.
130
+
131
+
### Install and Configure the CLI
132
+
133
+
1. Download the Linode CLI, or, if you have already downloaded it, make sure it has been upgraded to the latest version:
134
+
135
+
pip install linode-cli --upgrade
136
+
137
+
1. Configure the Object Storage plugin:
138
+
139
+
linode-cli obj --help
140
+
141
+
You will be prompted to enter in your Personal Access Token and default settings for deploying new Linodes.
142
+
143
+
1. Install the `boto` module:
144
+
145
+
pip install boto
146
+
147
+
Now you are ready to create buckets and upload objects.
148
+
149
+
### Create a Bucket with the CLI
150
+
151
+
To create a bucket with the Linode CLI, issue the `mb` command.
152
+
153
+
linode-cli obj mb my-example-bucket
154
+
155
+
{{< note >}}
156
+
Bucket labels need to be unique within the same cluster, including buckets on other users' Linode accounts. If the label you enter is already in use, you will have to choose a different label. Additionally, bucket labels have the following rules:</br>
157
+
• Cannot be formatted as IP addresses</br>
158
+
• Must be between 3 and 63 characters in length</br>
159
+
• Can only contain lower-case characters, numbers, periods, and dashes</br>
160
+
• Must start with a lowercase letter or number</br>
161
+
• Cannot contain underscores (_), end with a dash (-) or period (.), have consecutive periods (.), or use dashes (-) adjacent to periods (.)
162
+
{{< /note >}}
163
+
164
+
To delete a bucket, issue the `rb` command:
165
+
166
+
linode-cli obj rb my-example-bucket
167
+
168
+
If your bucket has objects in it, you will not be able to immediately delete it from the Linode CLI. Instead, remove the objects first, then delete the bucket. The [s3cmd](/docs/platform/object-storage/how-to-use-object-storage/#s3cmd) tool has commands for deleting all objects from a bucket, and it can also force-delete a bucket with objects in it.
169
+
170
+
### Upload, Download, and Delete an Object with the CLI
171
+
172
+
1. As an example object, create a text file and fill it with some example text.
173
+
174
+
echo 'Hello World!' > example.txt
175
+
176
+
1. To upload an object to a bucket using the Linode CLI, issue the `put` command. Supply the object name as the first parameter and the bucket label as the second:
177
+
178
+
linode-cli obj put --acl-public example.txt my-example-bucket
179
+
180
+
The file will now be accessible at the URL `http://my-example-bucket.us-east-1.linodeobjects.com/example.txt`.
181
+
182
+
{{< note >}}
183
+
The `--acl-public` flag is used to make the object publicly accessible, meaning that you will be able to access the object from its URL. By default, all objects are set to private. To make a public file private, or a private file public, use the `setacl` command and supply the corresponding flag.
184
+
185
+
For instance, if you want to make a public file private, you would supply the `--acl-private` flag:
1. To download an object, issue the `get` command. Supply the label of the bucket as the first parameter and the name of the file as the second:
191
+
192
+
linode-cli obj get my-example-bucket example.txt
193
+
194
+
1. To delete an object, issue the `rm` or `del` command. Supply the label of the bucket as the first parameter and the name of the object as the second:
195
+
196
+
linode-cli obj rm my-example-bucket example.txt
197
+
198
+
### Create a Static Site with the CLI
199
+
200
+
To create a static website from a bucket:
201
+
202
+
1. Issue the `ws-create` command, including the `--ws-index` and `--ws-error` flags:
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.
207
+
208
+
1. You need to separately upload the `index.html` and `404.html` files (or however you have named the index and error pages) to your bucket:
209
+
210
+
echo 'Index page' > index.html
211
+
echo 'Error page' > 404.html
212
+
linode-cli obj put index.html 404.html my-example-bucket
213
+
214
+
1. Set the `--aclpublic` flag on both the `index.html` and `404.html` files:
1. Your static site is accessed from a different URL than the generic URL for your Object Storage bucket. Static sites are available at the `website-us-east-1` subdomain. Using `my-example-bucket` as an example, navigate to `http://my-example-bucket.website-us-east-1.linodeobjects.com`.
220
+
221
+
For more information on hosting static websites from Linode Object Storage, see our [Host a Static Site on Linode's Object Storage](/docs/platform/object-storage/host-static-site-object-storage/) guide.
222
+
223
+
### Other CLI Commands
224
+
225
+
To get a list of all available buckets, issue the `ls` command:
226
+
227
+
linode-cli obj ls
228
+
229
+
To get a list of all objects in a bucket, issue the `ls` command with the label of a bucket:
230
+
231
+
linode-cli obj ls my-example-bucket
232
+
233
+
For a complete list of commands available with the Object Storage plugin, use the `--help` flag:
234
+
235
+
linode-cli obj --help
236
+
107
237
## s3cmd
108
238
109
239
s3cmd is a command line utility that you can use for any S3-compatible Object Storage.
@@ -165,10 +295,19 @@ You are now ready to use s3cmd to create a bucket in Object Storage.
165
295
166
296
### Create a Bucket with s3cmd
167
297
168
-
You can create a bucket with s3cmd issuing the following `mb` command, replacing `my-example-bucket` with the name of the bucket you would like to create. Bucket names need to be unique within the same cluster, including buckets on other Linode accounts. If you choose a name for your bucket that someone else has already created, you will have to choose a different name:
298
+
You can create a bucket with s3cmd issuing the following `mb` command, replacing `my-example-bucket` with the label of the bucket you would like to create.
169
299
170
300
s3cmd mb s3://my-example-bucket
171
301
302
+
{{< note >}}
303
+
Bucket labels need to be unique within the same cluster, including buckets on other users' Linode accounts. If the label you enter is already in use, you will have to choose a different label. Additionally, bucket labels have the following rules:</br>
304
+
• Cannot be formatted as IP addresses</br>
305
+
• Must be between 3 and 63 characters in length</br>
306
+
• Can only contain lower-case characters, numbers, periods, and dashes</br>
307
+
• Must start with a lowercase letter or number</br>
308
+
• Cannot contain underscores (_), end with a dash (-) or period (.), have consecutive periods (.), or use dashes (-) adjacent to periods (.)
309
+
{{< /note >}}
310
+
172
311
To remove a bucket, you can use the `rb` command:
173
312
174
313
s3cmd rb s3://my-example-bucket
@@ -206,7 +345,7 @@ If you chose to enable encryption when configuring s3cmd, you can store encrypte
206
345
Public URL of the object is: http://us-east-1.linodeobjects.com/my-example-bucket/example.txt
207
346
208
347
{{< note >}}
209
-
The URL for the object that s3cmd provides is one of two valid ways to access your object. The first, which s3cmd provides, places the name of your bucket after the domain name. You can also access your object by affixing your bucket name as a subdomain: `http://my-example-bucket.us-east-1.linodeobjects.com/example.txt`. The latter URL is generally favored.
348
+
The URL for the object that s3cmd provides is one of two valid ways to access your object. The first, which s3cmd provides, places the label of your bucket after the domain name. You can also access your object by affixing your bucket label as a subdomain: `http://my-example-bucket.us-east-1.linodeobjects.com/example.txt`. The latter URL is generally favored.
210
349
{{< /note >}}
211
350
212
351
1. To retrieve a file, issue the `get` command:
@@ -297,7 +436,16 @@ To create a bucket in Cyberduck:
297
436
298
437
299
438
300
-
1. Enter your bucket's name and then click **Create**. Bucket names need to be unique within the same cluster, including buckets on other Linode accounts. If the name of your bucket is already in use, you will have to choose a different name.
439
+
1. Enter your bucket's label and then click **Create**.
440
+
441
+
{{< note >}}
442
+
Bucket labels need to be unique within the same cluster, including buckets on other users' Linode accounts. If the label you enter is already in use, you will have to choose a different label. Additionally, bucket labels have the following rules:</br>
443
+
• Cannot be formatted as IP addresses</br>
444
+
• Must be between 3 and 63 characters in length</br>
445
+
• Can only contain lower-case characters, numbers, periods, and dashes</br>
446
+
• Must start with a lowercase letter or number</br>
447
+
• Cannot contain underscores (_), end with a dash (-) or period (.), have consecutive periods (.), or use dashes (-) adjacent to periods (.)
448
+
{{< /note >}}
301
449
302
450
To delete the bucket using Cyberduck, right click on the bucket and select **Delete**.
303
451
@@ -319,7 +467,7 @@ To delete the bucket using Cyberduck, right click on the bucket and select **Del
319
467
320
468
321
469
322
-
Your object is now accessible via the internet, at the URL `http://my-example-bucket.us-east-1.linodeobjects.com/example.txt`, where `my-example-bucket` is the name of your bucket, and `example.txt` is the name of your object.
470
+
Your object is now accessible via the internet, at the URL `http://my-example-bucket.us-east-1.linodeobjects.com/example.txt`, where `my-example-bucket` is the label of your bucket, and `example.txt` is the name of your object.
323
471
324
472
1. To download an object, right click on the object and select **Download**, or click **Download As** if you'd like to specify the location of the download.
325
473
@@ -345,4 +493,4 @@ To create a static site from your bucket:
345
493
346
494
## Next Steps
347
495
348
-
There are S3 bindings available for a number of programming languages, including the popular [Boto](https://github.com/boto/boto3) library for Python, that allow you to interact with Object Storage programmatically.
496
+
There are S3 bindings available for a number of programming languages, including the popular [Boto](https://github.com/boto/boto3) library for Python, that allow you to interact with Object Storage programmatically.
0 commit comments