~annegentle/openstack-devel/working

<title>Using cURL</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"/><link rel="home" href="index.html" title="OpenStack Object Storage Developer Guide"/><link rel="up" href="ch04.html" title="Chapter 4. Troubleshooting"/><link rel="prev" href="ch04.html" title="Chapter 4. Troubleshooting"/><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><script type="text/javascript">

//The id for tree cookie

var treeCookieId = "treeview-2458";

var language = "en";

var w = new Object();

//Localization

txt_filesfound = 'Results';

txt_enter_at_least_1_char = "You must enter at least one character.";

txt_browser_not_supported = "Your browser is not supported. Use of Mozilla Firefox is recommended.";

txt_please_wait = "Please wait. Search in progress...";

txt_results_for = "Results for: ";

</script><style type="text/css">

input {

margin-bottom: 5px;

margin-top: 2px;

}

.folder {

display: block;

height: 22px;

padding-left: 20px;

background: transparent url(../common/jquery/treeview/images/folder.gif) 0 0px no-repeat;

}

</style><link rel="shortcut icon" href="../favicon.ico" type="image/x-icon"/><link rel="stylesheet" type="text/css" href="../common/css/positioning.css"/><link rel="stylesheet" type="text/css" href="../common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css"/><link rel="stylesheet" type="text/css" href="../common/jquery/treeview/jquery.treeview.css"/><script type="text/javascript" src="../common/jquery/jquery-1.4.2.min.js"></script><script type="text/javascript" src="../common/jquery/jquery-ui-1.8.2.custom.min.js"></script><script type="text/javascript" src="../common/jquery/jquery.cookie.js"></script><script type="text/javascript" src="../common/jquery/treeview/jquery.treeview.min.js"></script><script type="text/javascript" src="search/htmlFileList.js"></script><script type="text/javascript" src="search/htmlFileInfoList.js"></script><script type="text/javascript" src="search/nwSearchFnt.js"></script><script type="text/javascript" src="search/stemmers/en_stemmer.js"/><script type="text/javascript" src="search/index-1.js"></script><script type="text/javascript" src="search/index-2.js"></script><script type="text/javascript" src="search/index-3.js"></script></head><body><div id="header"><img src="../common/images/openstack-logo.png" alt="OpenStack Documentation" width="157" height="47"/><p class="breadcrumbs"><a href="#">OpenStack Manuals</a><a href="#">Object Storage</a></p><h1>Using cURL<br/>Chapter 4. Troubleshooting</h1><div id="navheader" align="right"><table class="navLinks"><tr><td><a id="showHideButton" onclick="showHideToc();" class="pointLeft" title="Hide TOC tree">Sidebar

</a></td><td><a accesskey="p" class="navLinkPrevious" href="ch04.html">Prev</a>

<a accesskey="u" class="navLinkUp" href="ch04.html">Up</a></td></tr></table></div></div><div id="content"><div class="section" title="Using cURL"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="d5e716"/>Using cURL</h2></div></div></div>

<p>cURL is a command-line tool which is available on most UNIX®-like environments and Mac

OS X® and can be downloaded for Windows®. For more information on cURL, visit <a class="ulink" href="http://curl.haxx.se/" target="_top">http://curl.haxx.se/</a>. </p>

<p>cURL allows you to transmit and receive HTTP requests and responses from the

command-line or from within a shell script. This makes it possible to work with the ReST API

directly without using one of the client APIs. </p>

<p>The following cURL command-line options will be used</p>

<div class="variablelist" title="cURL Command-Line Options"><p class="title"><strong>cURL Command-Line Options</strong></p><dl><dt><span class="term"><code class="option">-X METHOD</code></span></dt><dd>

<p>Specify the HTTP method to request (<code class="code">HEAD</code>, <span class="command"><strong>GET</strong></span>,

etc.)</p>

</dd><dt><span class="term"><code class="option">-D</code></span></dt><dd>

