You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltacloud.apache.org by ma...@apache.org on 2012/08/09 11:54:46 UTC
git commit: Site Docs: adds cURL examples and deprecation notice for
deltacloudc
Updated Branches:
refs/heads/master 741ffcb93 -> 5b1548373
Site Docs: adds cURL examples and deprecation notice for deltacloudc
Project: http://git-wip-us.apache.org/repos/asf/deltacloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltacloud/commit/5b154837
Tree: http://git-wip-us.apache.org/repos/asf/deltacloud/tree/5b154837
Diff: http://git-wip-us.apache.org/repos/asf/deltacloud/diff/5b154837
Branch: refs/heads/master
Commit: 5b1548373e3db875aaaac74d8612dbf2a6a4838c
Parents: 741ffcb
Author: marios <ma...@redhat.com>
Authored: Wed Aug 8 19:35:30 2012 +0300
Committer: marios <ma...@redhat.com>
Committed: Thu Aug 9 12:53:55 2012 +0300
----------------------------------------------------------------------
site/content/command-tools.md | 16 ++-
site/content/curl-examples.md | 269 +++++++++++++++++++++++++
site/content/usage.md | 12 +-
site/output/command-tools.html | 13 ++-
site/output/curl-examples.html | 366 +++++++++++++++++++++++++++++++++++
site/output/usage.html | 9 +-
6 files changed, 677 insertions(+), 8 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltacloud/blob/5b154837/site/content/command-tools.md
----------------------------------------------------------------------
diff --git a/site/content/command-tools.md b/site/content/command-tools.md
index a56e548..18bc20e 100644
--- a/site/content/command-tools.md
+++ b/site/content/command-tools.md
@@ -5,6 +5,20 @@ title: Command Line Tools
<br/>
+
+<h3 id="command">deltacloudc is being deprecated</h3>
+
+The deltacloudc command line tool is being deprecated. For now the code making up deltacloudc has been moved to the /deltacloud/clients/console directory but will ultimately be removed from the repo. If the command line client is important to you then please <a href="/contact.html">let us know</a>. A new command line client may be put onto the roadmap if there is demand for one.
+
+The deltacloud core developers use (almost exclusively) <a href="http://curl.haxx.se/">cURL</a> as a command line client for working with a deltacloud server. You can find more information on working with cURL against deltacloud <a href="/curl-examples.html">here</a>.
+
+<hr/>
+<br/>
+<h1> /deprecated: </h1>
+<br/>
+<hr/>
+<br/>
+
<h3 id="command">Using Deltacloud command tool</h3>
<p>Installing the Deltacloud Ruby client also gives you the <strong>deltacloudc</strong> command line tool. This executable uses the Deltacloud client library to speak to the Deltacloud server through the <a href="/rest-api.html">REST API</a>. This means that you can control your cloud infrastructure from the command line. The general usage pattern for deltacloudc is:<p>
@@ -18,7 +32,7 @@ title: Command Line Tools
</dd>
<dt>Operation</dt>
<dd>
- is collection dependant. All collections respond to 'index' and 'show' operations (retrieve details on all objects in a given collection or on a specific object). Some collections respond to 'create' and 'destroy' operations. The collection of instances (realized virtual servers) responds to operations for managing the instance lifecycle, such as 'stop' or 'reboot'.
+ is collection dependant. All collections respond to 'index' and 'show' operations (retrieve details on all objects in a given collection or on a specific object). Some collections respond to 'create' and 'destroy' operations. The collection of instances (realized virtual servers) responds to operations for managing the instance lifecycle, such as 'stop' or 'reboot'.
</dd>
<dt>Options</dt>
<dd>
http://git-wip-us.apache.org/repos/asf/deltacloud/blob/5b154837/site/content/curl-examples.md
----------------------------------------------------------------------
diff --git a/site/content/curl-examples.md b/site/content/curl-examples.md
new file mode 100644
index 0000000..d3ddcbe
--- /dev/null
+++ b/site/content/curl-examples.md
@@ -0,0 +1,269 @@
+---
+site_name: Deltacloud API
+title: Working with cURL
+---
+
+<br/>
+
+<div class="row">
+
+ <div class="span8">
+
+ <h3 id="command">Working with cURL as a command line client</h3>
+
+ <p> The <a href="http://curl.haxx.se/docs/">cURL documentation</a> is pretty comprehensive, but the following are some general points to remember for using cURL against Deltacloud. All the examples on this page assume the deltacloud server is running at localhost:3001: </p>
+
+ <ul>
+ <li>
+ Credentials are specified with <strong> --user "name:password" </strong>
+ </li>
+ <li>
+ Request headers are specified with <strong> -H "header: value" </strong>. For the "Accept" header Deltacloud offers a convenient way of specifying the desired response format; you can include the <strong>"?format="</strong> parameter into the request URL rather than setting the Accept header
+ </li>
+ <li>
+ HTTP verbs are specified with <strong>-X VERB</strong>
+ </li>
+ <li>
+ The <strong> -i </strong> flag will show you the response headers and the <strong> -v </strong> flag will show you request and response headers as well as info about cURL activity:
+ <pre>
+curl -v -X DELETE --user "username:password" -H "Accept: application/xml" http://localhost:3001/api/keys/mykey
+ </pre>
+ </li>
+ </ul>
+
+ </div>
+
+ <div class="span4">
+
+ <ul class="nav nav-list well">
+ <li class="nav-header">cURL as a deltacloud client</li>
+ <li class="active"><a href="#instances">Work with instances</a></li>
+ <li><a href="#images">Work with images</a></li>
+ <li><a href="#hardware_profiles">Work with hardware profiles</a></li>
+ <li><a href="#realms">Work with realms</a></li>
+ <li><a href="#keys">Work with keys</a></li>
+ <li><a href="#firewalls">Work with firewalls</a></li>
+ <li><a href="#addresses">Work with addresses</a></li>
+ <li><a href="#load_balancers">Work with load balancers</a></li>
+ <li><a href="#buckets">Work with buckets</a></li>
+ <li><a href="#storage_volumes">Work with storage volumes</a></li>
+ <li><a href="#storage_snapshots">Work with storage snapshots</a></li>
+ </ul>
+
+ </div>
+</div>
+
+<hr/>
+
+<h4 id="instances">Working with instances</h4>
+
+<p>Display a complete list of instances in xml format:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/instances?format=xml </pre>
+
+Alternatively and if you prefer you can manually specify the Accept header:
+
+<pre> curl --user "user:pass" -H "Accept: application/xml" http://localhost:3001/api/instances</pre>
+
+<p>Launch an instance. Note that in this example parameters are specified as application/x-www-form-urlencoded through the use of the <strong> -d </strong> flag:</p>
+
+<pre> curl -X POST --user "user:pass" -d "image_id=ami-84db39ed&hwp_id=m1.small&keyname=marios_key" http://localhost:3001/api/instances?format=xml </pre>
+
+<p>Alternatively, you can use the -F flag to specify the parameters as multipart/form-data:</p>
+
+<pre> curl -X POST --user "user:pass" -F "image_id=ami-84db39ed" -F "hwp_id=m1.small" -F "keyname=marios_key" http://localhost:3001/api/instances?format=xml </pre>
+
+<p>Launch an instance action - reboot:</p>
+
+<pre> curl -X POST --user "user:pass" http://localhost:3001/api/instances/reboot?format=xml </pre>
+
+<p>Run command on an instance (where available):</p>
+
+<pre> curl -X POST --user "user:pass" -F "cmd=uname -a; ls -l" -F "private_key=`cat /location/of/ssh/keyfile`" http://localhost:3001/api/instances/i-d77cd0ac/run?format=xml </pre>
+
+<h4 id="images">Working with images</h4>
+
+<p>Get the details of a specific image:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/images/ami-3dc06a54?format=xml </pre>
+
+<p>Create an image from an existing instance (where available):</p>
+
+<pre>curl -X POST --user "user:pass" -d "instance_id=i-d77cd0ac&name=mariostestimage" http://localhost:3001/api/images?format=xml </pre>
+
+<p>Delete an image:</p>
+
+<pre>curl -X DELETE --user "user:pass" http://localhost:3001/api/images/ami-3dc06a54?format=xml </pre>
+
+<h4 id="hardware_profiles">Working with hardware profiles</h4>
+
+<p>Get a list of all hardware profiles:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/hardware_profiles?format=xml</pre>
+
+<p>Get the details of a specific hardware profile:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/hardware_profiles/m2.4xlarge?format=xml </pre>
+
+<h4 id="realms">Working with realms</h4>
+
+<p>Get a list of all realms:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/realms?format=xml</pre>
+
+<p>Get the details of a specific realm:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/realms/us-east-1a?format=xml </pre>
+
+<h4 id="realms">Working with keys</h4>
+
+<p>Get a list of all keys:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/keys?format=xml</pre>
+
+<p>Create a new key (where available):</p>
+
+<pre> curl -X POST --user "user:pass" -d "name=mynewkey" http://localhost:3001/api/keys?format=xml </pre>
+
+<p>Import an existing key (where available):</p>
+
+<pre> curl -X POST --user "user:pass" -F "name=mynewkey" -F "public_key=`cat /location/of/public/key/id_rsa.pub`" http://localhost:3001/api/keys?format=xml </pre>
+
+<p>Delete a key:</p>
+
+<pre> curl -X DELETE --user "user:pass" http://localhost:3001/api/keys/mynewkey?format=xml </pre>
+
+<h4 id="firewalls">Working with firewalls</h4>
+
+<p>Get a list of all firewalls:</p>
+
+<pre> curl -v --user "user:pass" http://localhost:3001/api/firewalls?format=xml </pre>
+
+<p>Create a new firewall:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "name=my_new_firewall&description=a test firewall" http://localhost:3001/api/firewalls?format=xml</pre>
+
+<p>Create a new firewall rule - port 22 tcp, with one source firewall (group) and 2 IP addresses:</p>
+
+<pre> curl -v -X POST --user "user:pass" -F "protocol=tcp" -F "port_from=22" -F "port_to=22" -F "group1=default" -F "group1owner=821108636519" -F "ip_address1=192.168.1.1/24" -F "ip_address2=65.128.31.27/32" http://localhost:3001/api/firewalls/my_new_firewall/rules</pre>
+
+<p>Delete a firewall rule: </p>
+
+<pre> curl -v -X DELETE --user "user:pass" http://localhost:3001/api/firewalls/marios_test_firewall/821108636519~tcp~22~22~@group,821108636519,default,@address,ipv4,192.168.1.1,24,@address,ipv4,65.128.31.27,32?format=xml </pre>
+
+<p>Delete a firewall:</p>
+
+<pre>curl -v -X DELETE --user "user:pass" http://localhost:3001/api/firewalls/marios_test_firewall?format=xml </pre>
+
+<h4 id="addresses">Working with addresses</h4>
+
+<p>Get a list of all addresses:</p>
+
+<pre> curl -v --user "user:pass" http://localhost:3001/api/addresses?format=xml </pre>
+
+<p>Create a new address:</p>
+
+<pre> curl -v --user "user:pass" -X POST http://localhost:3001/api/addresses?format=xml</pre>
+
+
+<p>Associate an address with an instance:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "instance_id=i-d77cd0ac" http://localhost:3001/api/addresses/23.23.176.127/associate?format=xml </pre>
+
+
+<p>Disassociate an address from an instance:</p>
+
+<pre>curl -v -X POST --user "user:pass" http://localhost:3001/api/addresses/23.23.176.127/disassociate?format=xml </pre>
+
+<p>Delete an address:</p>
+
+<pre>curl -v -X DELETE --user "user:pass" http://localhost:3001/api/addresses/23.23.176.127?format=xml </pre>
+
+<h4 id="load_balancers">Working with load balancers</h4>
+
+<p>Get a list of all load balancers:</p>
+
+<pre> curl -v --user "user:pass" http://localhost:3001/api/load_balancers?format=xml </pre>
+
+<p>Create a load balancer:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "name=webtraffic-balancer&realm_id=us-east-1c&listener_protocol=HTTP&
+listener_balancer_port=80&listener_instance_port=3001" http://localhost:3001/api/load_balancers?format=xml </pre>
+
+<p>Register an instance with a load balancer:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "instance_id=i-4f06b52e" http://localhost:3001/api/load_balancers/webtraffic-balancer/register?format=xml </pre>
+
+<p>Unregister an instance from a load balancer:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "instance_id=i-4f06b52e" http://localhost:3001/api/load_balancers/webtraffic-balancer/unregister?format=xml </pre>
+
+<p>Delete a load balancer:</p>
+
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/load_balancers/web-traffic-balancer</pre>
+
+<h4 id="buckets">Working with buckets</h4>
+
+<p>Get the details of a bucket:</p>
+
+<pre>curl -v --user "user:pass" http://localhost:3001/api/buckets/my_bucket?format=xml</pre>
+
+<p>Create a new bucket:</p>
+
+<pre>curl -v --user "user:pass" -X POST -d "name=shinynewbucket" http://localhost:3001/api/buckets?format=xml</pre>
+
+<p>Create a new blob, specifying a content-type and some metadata:</p>
+
+<pre>curl -v --user "user:pass" -H "content-type: image/jpg" -H 'X-Deltacloud-Blobmeta-Name:mariosblob' -H 'X-Deltacloud-Blobmeta-Author:me' --upload-file "/some/location/image.jpg" http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml </pre>
+
+<p> Note that the <strong>--upload-file</strong> parameter above causes cURL to issue a HTTP PUT </p>
+
+<p> Get blob metadata: </p>
+
+<pre> curl -v --user "user:pass" -X HEAD http://localhost:3001/api/buckets/shinynewbucket/newblob</pre>
+
+<p>Note that blob metadata is returned in the HTTP response headers. So the use of the <strong>-v</strong> flag is important here or you will not see the metadata.</p>
+
+<p>Update blob metadata:</p>
+
+<pre>curl -v --user "user:pass" -X POST -H 'X-Deltacloud-Blobmeta-Name:mariosblobV2' -H 'X-Deltacloud-Blobmeta-Version:v2.1.1' http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml</pre>
+
+<p>Delete a blob:</p>
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml</pre>
+
+<p>Delete a bucket:</p>
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/bucket/shinynewbucket</pre>
+
+
+<h4 id="storage_volumes">Working with storage volumes</h4>
+
+<p>Get a list of all storage volumes:</p>
+
+<pre>curl -v --user "user:pass" http://localhost:3001/api/storage_volumes?format=xml</pre>
+
+<p>Create a new storage volume:</p>
+
+<pre>curl -v --user "user:pass" -X POST -d "capacity=10&realm_id=us-east-1c" http://localhost:3001/api/storage_volumes?format=xml</pre>
+
+<p>Attach a volume to a running instance:</p>
+
+<pre>curl -v --user "user:pass" -X POST -d "instance_id=i-b100b3d0&device=/dev/sdi" http://localhost:3001/api/storage_volumes/vol-0bc0de60/attach?format=xml</pre>
+
+<p>Detach a volume (from whichever instance it is connected to):</p>
+
+<pre>curl -v --user "user:pass" -X POST http://localhost:3001/api/storage_volumes/vol-0bc0de60/detach?format=xml</pre>
+
+<p>Delete a storage volume:</p>
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/storage_volumes/vol-0bc0de60?format=xml</pre>
+
+<h4 id="storage_snapshots">Working with storage snapshots</h4>
+
+<p>Get details about a specific storage snapshot:</p>
+<pre>curl -v --user "user:pass" http://localhost:3001/api/storage_snapshots/snap-45b8d024?format=xml</pre>
+
+<p>Create a new storage snapshot:</p>
+<pre>curl -v --user "user:pass" -X POST -d "volume_id=vol-99fbe5f2" http://localhost:3001/api/storage_snapshots?format=xml</pre>
+
+<p>Delete a storage snapshot:</p>
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/storage_snapshots/snap-dda6cebc?format=xml</pre>
+
http://git-wip-us.apache.org/repos/asf/deltacloud/blob/5b154837/site/content/usage.md
----------------------------------------------------------------------
diff --git a/site/content/usage.md b/site/content/usage.md
index b63efc9..bf5d2cb 100644
--- a/site/content/usage.md
+++ b/site/content/usage.md
@@ -1,4 +1,4 @@
----
+---
site_name: Deltacloud API
title: Usage
---
@@ -10,7 +10,7 @@ title: Usage
Instead of dealing with HTTP interface you can use various clients to communicate with Deltacloud server.
<h3>The Deltacloud Ruby Client</h3>
-You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing:
+You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing:
<pre>$ sudo gem install deltacloud-client</pre>
@@ -129,6 +129,12 @@ http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml
The <strong>'-iv'</strong> flags will ensure that cURL displays the request and response headers (blob metadata are reported in the response headers with an empty response body).
</p>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="/curl-examples.html">Working with cURL</a>
+
+<br/>
+<br/>
+
<h3>Libdeltacloud Client (C library)</h3>
<p>
Libdeltacloud is a C/C++ library for accessing the Deltacloud API. It exports convenient structures and functions for manipulating cloud objects through the Deltacloud API.
@@ -144,7 +150,7 @@ As of version 0.9, libdeltacloud is mostly <strong>API stable</strong>, but not
</p>
<p>
-Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud.
+Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud.
</p>
<a class="btn btn-inverse btn-large" style="float: right" href="http://deltacloud.apache.org/libdeltacloud/index.html">Libdeltacloud documentation</a>
http://git-wip-us.apache.org/repos/asf/deltacloud/blob/5b154837/site/output/command-tools.html
----------------------------------------------------------------------
diff --git a/site/output/command-tools.html b/site/output/command-tools.html
index e6dd5ac..9589925 100644
--- a/site/output/command-tools.html
+++ b/site/output/command-tools.html
@@ -88,6 +88,17 @@
<p><br></p>
+<h3 id="command">deltacloudc is being deprecated</h3>
+
+<p>The deltacloudc command line tool is being deprecated. For now the code making up deltacloudc has been moved to the /deltacloud/clients/console directory but will ultimately be removed from the repo. If the command line client is important to you then please <a href="contact.html">let us know</a>. A new command line client may be put onto the roadmap if there is demand for one.</p>
+
+<p>The deltacloud core developers use (almost exclusively) <a href="http://curl.haxx.se/">cURL</a> as a command line client for working with a deltacloud server. You can find more information on working with cURL against deltacloud <a href="curl-examples.html">here</a>.</p>
+
+<hr><p><br></p>
+<h1> /deprecated: </h1>
+<p><br></p>
+<hr><p><br></p>
+
<h3 id="command">Using Deltacloud command tool</h3>
<p>Installing the Deltacloud Ruby client also gives you the <strong>deltacloudc</strong> command line tool. This executable uses the Deltacloud client library to speak to the Deltacloud server through the <a href="rest-api.html">REST API</a>. This means that you can control your cloud infrastructure from the command line. The general usage pattern for deltacloudc is:</p><p>
@@ -101,7 +112,7 @@
</dd>
<dt>Operation</dt>
<dd>
- is collection dependant. All collections respond to 'index' and 'show' operations (retrieve details on all objects in a given collection or on a specific object). Some collections respond to 'create' and 'destroy' operations. The collection of instances (realized virtual servers) responds to operations for managing the instance lifecycle, such as 'stop' or 'reboot'.
+ is collection dependant. All collections respond to 'index' and 'show' operations (retrieve details on all objects in a given collection or on a specific object). Some collections respond to 'create' and 'destroy' operations. The collection of instances (realized virtual servers) responds to operations for managing the instance lifecycle, such as 'stop' or 'reboot'.
</dd>
<dt>Options</dt>
<dd>
http://git-wip-us.apache.org/repos/asf/deltacloud/blob/5b154837/site/output/curl-examples.html
----------------------------------------------------------------------
diff --git a/site/output/curl-examples.html b/site/output/curl-examples.html
new file mode 100644
index 0000000..c0d2da6
--- /dev/null
+++ b/site/output/curl-examples.html
@@ -0,0 +1,366 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <title>Working with cURL</title>
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+ <!-- Le JavaScript -->
+ <script src="/assets/js/jquery-1.7.1.min.js" type="text/javascript"></script>
+ <script src="/assets/js/bootstrap-dropdown.js" type="text/javascript"></script>
+ <script src="/assets/js/jquery.tweet.js" type="text/javascript"></script>
+ <script src="/assets/js/application.js" type="text/javascript"></script>
+ <script src="/assets/js/bootstrap-transition.js"></script>
+ <script src="/assets/js/bootstrap-alert.js"></script>
+ <script src="/assets/js/bootstrap-modal.js"></script>
+ <script src="/assets/js/bootstrap-scrollspy.js"></script>
+ <script src="/assets/js/bootstrap-tab.js"></script>
+ <script src="/assets/js/bootstrap-tooltip.js"></script>
+ <script src="/assets/js/bootstrap-popover.js"></script>
+ <script src="/assets/js/bootstrap-button.js"></script>
+ <script src="/assets/js/bootstrap-collapse.js"></script>
+ <script src="/assets/js/bootstrap-carousel.js"></script>
+ <script src="/assets/js/bootstrap-typeahead.js"></script>
+
+ <!-- Le styles -->
+ <link href="/assets/css/bootstrap.css" rel="stylesheet">
+ <link href="/assets/css/application.css" rel="stylesheet">
+ <link rel="shortcut icon" href="/assets/img/favicon.ico">
+ </head>
+
+ <body>
+
+ <div class="navbar navbar-fixed-top">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/"><img src="/assets/img/logo.png" width="152"
+ alt="Deltacloud API"/></a>
+ <ul class="nav top-nav">
+ <li><a href="/">Home</a></li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">About<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="/about.html">What is Deltacloud?</a></li>
+ <li><a href="/supported-providers.html">Supported Providers</a></li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Installation<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="/install-deltacloud.html">Install Deltacloud</a></li>
+ <li><a href="/run-deltacloud-server.html">Run the Deltacloud Server</a></li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="/usage.html" class="dropdown-toggle" data-toggle="dropdown">Usage<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="/usage.html#usingapi">Using API</a></li>
+ <li><a href="/usage.html#clients">Client Libraries</a></li>
+ <li><a href="/command-tools.html">Command Line Tools</a></li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contribute<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="/getting-sources.html">Getting Sources</a></li>
+ <li><a href="/how-to-contribute.html">How Can I Contribute?</a></li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">API<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="/rest-api.html">REST API</a></li>
+ <li><a href="/drivers.html">Drivers API</a></li>
+ </ul>
+ </li>
+ <li><a href="/contact.html">Contact</a></li>
+</ul>
+
+ </div>
+ </div>
+
+ </div>
+
+ <div class="container content">
+
+ <p><br></p>
+
+<div class="row">
+
+ <div class="span8">
+
+ <h3 id="command">Working with cURL as a command line client</h3>
+
+ <p> The <a href="http://curl.haxx.se/docs/">cURL documentation</a> is pretty comprehensive, but the following are some general points to remember for using cURL against Deltacloud. All the examples on this page assume the deltacloud server is running at localhost:3001: </p>
+
+ <ul>
+<li>
+ Credentials are specified with <strong> --user "name:password" </strong>
+ </li>
+ <li>
+ Request headers are specified with <strong> -H "header: value" </strong>. For the "Accept" header Deltacloud offers a convenient way of specifying the desired response format; you can include the <strong>"?format="</strong> parameter into the request URL rather than setting the Accept header
+ </li>
+ <li>
+ HTTP verbs are specified with <strong>-X VERB</strong>
+ </li>
+ <li>
+ The <strong> -i </strong> flag will show you the response headers and the <strong> -v </strong> flag will show you request and response headers as well as info about cURL activity:
+ <pre>
+curl -v -X DELETE --user "username:password" -H "Accept: application/xml" http://localhost:3001/api/keys/mykey
+ </pre>
+ </li>
+ </ul>
+</div>
+
+ <div class="span4">
+
+ <ul class="nav nav-list well">
+<li class="nav-header">cURL as a deltacloud client</li>
+ <li class="active"><a href="#instances">Work with instances</a></li>
+ <li><a href="#images">Work with images</a></li>
+ <li><a href="#hardware_profiles">Work with hardware profiles</a></li>
+ <li><a href="#realms">Work with realms</a></li>
+ <li><a href="#keys">Work with keys</a></li>
+ <li><a href="#firewalls">Work with firewalls</a></li>
+ <li><a href="#addresses">Work with addresses</a></li>
+ <li><a href="#load_balancers">Work with load balancers</a></li>
+ <li><a href="#buckets">Work with buckets</a></li>
+ <li><a href="#storage_volumes">Work with storage volumes</a></li>
+ <li><a href="#storage_snapshots">Work with storage snapshots</a></li>
+ </ul>
+</div>
+</div>
+
+<hr><h4 id="instances">Working with instances</h4>
+
+<p>Display a complete list of instances in xml format:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/instances?format=xml </pre>
+
+<p>Alternatively and if you prefer you can manually specify the Accept header:</p>
+
+<pre> curl --user "user:pass" -H "Accept: application/xml" http://localhost:3001/api/instances</pre>
+
+<p>Launch an instance. Note that in this example parameters are specified as application/x-www-form-urlencoded through the use of the <strong> -d </strong> flag:</p>
+
+<pre> curl -X POST --user "user:pass" -d "image_id=ami-84db39ed&hwp_id=m1.small&keyname=marios_key" http://localhost:3001/api/instances?format=xml </pre>
+
+<p>Alternatively, you can use the -F flag to specify the parameters as multipart/form-data:</p>
+
+<pre> curl -X POST --user "user:pass" -F "image_id=ami-84db39ed" -F "hwp_id=m1.small" -F "keyname=marios_key" http://localhost:3001/api/instances?format=xml </pre>
+
+<p>Launch an instance action - reboot:</p>
+
+<pre> curl -X POST --user "user:pass" http://localhost:3001/api/instances/reboot?format=xml </pre>
+
+<p>Run command on an instance (where available):</p>
+
+<pre> curl -X POST --user "user:pass" -F "cmd=uname -a; ls -l" -F "private_key=`cat /location/of/ssh/keyfile`" http://localhost:3001/api/instances/i-d77cd0ac/run?format=xml </pre>
+
+<h4 id="images">Working with images</h4>
+
+<p>Get the details of a specific image:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/images/ami-3dc06a54?format=xml </pre>
+
+<p>Create an image from an existing instance (where available):</p>
+
+<pre>curl -X POST --user "user:pass" -d "instance_id=i-d77cd0ac&name=mariostestimage" http://localhost:3001/api/images?format=xml </pre>
+
+<p>Delete an image:</p>
+
+<pre>curl -X DELETE --user "user:pass" http://localhost:3001/api/images/ami-3dc06a54?format=xml </pre>
+
+<h4 id="hardware_profiles">Working with hardware profiles</h4>
+
+<p>Get a list of all hardware profiles:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/hardware_profiles?format=xml</pre>
+
+<p>Get the details of a specific hardware profile:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/hardware_profiles/m2.4xlarge?format=xml </pre>
+
+<h4 id="realms">Working with realms</h4>
+
+<p>Get a list of all realms:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/realms?format=xml</pre>
+
+<p>Get the details of a specific realm:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/realms/us-east-1a?format=xml </pre>
+
+<h4 id="realms">Working with keys</h4>
+
+<p>Get a list of all keys:</p>
+
+<pre> curl --user "user:pass" http://localhost:3001/api/keys?format=xml</pre>
+
+<p>Create a new key (where available):</p>
+
+<pre> curl -X POST --user "user:pass" -d "name=mynewkey" http://localhost:3001/api/keys?format=xml </pre>
+
+<p>Import an existing key (where available):</p>
+
+<pre> curl -X POST --user "user:pass" -F "name=mynewkey" -F "public_key=`cat /location/of/public/key/id_rsa.pub`" http://localhost:3001/api/keys?format=xml </pre>
+
+<p>Delete a key:</p>
+
+<pre> curl -X DELETE --user "user:pass" http://localhost:3001/api/keys/mynewkey?format=xml </pre>
+
+<h4 id="firewalls">Working with firewalls</h4>
+
+<p>Get a list of all firewalls:</p>
+
+<pre> curl -v --user "user:pass" http://localhost:3001/api/firewalls?format=xml </pre>
+
+<p>Create a new firewall:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "name=my_new_firewall&description=a test firewall" http://localhost:3001/api/firewalls?format=xml</pre>
+
+<p>Create a new firewall rule - port 22 tcp, with one source firewall (group) and 2 IP addresses:</p>
+
+<pre> curl -v -X POST --user "user:pass" -F "protocol=tcp" -F "port_from=22" -F "port_to=22" -F "group1=default" -F "group1owner=821108636519" -F "ip_address1=192.168.1.1/24" -F "ip_address2=65.128.31.27/32" http://localhost:3001/api/firewalls/my_new_firewall/rules</pre>
+
+<p>Delete a firewall rule: </p>
+
+<pre> curl -v -X DELETE --user "user:pass" http://localhost:3001/api/firewalls/marios_test_firewall/821108636519~tcp~22~22~@group,821108636519,default,@address,ipv4,192.168.1.1,24,@address,ipv4,65.128.31.27,32?format=xml </pre>
+
+<p>Delete a firewall:</p>
+
+<pre>curl -v -X DELETE --user "user:pass" http://localhost:3001/api/firewalls/marios_test_firewall?format=xml </pre>
+
+<h4 id="addresses">Working with addresses</h4>
+
+<p>Get a list of all addresses:</p>
+
+<pre> curl -v --user "user:pass" http://localhost:3001/api/addresses?format=xml </pre>
+
+<p>Create a new address:</p>
+
+<pre> curl -v --user "user:pass" -X POST http://localhost:3001/api/addresses?format=xml</pre>
+
+<p>Associate an address with an instance:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "instance_id=i-d77cd0ac" http://localhost:3001/api/addresses/23.23.176.127/associate?format=xml </pre>
+
+<p>Disassociate an address from an instance:</p>
+
+<pre>curl -v -X POST --user "user:pass" http://localhost:3001/api/addresses/23.23.176.127/disassociate?format=xml </pre>
+
+<p>Delete an address:</p>
+
+<pre>curl -v -X DELETE --user "user:pass" http://localhost:3001/api/addresses/23.23.176.127?format=xml </pre>
+
+<h4 id="load_balancers">Working with load balancers</h4>
+
+<p>Get a list of all load balancers:</p>
+
+<pre> curl -v --user "user:pass" http://localhost:3001/api/load_balancers?format=xml </pre>
+
+<p>Create a load balancer:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "name=webtraffic-balancer&realm_id=us-east-1c&listener_protocol=HTTP&
+listener_balancer_port=80&listener_instance_port=3001" http://localhost:3001/api/load_balancers?format=xml </pre>
+
+<p>Register an instance with a load balancer:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "instance_id=i-4f06b52e" http://localhost:3001/api/load_balancers/webtraffic-balancer/register?format=xml </pre>
+
+<p>Unregister an instance from a load balancer:</p>
+
+<pre> curl -v -X POST --user "user:pass" -d "instance_id=i-4f06b52e" http://localhost:3001/api/load_balancers/webtraffic-balancer/unregister?format=xml </pre>
+
+<p>Delete a load balancer:</p>
+
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/load_balancers/web-traffic-balancer</pre>
+
+<h4 id="buckets">Working with buckets</h4>
+
+<p>Get the details of a bucket:</p>
+
+<pre>curl -v --user "user:pass" http://localhost:3001/api/buckets/my_bucket?format=xml</pre>
+
+<p>Create a new bucket:</p>
+
+<pre>curl -v --user "user:pass" -X POST -d "name=shinynewbucket" http://localhost:3001/api/buckets?format=xml</pre>
+
+<p>Create a new blob, specifying a content-type and some metadata:</p>
+
+<pre>curl -v --user "user:pass" -H "content-type: image/jpg" -H 'X-Deltacloud-Blobmeta-Name:mariosblob' -H 'X-Deltacloud-Blobmeta-Author:me' --upload-file "/some/location/image.jpg" http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml </pre>
+
+<p> Note that the <strong>--upload-file</strong> parameter above causes cURL to issue a HTTP PUT </p>
+
+<p> Get blob metadata: </p>
+
+<pre> curl -v --user "user:pass" -X HEAD http://localhost:3001/api/buckets/shinynewbucket/newblob</pre>
+
+<p>Note that blob metadata is returned in the HTTP response headers. So the use of the <strong>-v</strong> flag is important here or you will not see the metadata.</p>
+
+<p>Update blob metadata:</p>
+
+<pre>curl -v --user "user:pass" -X POST -H 'X-Deltacloud-Blobmeta-Name:mariosblobV2' -H 'X-Deltacloud-Blobmeta-Version:v2.1.1' http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml</pre>
+
+<p>Delete a blob:</p>
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml</pre>
+
+<p>Delete a bucket:</p>
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/bucket/shinynewbucket</pre>
+
+<h4 id="storage_volumes">Working with storage volumes</h4>
+
+<p>Get a list of all storage volumes:</p>
+
+<pre>curl -v --user "user:pass" http://localhost:3001/api/storage_volumes?format=xml</pre>
+
+<p>Create a new storage volume:</p>
+
+<pre>curl -v --user "user:pass" -X POST -d "capacity=10&realm_id=us-east-1c" http://localhost:3001/api/storage_volumes?format=xml</pre>
+
+<p>Attach a volume to a running instance:</p>
+
+<pre>curl -v --user "user:pass" -X POST -d "instance_id=i-b100b3d0&device=/dev/sdi" http://localhost:3001/api/storage_volumes/vol-0bc0de60/attach?format=xml</pre>
+
+<p>Detach a volume (from whichever instance it is connected to):</p>
+
+<pre>curl -v --user "user:pass" -X POST http://localhost:3001/api/storage_volumes/vol-0bc0de60/detach?format=xml</pre>
+
+<p>Delete a storage volume:</p>
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/storage_volumes/vol-0bc0de60?format=xml</pre>
+
+<h4 id="storage_snapshots">Working with storage snapshots</h4>
+
+<p>Get details about a specific storage snapshot:</p>
+<pre>curl -v --user "user:pass" http://localhost:3001/api/storage_snapshots/snap-45b8d024?format=xml</pre>
+
+<p>Create a new storage snapshot:</p>
+<pre>curl -v --user "user:pass" -X POST -d "volume_id=vol-99fbe5f2" http://localhost:3001/api/storage_snapshots?format=xml</pre>
+
+<p>Delete a storage snapshot:</p>
+<pre>curl -v --user "user:pass" -X DELETE http://localhost:3001/api/storage_snapshots/snap-dda6cebc?format=xml</pre>
+
+ <footer class="footer">
+ <p class="pull-right"><span class='icon-circle-arrow-up'> </span><a href="#">Back to top</a></p>
+ <div class='row'>
+ <div class='span3'>
+ <img src="/assets/img/asf.png" alt="Apache Software Foundation"/>
+ </div>
+ <div class='span9'>
+ <strong>Apache Deltacloud</strong> is a top-level project at the <a
+ href="http://www.apache.org">Apache Software Foundation</a>,
+ having graduated from the ASF Incubator in October
+ 2011. Through a collaborative and meritocratic development process, Apache
+ projects deliver enterprise-grade, freely available software products that
+ attract large communities of users.
+ </div>
+ </div>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/deltacloud/blob/5b154837/site/output/usage.html
----------------------------------------------------------------------
diff --git a/site/output/usage.html b/site/output/usage.html
index 3d34f5f..abe58d5 100644
--- a/site/output/usage.html
+++ b/site/output/usage.html
@@ -94,7 +94,7 @@
<p>Instead of dealing with HTTP interface you can use various clients to communicate with Deltacloud server.</p>
<h3>The Deltacloud Ruby Client</h3>
-<p>You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing: </p>
+<p>You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing:</p>
<pre>$ sudo gem install deltacloud-client</pre>
@@ -210,7 +210,10 @@ http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml
The <strong>'-iv'</strong> flags will ensure that cURL displays the request and response headers (blob metadata are reported in the response headers with an empty response body).
</p>
-<h3>Libdeltacloud Client (C library)</h3>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="curl-examples.html">Working with cURL</a>
+
+<br><br><h3>Libdeltacloud Client (C library)</h3>
<p>
Libdeltacloud is a C/C++ library for accessing the Deltacloud API. It exports convenient structures and functions for manipulating cloud objects through the Deltacloud API.
</p>
@@ -225,7 +228,7 @@ As of version 0.9, libdeltacloud is mostly <strong>API stable</strong>, but not
</p>
<p>
-Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud.
+Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud.
</p>
<a class="btn btn-inverse btn-large" style="float: right" href="http://deltacloud.apache.org/libdeltacloud/index.html">Libdeltacloud documentation</a>