Versions Compared

Old Version 9

changes.mady.by.user Kyle Miller (Deactivated)

Saved on

compared with

New Version Current

changes.mady.by.user Kyle Miller (Deactivated)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Document Identifier:

TechNote 2015002 (replaces TechNote 2011004)

Document Date:

July 24, 2015

Software Package:

SWARM

Version:

Swarm 7 or later

Abstract

This technical note provides examples for using curl cURL with Swarm version 7.0 or later. curl cURL can be useful for performing specific tasks, such as executing all SCSP methods, including those that require authentication, and can assist you with verifying that your client and Swarm are working properly. See the SDK Overview for detailed information about programming for Swarm.

curl (also referred to as cURL ) is a free, open source command-line utility that runs in a variety of operating systems, including Windows and UNIX. The functionality of curl cURL is also made available as a programming library called libcurl. For more information about curlcURL, see one of the following resources:

...

  • You are familiar with using curlcURL.

  • You are using curl cURL version 7.20.1 or later

  • You are familiar with the Simple Content Storage Protocol (SCSP), the protocol used by Swarm clients.

  • Your cluster runs Swarm version 7.0 or later.

  • You can communicate with at least one node in the cluster using a computer that runs either Windows or Linux.

Getting Started

To make sure you can communicate with your Swarm cluster, open a command prompt window and ping a node in the cluster:

Code Block
ping cluster-node-ip

For example:

Code Block
ping 172.16.0.32

If the node does not respond, try to ping another node IP address. Do not continue until you can successfully ping a node in your cluster.  This verifies ICMP reachability but not necessarily that the node is available on port 80 for HTTP requests.  It is not definitive, as a node could potentially be unavailable via ICMP through the network, but still be available via port 80.  Regardless, it is a good, simple test for reachability.  Similarly, you could run the following to test port 80:

Code Block
telnet 172.16.0.32 80

How to Correctly Use

...

cURL

Even if you are accustomed to using curl cURL to communicate with a web server, you might not know some of the differences necessary to communicate with Swarm. Although Swarm uses the HTTP protocol, Swarm uses more of the HTTP specification than does a typical web server.

Based on our experience, DataCore provides the following recommendations for avoiding common curl cURL mistakes:

  • Use the correct curl cURL version!

  • SCSP and HTTP method names

  • Use only plain ASCII text

  • Send binary data to Swarm in binary format using --data-binary

  • Enclose the location (that is, URL) in single quotes

  • Use --anyauth and --location-trusted with authentication (Swarm 5.0 and later)

  • Understand how to interpret curl cURL output

Use a recent

...

cURL version

...

Older versions of curl cURL do not support --post301, which prevents curl cURL from following redirects in the cluster using the original HTTP method (without --post301, an HTTP GET is substituted for the original SCSP method). As a result, any request that is redirected from the first node of contact fails.

DataCore recommends you use the most recent available version of curlcURL. Some operating systems, such as CentOS 5.5, have older versions of curl cURL that do not work with Swarm. Before continuing, verify the curl cURL version you are using and upgrade it if necessary.

To verify your curl cURL version, enter curl --version. Follow the documentation provided with your operating system, or the curl cURL man page, for more information about upgrading curlcURL.

SCSP and HTTP method names

When you execute methods using curlcURL, you must use HTTP method names; however, this Tech Note uses SCSP method names except when showing curl cURL command examples. For more information about SCSP and HTTP method names, see SCSP Essentials and SCSP Methods.

Plain text only