<p>Dump HTTP response headers to stdout.</p>

</dd><dt><span class="term"><code class="option">-H HEADER</code></span></dt><dd>

<p>Specify an HTTP header in the request.</p>

</dd></dl></div>

<div class="section" title="Authentication"><div class="titlepage"><div><div><h3 class="title"><a id="d5e741"/>Authentication</h3></div></div></div>

<p>In order to use the ReST API, you will first need to obtain a authorization token,

which will need to be passed in for each request using the <code class="code">X-Auth-Token</code>

header. The following example demonstrates how to use cURL to obtain the authorization

token and the URL of the storage system.</p>

<div class="example"><a id="d5e745"/><p class="title"><strong>Example 4.1. cURL Authenticate</strong></p><div class="example-contents">

<span class="command"><strong>curl</strong></span> <code class="option">-D</code> - \

<code class="option">-H "X-Auth-Token: a86850deb2742ec3cb41518e26aa2d89"</code> \

<code class="option">-H "X-Auth-User: jdoe"</code> \

<code class="uri">https://auth.api.yourcloud.com/v1.0</code>

</pre>

<code class="computeroutput">HTTP/1.1 204 No Content

Date: Thu, 09 Jul 2009 15:31:39 GMT

Server: Apache/2.2.3

X-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_343

X-CDN-Management-Url: https://cdn.swiftdrive.com/v1/CF_xer7_343

X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae

Content-Length: 0

Connection: close

Content-Type: application/octet-stream

</code></pre>

</div></div><br class="example-break"/>

<p>The storage URL, CDN management URL, and authentication token are returned in the

headers of the response. After authentication, you can use cURL to perform

<code class="code">HEAD</code>, <span class="command"><strong>GET</strong></span>, <span class="command"><strong>DELETE</strong></span>, <span class="command"><strong>POST</strong></span> and <span class="command"><strong>PUT</strong></span> requests on the storage and CDN

services.</p>

</div>

<div class="section" title="Determining Storage Usage"><div class="titlepage"><div><div><h3 class="title"><a id="d5e761"/>Determining Storage Usage</h3></div></div></div>

<p>A <code class="code">HEAD</code> request can be sent to the storage service to determine how much

data you have stored in the system and the number of containers you are using. Use the

<code class="code">-X</code> switch to specify the correct HTTP method and the <code class="code">-D</code> to

dump the HTTP response headers to terminal output (stdout).</p>

<div class="example"><a id="d5e767"/><p class="title"><strong>Example 4.2. cURL Get Storage Space</strong></p><div class="example-contents">

<span class="command"><strong>curl</strong></span> <code class="option">–X HEAD</code> <code class="option">-D</code> - \

<code class="option">-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</code> \

<code class="uri">https://storage.swiftdrive.com/v1/CF_xer7_343</code>

</pre>

<code class="computeroutput">HTTP/1.1 204 No Content

Date: Thu, 09 Jul 2009 15:38:14 GMT

Server: Apache

X-Account-Container-Count: 22

X-Account-Bytes-Used: 9891628380

Content-Type: text/plain

100

</code></pre>

101

</div></div><br class="example-break"/>

102

<p>The HTTP request must include a header to specify the authentication token. The HTTP

103

headers in the response indicate the number of containers in this storage account and the

104

total bytes stored for the entire account.</p>

105

</div>

106

<div class="section" title="Creating a Storage Container"><div class="titlepage"><div><div><h3 class="title"><a id="d5e778"/>Creating a Storage Container</h3></div></div></div>

107

108

<p> Before uploading any data to OpenStack Object Storage, you must create a storage container. You do

109

this with a <span class="command"><strong>PUT</strong></span> request; cURL can be used for that, too.</p>

110

<div class="example"><a id="d5e782"/><p class="title"><strong>Example 4.3. cURL Create Storage Container</strong></p><div class="example-contents">

111

112

113

<span class="command"><strong>curl</strong></span> <code class="option">–X PUT</code> <code class="option">-D</code> - \