curl cURL accepts commands in plain ASCII text only; for example, you must use straight quotes (') and not "curly" quotes (´). Some characters in this Tech Note might paste into a command prompt as non-ASCII text characters. Check your command carefully for non-ASCII characters before you execute it.

Use --data-binary and not –d

To send data to Swarm, always use the --data-binary option because it sends binary data to Swarm in binary format. If you are used to using curl cURL to send data to a web server, you might make the mistake of using –d option, which translates binary data to text.

-d is intended to send HTML form-posted data of Content-Type application/x-www-form-urlencoded, which works for a Web server but not always for Swarm!

Always enclose the location in quotes

The location, or the URL to which the command is being sent, must be enclosed in single quotes. This prevents special characters in the URL, such as ? and & used in query arguments, from being interpreted as commands by the command shell.

...

The examples in this Tech Note always use --location-trusted for consistency.

Interpreting

...

cURL –v(erbose) Output

Most of the examples in this Tech Note use curl cURL with the –voption, which displays “verbose” output. curl’s cURL’s verbose output can indicate communication problems with the cluster and other important diagnostic information.

...

The following table explains the italicized lines in curl cURL output:

Line

Meaning

Connected to 172.16.0.32 (172.16.0.32) port 80

Confirms the IP address and port of the node with which you are communicating.

POST / HTTP/1.1

Displays the SCSP method name (in this case, WRITE).

User-Agent: ...

Displays the name and version information about your curl cURL client. This value is intentionally omitted in the examples in this Tech Note.

HTTP/1.1 301 Moved Permanently

Does not always display but if so, is normal. This message indicates that the primary access node (PAN) redirected your request to another node in the cluster.

HTTP/1.1 201 Created

Indicates the request was successful.

Location: http://172.16.0.32:80/b64d2b22cd2ca0c8300ffecb337181e5

Displays the URL to the object.

Server: CAStor Cluster/7.5.1

Displays the Swarm version running on the responding node.

<html><body>New stream created</body></html>

Swarm’s response, which indicates the method completed successfully.

Summary of Selected Commands

Following are selected sample commands discussed in this Tech Note. The commands show how to execute all seven SCSP methods on mutable unnamed objects (also called anchor streams) and on named objects.

...

You can use the same commands for unnamed immutable objects as well (minus the ?alias query argument); however, the only SCSP methods supported by immutable objects are WRITE, DELETE, READ, and INFO.

SCSP WRITE

Unnamed mutable:

Code Block
curl -v --post301 -X POST --data-binary '<h1>Hello world</h1>' -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/?alias'

Named (requires a previously created domain and bucket- see later in the doc for examples):

Code Block
curl -v --post301 -X POST --data-binary '<h1>Hello world</h1>' -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/bucket-name/object-name?domain=domain-name'

SCSP APPEND

Unnamed mutable:

Code Block
curl -v --post301 -X APPEND --data-binary 'text' --location-trusted  'http://node-ip-address/UUID-to-APPEND?alias'

Named:

Code Block
curl -v --post301 -X APPEND --data-binary 'text' --location-trusted 'http://node-ip-address/bucket-name/object-name?domain=domain-name'

SCSP COPY

Unnamed mutable:

Code Block
curl -v --post301 -X COPY -H 'x-custom-meta-data-header:metadata-value' --location-trusted 'http://node-ip-address/UUID-to-COPY?alias'

Named:

Code Block
curl -v --post301 -X COPY -H 'x-custom-meta-data-header:metadata-value' --location-trusted 'http://node-ip-address/bucket-name/object-name?domain=domain-name'

SCSP UPDATE

Unnamed mutable:

Code Block
curl -v --post301 -X PUT --data-binary '<h2>Goodbye</h2>' -H 'Content-type: text/html' -H 'x-custom-meta-data-header:metadata-value' --location-trusted 'http://node-ip-address/UUID-to-UPDATE?alias'

Named:

Code Block
curl -v --post301 -X PUT --data-binary '<h2>Goodbye</h2>' -H 'Content-type: text/html' -H 'x-custom-meta-data-header:metadata-value' --location-trusted 'http://node-ip-address/bucket-name/object-name?domain=domain-name'

SCSP READ

Unnamed mutable:

Code Block
curl -v --post301 --location-trusted 'http://node-ip-address/UUID-to-READ?alias'

Named:

Code Block
curl -v --post301 --location-trusted 'http://node-ip-address/bucket-name/object-name?domain=domain-name'

SCSP INFO

Unnamed mutable:

Code Block
curl -v -I --post301 --location-trusted 'http://node-ip-address/UUID-to-INFO?alias'

Named:

Code Block
curl -v -I --post301 --location-trusted 'http://node-ip-address/bucket-name/object-name?domain=domain-name'

SCSP DELETE

Unnamed mutable:

Code Block
curl -v --post301 -X DELETE --location-trusted 'http://node-ip-address/UUID-to-UPDATE?alias'

Named:

Code Block
curl -v --post301 -X DELETE --location-trusted 'http://node-ip-address/bucket-name/object-name?domain=domain-name'

Working With Unnamed Objects

This section provides examples of using curl cURL to work with unnamed objects. The term unnamed object includes both immutable objects and mutable objects (which are also referred to as anchor streams).

...

Assumption: You use the default port 80 for SCSP. If you use a different port, you must include it in the URL.

Write a New Immutable Object

WRITE a string:

Code Block
curl -v --post301 –X POST --data-binary '<h1>Hello world</h1>' -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/'

WRITE a file:

Code Block
curl -v --post301 -X POST --data-binary @Hello_World.html -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/'

For the preceding command to work, Hello_World.html must be in a location accessible by curl cURL and it must have HTML contents, such as <h1>Hello World</h1>. (Include the path to the file if necessary as @path-to-file/Hello_World.html.)

To view the object (that is, execute the READ method), paste the URL displayed in the Location response into a web browser’s address or location field.

INFO an Unnamed Immutable Object

An INFO differs from a READ in that only the metadata stored with the object is returned. The object’s contents are not returned if you INFO the object.

Code Block
curl -I --post301 --location-trusted 'http://value-of-Location-header'

For example,

Code Block
curl -I --post301 --location-trusted 'http://172.16.0.32:80/3c0723bd9f555df9645c266227ee5fa2'

Sample response:

HTTP/1.1 200 OK
Castor-System-Created: Sat, 19 Mar 2015 19:18:42 GMT
Content-Length: 33
Content-type: text/html
Last-Modified: Sat, 19 Mar 2015 19:18:42 GMT
Etag: "3c0723bd9f555df9645c266227ee5fa2"
Date: Sat, 19 Mar 2015 19:22:41 GMT
Server: CAStor Cluster/7.5.1

DELETE an Unnamed Immutable Object

To delete an unnamed immutable object, you must know the value of the object’s Location header.

Code Block
curl -v -X DELETE --post301 --location-trusted 'http://value-of-Location-header'

For example,

Code Block
curl -v -X DELETE --post301 --location-trusted 'http://172.16.0.32:80/3c0723bd9f555df9645c266227ee5fa2'

If you now try to READ or INFO the object, Swarm responds with 404 (Not Found) or with a Swarm Error.

Working With An Unnamed Mutable Object

An unnamed mutable object is one that can be changed using UPDATE, APPEND, COPY, or DELETE. You can also READ and INFO the object. This example shows how to create a new mutable object, how to modify it using UPDATE, add data to it using APPEND, COPY metadata, then READ and INFO the object before you DELETE it.

The ?alias (optionally ?alias=yes) query argument is only required on POST when creating a mutable unnamed object in Swarm >= 7.x.  It will not be shown in subsequent examples where unnecessary as the examples are created in post 7.x Swarm code.

Create the object using POST

WRITE a string:

Code Block
curl -v --post301 -X POST --data-binary '<h1>Hello world</h1>' -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/?alias'

WRITE a file:

Code Block
curl -v --post301 -X POST --data-binary @Hello_World.html -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/?alias'

For the preceding command to work, Hello_World.html must be in a location accessible by curl cURL and it must have HTML contents, such as <h1>Hello World</h1>. (Include the path to the file if necessary as @path-to-file/Hello_World.html.)

READ the Object

Verify the object was created successfully by pasting the value of the Location header in a browser.

Add data to the object using APPEND

Code Block
curl -v --post301 -X APPEND --data-binary '<br>...more data' --location-trusted 'value-of-Location-header'

For example,

Code Block
curl -v --post301 -X APPEND --data-binary '<br>...more data' --location-trusted 'http://172.16.0.32:80/10eb3d3fba8ddd6f60dfbf89e4aed3e4'

Refresh your web browser to see how the object changed.

Note: Although this example shows how to append data to an object, APPEND can also be used to append metadata to the object as well.

Add custom metadata to the object using COPY

Swarm enables you to add custom metadata in the format x-*-meta-*. Custom metadata added in this way is case-insensitive (to be consistent with section 4.2 of RFC 2616) and can contain ASCII characters only. The total length of all persisted metadata, keys and values, is limited to 32KB.

You can add metadata headers to an object using the UPDATE method (which replaces the object's data and metadata) or using COPY (which replaces the metadata only).

Code Block
curl -v --post301 -X COPY -H 'x-custom-meta-data-header:metadata-value' --location-trusted 'value-of-Location-header'

For example,

Code Block
curl -v --post301 -X COPY -H 'x-ExampleCorp-meta-color: blue' --location-trusted 'http://172.16.0.32:80/90eee0a3170bf8fca313532e70b37eec'

INFO the object to verify the header:

Code Block
curl -I --location-trusted 'http://172.16.0.32:80/90eee0a3170bf8fca313532e70b37eec'

A sample response follows (the custom metadata header is displayed in italicized type for emphasis):

...

Note: If you send a Content-Length header, you must set it to 0 because a COPY has no data.

Replace data and metadata using UPDATE

UPDATE is very similar to COPY except that UPDATE also replaces the object's contents as well as its metadata.

Try UPDATE on the preceding example as follows:

Code Block
curl -v --post301 -X PUT --data-binary '<h2>Goodbye</h2>' -H 'Content-type: text/html' -H 'x-ExampleCorp-meta-color: orange' --location-trusted 'http://node-ip-address/value-of-Location-header'

For example,

Code Block
curl -v --post301 -X PUT --data-binary '<h2>Goodbye</h2>' -H 'Content-type: text/html' -H 'x-ExampleCorp-meta-color: orange' --location-trusted 'http://172.16.0.32:80/90eee0a3170bf8fca313532e70b37eec'

INFO the object to verify the header:

Code Block
curl -I --location-trusted 'http://172.16.0.32:80/90eee0a3170bf8fca313532e70b37eec'

A sample follows:

HTTP/1.1 200 OK
Castor-System-Alias: 90eee0a3170bf8fca313532e70b37eec
Castor-System-Created: Sat, 19 Mar 2015 22:11:33 GMT
Castor-System-Version: 1438101372.519
Content-Length: 0
Last-Modified: Sat, 19 Mar 2015 22:11:33 GMT
x-ExampleCorp-meta-color: orange
Etag: "a6d10b1786ddfc40e9f06e5e385295a0"
Date: Sat, 19 Mar 2015 22:11:38 GMT
Server: CAStor Cluster/7.5.1

Refresh your browser window to see the change in the object's contents.

DELETE the mutable object

Code Block
curl -v --post301 -X DELETE --location-trusted 'value-of-Location-header?alias'

Paste the value of the Location header in a web browser, or INFO the object, to verify you get a 404 (Not Found) or a Swarm Error.

Beyond the Basics With Unnamed Objects

This section discusses more advanced actions, such as using curl cURL for performance, immediate replication (also referred to as replicate-on-write, lifepoint headers, and range reads).

Performance tip

curlcURL's output to the command prompt can drastically skew or slow response times. If you use curl cURL for performance reasons, use -s (silent) and -o /dev/null (output). For example,

Code Block
curl -s --post301 –X POST --data-binary '<h1>Outperform me</h1>' -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/?alias' –o /dev/null

Immediate replication (replicate-on-write)

To create a mutable unnamed object and replicate it immediately:

Code Block
curl -v --post301 –X POST --data-binary '<h1>Replicate me</h1>' -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/?alias&replicate=immediate'

INFO the object to get its replica count:

Code Block
curl -I --location-trusted 'value-of-Location-header?countreps=yes'

For example:

Code Block
curl -I --location-trusted 'http://172.16.0.32/cd0e8d605372a4d21b660000fc807c1b?countreps=yes'

Sample response (the Replica-Count header is displayed in italicized text for emphasis):

HTTP/1.1 200 OK
Castor-System-Alias: cd0e8d605372a4d21b660000fc807c1b
Castor-System-Created: Thu, 17 Mar 2015 21:45:47 GMT
Castor-System-Version: 1438101372.519
Content-Length: 0
Content-type: text/html
Last-Modified: Thu, 17 Mar 2015 21:45:47 GMT
lifepoint: [Fri, 18 March 2015 10:15:00 GMT] reps=2, deletable=True, [] delete
Replica-Count: 2
Etag: "7a1f8719a80df7065d1b5ce4ef30403b"
Date: Thu, 17 Mar 2015 22:01:20 GMT
Server: CAStor Cluster/7.5.1

Range READ

Code Block
curl -v --location-trusted 'value-of-Location-header' -r range-in-bytes

For example:

Code Block
curl -v --location-trusted 'http://172.16.0.32/ad20eb6cbb3e38de3b13613c334012f5?alias' -r 100-500

The response depends on the type of file you are reading. For example, following is a partial response if you request bytes 399-600 from the Henry Ford biography from Wikipedia (assuming you had previously stored it in your cluster):

...

< Content-Range: bytes 399-600/219136
Content-Range: bytes 399-600/219136
< Content-Length: 202
Content-Length: 202
< Etag: "25d456df70ba3813d5490bceaa71cb79"
Etag: "25d456df70ba3813d5490bceaa71cb79"
< Age: 97
Age: 97
< Date: Thu, 17 Mar 2015 23:11:09 GMT
Date: Thu, 17 Mar 2015 23:11:09 GMT
< Server: CAStor Cluster/7.5.1
Server: CAStor Cluster/7.5.1
<
Henry Ford - Wikipedia, the free encyclopedia</title>
<meta http-equiv="Content-Style-Type" content="text/css">
<meta name="generator" content="MediaWiki 1.17wmf1">
* Connection #0 to host 172.16.0.32 left intact
* Closing connection #0

WRITE a New Mutable Object With a Lifepoint Header

Code Block
curl -v --post301 –X POST --data-binary '<h1>Lifepoint example</h1>' -H 'Content-type: text/html' -H 'lifepoint: [http-date] reps=2, deletable=True, [] delete' --location-trusted 'http://node-ip-address/?alias'

Set http-date to an HTTP 1.1 specification-formatted date that is at least an hour from now. An example follows:

Code Block
curl -v --post301 -X POST --data-binary '<h1>Hello world</h1>' -H 'Content-type: text/html' -H 'lifepoint: [Friday, 18 March 2015 10:15:00 GMT] reps=2, deletable=True, [] delete' --location-trusted 'http://172.16.0.32/?alias'

The preceding command creates an object that initially has two replicas, both of which are deleted at http-date.

To verify the lifepoint headers, INFO the object using the following command:

Code Block
curl -I --post301 --location-trusted 'value-of-Location-header'

A response similar to the following displays to indicate the object was found, and it displays the object’s lifepoint header:

HTTP/1.1 200 OK
Castor-System-Created: Thu, 17 Mar 2015 01:18:32 GMT
Content-Length: 33
Content-type: text/html
Last-Modified: Thu, 17 Mar 2015 01:18:32 GMT
lifepoint: [Friday, 18 March 2015 10:15:00 GMT] reps=2, deletable=True, [] delete
Etag: "236a921048fa3a4fb31cdda452f2c0a0"
Date: Thu, 17 Mar 2015 01:19:00 GMT
Server: CAStor Cluster/7.5.1

Add a lifepoint header to a mutable object using UPDATE

Code Block
curl -v --post301 -X PUT -H 'lifepoint: [http-date] reps=2, deletable=True, [] delete' --location-trusted 'value-of-Location-header/'

Set http-date to a HTTP 1.1 specification-formatted date that is at least an hour from now. An example follows:

Code Block
curl -v --post301 -X PUT -H 'Content-type: text/html' -H 'lifepoint: [Fri, 18 March 2015 10:15:00 GMT] reps=2, deletable=True, [] delete' --location-trusted 'http://172.16.0.32:80/cd0e8d605372a4d21b660000fc807c1b'

Verify the headers on the object using the following command:

Code Block
curl -I --post301 --location-trusted 'value-of-Location-header'

A sample follows (the lifepoint header is displayed in italicized type for emphasis):

...

This response confirms you updated the lifepoint header successfully.

Working With Named Objects

This section discusses how to verify you can perform SCSP operations on named objects.

Brief Introduction to Named Objects

Before you can create named objects, your cluster administrator must create at least one tenant (that is, domain). DataCore recommends you use the default cluster domain for these examples but that is not required.

The default cluster domain is defined as a domain whose name exactly matches the value of the cluster configuration parameter in the node or cluster configuration file. Swarm assumes that the domain is set to the default cluster domain if you omit the ?domain= query argument from your curl cURL commands.

In other words, if cluster.example.com is the default cluster domain, the following curl cURL commands are equivalent:

Code Block
curl --location-trusted 'http://172.16.0.32/mybucket?domain=cluster.example.com'
Code Block
curl --location-trusted 'http://172.16.0.32/mybucket'

For more information about creating a tenant and a domain, see the Swarm Guide, under Configuration and Administration.

...

  • The IP address of one node in the cluster.

  • The name of the domain and whether or not it is the default cluster domain. If the domain is not the default cluster domain, you must add the ?domain=domain-name query argument to every curl cURL command.

  • The domain’s protection setting, which defines the users who can WRITE in the domain.  This document will not address authentication.

  • If you do not use the default port 80 for SCSP, you must include the port in the URL.

Creating the Domain

This section describes how to create the mycluster.example.com domain. All tasks discussed in this section require you to authenticate as a user in the Swarm administrators user list.   It is preferred to create the domain using the Swarm user interface if possible.

...

1. Create the mycluster.example.com domain:

Code Block
curl -v --post301 -X POST -H 'Castor-Stream-Type: admin' -H 'Allow-Encoding: *;q=0' -H 'lifepoint: [] reps=16' --data-binary '' --location-trusted 'http://172.16.0.35?domain=mycluster.example.com&admin&createDomain' --anyauth -u 'admin:ourpwdofchoicehere' [-D log-file-name]

Caution — Be sure to enter these headers exactly as shown so that they match the headers used when domains are created by the Console. lifepoint: [] reps=16 enables the domain to be replicated as many times as possible. Use Castor-Stream-Type: admin for all root objects that are accessed frequently and all objects that use a Castor-Authorization header.

...

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Digest realm="CAStor administrator",
nonce="e9d618c06bbeca15e7568aca2f
opaque="f9bcffd26d1bede5419a2b30cbcff976",
stale=false, qop="auth", algorithm=MD5
WWW-Authenticate: Basic realm="CAStor administrator"
Content-Length: 51
Content-Type: text/html
Date: Fri, 04 Nov 2011 16:22:53 GMT
Server: CAStor Cluster/6.0.0
Allow: HEAD, GET, PUT, POST, COPY, APPEND, DELETE
HTTP/1.1 201 Created
Content-UUID: 68aeb6c78e4ca0101f3936c03fa26e72
Location: http://172.16.0.35:80/?domain=mycluster.example.com      com
Volume: 064d2cc2392810dcc2d04f7b1023ecc7

...

Entity-MD5: ZoxbtOo9PhHyZzAbaqa/Pw==
Stored-Digest: 668c5bb4ea3d3e11f267301b6aa6bf3f
Castor-System-Owner: admin@CAStor administrator
Castor-System-Version: 1320

Creating the Bucket

Once you have a domain, you need one or more buckets to write your data streams into.  If you do not create a bucket, and you write named streams into your domain, the streams will be assumed to be buckets.  For example, if you write a stream called: http://172.16.0.35/stream1?domain=mycluster.example.com, stream1 will be considered a bucket, not a regular stream.  This is not desirable as different replication policies apply to context streams (domains and buckets) than to streams.

...

WRITE a bucket without authentication

Code Block
curl -v --post301 -X POST --data-binary '' --location-trusted 'http://node-ip-address/bucket-name[?domain=domain-name]’

(?domain-name is not required if you are creating a bucket in the default cluster domain.)

Code Block
curl -v --post301 -X POST --data-binary '' --location-trusted 'http://172.16.0.35/mybucket?domain=mycluster.example.com'

Verify the bucket.

Code Block
curl --post301 -I --location-trusted 'http://172.16.0.35/mybucket[?domain=mycluster.example.com]'

A sample response follows (the authorization specification is displayed in italicized type for emphasis):

HTTP/1.1 200 OK
Castor-System-Alias: 759db90c1b81d695837d54261df90c53
Castor-System-CID: 4a89010e358d48c3040778f35282238e
Castor-System-Cluster: mycluster.example.com
Castor-System-Created: Mon, 21 Mar 2015 23:29:28 GMT
Castor-System-Name: mybucket
Castor-System-Version: 1438101372.519
Content-Length: 0
Content-Type: application/x-www-form-urlencoded
Last-Modified: Mon, 21 Mar 2015 23:29:28 GMT
Etag: "f21a6e2e847539049d3f83c508fa0986"
Age: 114
Date: Mon, 21 Mar 2015 23:32:49 GMT
Server: CAStor Cluster/7.5.1

Named Objects

WRITE an object in a bucket

WRITE a string:

Code Block
curl -v --post301 -X POST --data-binary '<h1>Hello world</h1>' -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/bucket-name/technote.html[?domain=domain-name]'

WRITE a file:

Code Block
curl -v --post301 -X POST --data-binary @Hello_world.txt -H 'Content-type: text/html' --location-trusted 'http://node-ip-address/bucket-name/technote.html[?domain=domain-name]'

Verify the object in a web browser

Enter the following URL in your web browser’s location or address field:

...

Hello World displays in bold text.

Add data to the object using APPEND

Code Block
curl -v --post301 -X APPEND --data-binary '<br>...more data' --location-trusted 'http://node-ip-address/bucket-name/technote.html[?domain=domain-name]'

Verify the append succeeded by refreshing your web browser window.

Add custom metadata using COPY

Code Block
curl -i -v --post301 -X COPY -H 'x-NamedObject-meta-data: NameOne' --location-trusted 'http:// node-ip-address/bucket-name /technote.html[?domain=domain-name]'

INFO the object to verify the metadata.

Code Block
curl --post301 -I --location-trusted 'http://172.16.0.32/bucket/technote.html'

A sample response follows:

HTTP/1.1 200 OK
Castor-System-CID: 74888c3f62ebd05e53bf442eb6a7d98c
Castor-System-Cluster: mycluster.example.com
Castor-System-Created: Sat, 19 Mar 2015 22:58:48 GMT
Castor-System-Name: technote.html
Castor-System-Version: 1438101372.519
Content-Length: 0
Last-Modified: Sat, 19 Mar 2015 22:58:48 GMT
x-NamedObject-meta-data: NameOne
Etag: "258de599945736b9bb26247ac8229e5f"
Date: Sat, 19 Mar 2015 22:59:13 GMT
Server: CAStor Cluster/7.5.1

Replace data and metadata using PUT

Code Block
curl -v --post301 -X PUT --data-binary '<h2>Goodbye</h2>' -H 'Content-type: text/html' -H 'x-NamedObject-meta-data: NameTwo' --location-trusted 'http://node-ip-address/bucket-name/technote.html[?domain=domain-name]'

INFO the object to verify the metadata.

Code Block
curl --post301 -I --location-trusted 'http://172.16.0.32/bucket/technote.html'

A sample response follows:

...

Refresh your browser window to see the object's data.

Delete the named object

Code Block
curl -v --post301 -X DELETE --location-trusted 'http://node-ip-address/bucket-name/technote.html'

Verify the delete succeeded by refreshing your web browser window or using an INFO. You should get a 404 (Not Found) or a Swarm Error.

HTTP and SCSP Methods

Swarm clients use the Simple Content Storage Protocol (SCSP) to communicate with Swarm. SCSP is a subset of HTTP 1.1 as defined in RFC 2616. Some SCSP methods have different names than their HTTP counterparts.

When you execute methods using curlcURL, you must use HTTP method names; however, this Tech Note uses SCSP method names except when showing curl cURL command examples.

The following tables map SCSP method names to their HTTP method counterparts. A link is provided in the HTTP method column to the relevant section in RFC 2616. For more information about SCSP methods, see the Swarm Guide.

...