114

<code class="option">-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</code> \

115

<code class="uri">https://storage.swiftdrive.com/v1/CF_xer7_343/images</code>

116

</pre>

117

118

<code class="computeroutput">HTTP/1.1 201 Created

119

Date: Thu, 09 Jul 2009 17:03:36 GMT

120

Server: Apache

121

Content-Length: 0

122

Content-Type: text/plain

123

</code></pre>

124

</div></div><br class="example-break"/>

125

<p>Returning an HTTP status code of 201 (Created) indicates that the container was

126

successfully created.</p>

127

</div>

128

<div class="section" title="Uploading a Storage Object"><div class="titlepage"><div><div><h3 class="title"><a id="d5e793"/>Uploading a Storage Object</h3></div></div></div>

129

130

<p>After creating a container, you can upload a local file. For this example, let's

131

upload a screenshot image. The <code class="code">-T</code> switch specifies the full path to the local

132

file to upload. Please note that if you intend to distribute this object via the CDN you

133

MUST make sure that the object's <code class="code">Content-Type</code> is set correctly. This is the

134

mechanism by which a user's web browser knows how to display the file or launch a helper

135

application to view the file.</p>

136

<div class="example"><a id="d5e798"/><p class="title"><strong>Example 4.4. cURL Upload Storage Object</strong></p><div class="example-contents">

137

138

139

<span class="command"><strong>curl</strong></span> <code class="option">–X PUT</code> <code class="option">-T screenies/wow1.jpg</code><code class="option">-D</code> - \

140

<code class="option">-H "ETag: 805120ec285a7ed28f74024422fe3594"</code> \

141

<code class="option">-H "Content-Type: image/jpeg"</code> \

142

<code class="option">-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</code> \

143

<code class="option">-H "X-Object-Meta-Screenie: Mel visits Outland"</code> \

144

<code class="uri">https://storage.swiftdrive.com/v1/CF_xer7_343/images/wow1.jpg</code>

145

</pre>

146

147

<code class="computeroutput">HTTP/1.1 201 Created

148

Date: Thu, 09 Jul 2009 17:03:36 GMT

149

Server: Apache

150

Content-Length: 0

151

Etag: 805120ec285a7ed28f74024422fe3594

152

Content-Type: text/plain

153

</code></pre>

154

</div></div><br class="example-break"/>

155

</div>

156

<div class="section" title="CDN-Enabling the Container"><div class="titlepage"><div><div><h3 class="title"><a id="d5e812"/>CDN-Enabling the Container</h3></div></div></div>

157

158

<p>After creating a container and storing a file in it, you can choose to share the file.

159

Since the data in OpenStack Object Storage is all private, you can share your screenshot via the CDN.

160

To CDN-enable a container, issue a <span class="command"><strong>PUT</strong></span> request against the CDN management service. The

161

default TTL is 24 hours and supports a minimum of 1 hour (3600 seconds) and a maximum of 3

162

days (259200 seconds). Note that the target URL specifies the CDN system.</p>

163

<div class="example"><a id="d5e816"/><p class="title"><strong>Example 4.5. cURL CDN-Enable Container</strong></p><div class="example-contents">

164

165

166

<span class="command"><strong>curl</strong></span> <code class="option">–X PUT</code> <code class="option">-D</code> - \

167

<code class="option">-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</code> \

168

<code class="option">-H "X-TTL: 259200"</code> \

169

<code class="uri">https://cdn.swiftdrive.com/v1/CF_xer7_343/images</code>

170

</pre>

171

172

<code class="computeroutput">HTTP/1.1 202 Accepted

173

Date: Thu, 06 Aug 2009 01:34:13 GMT

174

Server: Apache

175

X-CDN-URI: http://c0010171.cdn.swiftfiles.swiftcloud.com

176

Content-Length: 0

177

Connection: close

178

Content-Type: text/plain; charset=UTF-8

179

</code></pre>

180

</div></div><br class="example-break"/>

181

<p>When the container is CDN-enabled, the service returns its public URI in the

182

<code class="code">X-CDN-URI</code> header of the response. Now you can combine this URI with the

183

object name to access the file via the CDN.</p>

184

<p>You can verify the CDN's cache settings that you specified with your TTL value by

185

sending a <span class="command"><strong>GET</strong></span> request to the object's CDN URL and viewing the response

186

headers. The TTL value you specify translates to the <code class="code">Expires</code> and

187

<code class="code">Cache-Control</code> headers of the CDN's cached Object.</p>

188

<p>The cURL command below issues a <span class="command"><strong>GET</strong></span> request which downloads the entire

189

file but writes it to <code class="code">/dev/null</code>, a data sink that won't actually save the

190

content to your local drive (This is only valid on UNIX-like systems).</p>

191

<div class="example"><a id="d5e836"/><p class="title"><strong>Example 4.6. cURL Download a File</strong></p><div class="example-contents">

192

193

194

<span class="command"><strong>curl</strong></span> <code class="option">–s</code> <code class="option">-D</code> - \

195

<code class="uri">http://c0010171.cdn.swiftfiles.swiftcloud.com/wow1.jpg</code> \

196

197

</pre>

198

199

<code class="computeroutput">HTTP/1.1 200 OK

200

Date: Thu, 06 Aug 2009 01:40:12 GMT

201

Server: Apache

202

Expires: Fri, 07 Aug 2009 01:40:12 GMT

203

Last-Modified: Thu, 09 Jul 2009 17:14:46 GMT

204

Cache-Control: max-age=86400, public

205

ETag: b20237bff6828976d2eb348e1ca8adae

206

Content-Length: 1255764

207

Content-Type: image/jpeg

208

Connection: keep-alive

209

</code></pre>

210

</div></div><br class="example-break"/>

211

</div>

212

<div class="section" title="Other cURL Commands"><div class="titlepage"><div><div><h3 class="title"><a id="d5e846"/>Other cURL Commands</h3></div></div></div>

213

214

<p>You can issue any of the ReST methods defined for OpenStack Object Storage with the cURL utility.

215

For example, you can use cURL to send <span class="command"><strong>POST</strong></span> and <span class="command"><strong>DELETE</strong></span> requests even though we haven't

216

provided specific examples.</p>

217

<p>It should be noted that generally each time <code class="code">curl</code> is invoked to perform an

218

operation, a separate TCP/IP and SSL connection is created and thrown away. The language

219

APIs. however. are designed to re-use these connections between operations and therefore

220

provide much better performance. It is recommended that you use one of the supported

221

language APIs in your production applications and limit <code class="code">curl</code> to

222

quick-and-easy testing/troubleshooting.</p>

223

</div>

224

</div><script type="text/javascript" src="../common/main.js"></script><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></div><div><div id="leftnavigation" style="padding-top:3px; background-color:white;"><div id="tabs"><ul><li><a href="#treeDiv"><span class="contentsTab">Contents</span></a></li><li><a href="#searchDiv"><span class="searchTab">Search</span></a></li></ul><div id="treeDiv"><img src="../common/images/loading.gif" alt="loading table of contents..." id="tocLoading" style="display:block;"/><div id="ulTreeDiv" style="display:none"><ul id="tree" class="filetree"><li><span class="file"><a href="ch01.html">Overview</a></span><ul><li><span class="file"><a href="ch01s01.html">Intended Audience</a></span></li><li><span class="file"><a href="ch01s02.html">Document Change History</a></span></li><li><span class="file"><a href="ch01s03.html">Additional Resources</a></span></li></ul></li><li><span class="file"><a href="ch02.html">General API Information</a></span><ul><li><span class="file"><a href="ch02s01.html">Authentication</a></span><ul><li><span class="file"><a href="ch02s01.html#d5e215">Request</a></span></li><li><span class="file"><a href="ch02s01.html#d5e230">Response</a></span></li></ul></li><li><span class="file"><a href="ch02s02.html">Overview of API Operations</a></span></li></ul></li><li><span class="file"><a href="ch03.html">API Operations for Storage Services</a></span><ul><li><span class="file"><a href="ch03s01.html">Storage Account Services</a></span><ul><li><span class="file"><a href="ch03s01.html#d5e301">List Containers</a></span><ul><li><span class="file"><a href="ch03s01.html#d5e344">Serialized List Output</a></span></li><li><span class="file"><a href="ch03s01.html#d5e363">List Large Number of Containers</a></span></li></ul></li><li><span class="file"><a href="ch03s01.html#d5e382">Retrieve Account Metadata</a></span></li></ul></li><li><span class="file"><a href="ch03s02.html">Storage Container Services</a></span><ul><li><span class="file"><a href="ch03s02.html#d5e401">List Objects</a></span><ul><li><span class="file"><a href="ch03s02.html#d5e469">Serialized List Output</a></span></li><li><span class="file"><a href="ch03s02.html#d5e489">List Large Number of Objects</a></span></li><li><span class="file"><a href="ch03s02.html#d5e508">Pseudo-Hierarchical Folders/Directories</a></span></li></ul></li><li><span class="file"><a href="ch03s02.html#d5e546">Create Container</a></span></li><li><span class="file"><a href="ch03s02.html#d5e559">Delete Container</a></span></li><li><span class="file"><a href="ch03s02.html#d5e574">Retrieve Container Metadata</a></span></li></ul></li><li><span class="file"><a href="ch03s03.html">Storage Object Services</a></span><ul><li><span class="file"><a href="ch03s03.html#d5e590">Retrieve Object</a></span></li><li><span class="file"><a href="ch03s03.html#d5e629">Create/Update Object</a></span><ul><li><span class="file"><a href="ch03s03.html#d5e649">Chunked Transfer Encoding</a></span></li></ul></li><li><span class="file"><a href="ch03s03.html#d5e658">Copy Object</a></span></li><li><span class="file"><a href="ch03s03.html#d5e666">Delete Object</a></span></li><li><span class="file"><a href="ch03s03.html#d5e682">Retrieve Object Metadata</a></span></li><li><span class="file"><a href="ch03s03.html#d5e694">Update Object Metadata</a></span></li></ul></li></ul></li><li><span class="file"><a href="ch04.html">Troubleshooting</a></span><ul><li id="webhelp-currentid"><span class="file"><a href="ch04s01.html">Using cURL</a></span><ul><li><span class="file"><a href="ch04s01.html#d5e741">Authentication</a></span></li><li><span class="file"><a href="ch04s01.html#d5e761">Determining Storage Usage</a></span></li><li><span class="file"><a href="ch04s01.html#d5e778">Creating a Storage Container</a></span></li><li><span class="file"><a href="ch04s01.html#d5e793">Uploading a Storage Object</a></span></li><li><span class="file"><a href="ch04s01.html#d5e812">CDN-Enabling the Container</a></span></li><li><span class="file"><a href="ch04s01.html#d5e846">Other cURL Commands</a></span></li></ul></li></ul></li></ul></div></div><div id="searchDiv"><div id="search"><form onsubmit="Verifie(ditaSearch_Form);return false" name="ditaSearch_Form" class="searchForm"><fieldset class="searchFieldSet"><legend>Search</legend><center><input id="textToSearch" name="textToSearch" type="text" class="searchText"/>   <input onclick="Verifie(ditaSearch_Form)" type="button" class="searchButton" value="Go" id="doSearch"/></center></fieldset></form></div><div id="searchResults"><center/></div><p class="searchHighlight"><a href="#" onclick="toggleHighlight()">Search Highlighter (On/Off)</a></p></div></div></div></div></body></html>

b'\\ No newline at end of file'

Older »