commit dad708b4e6653b6679817fe6f76cc41ef7472e94
Author: Antony Chazapis <chazapis@gmail.com>
Date:   Thu Apr 19 15:24:40 2012 +0300

    Add Pithos+ docs.

diff --git a/docs/dev-guide.rst b/docs/dev-guide.rst
index 3e44abf..5cee204 100644
--- a/docs/dev-guide.rst
+++ b/docs/dev-guide.rst
@@ -44,12 +44,12 @@ Images API body
 Storage API (Pithos+)
 =====================
 
-This is the Pithos+ File Storage API:
+This is the Pithos+ Object Storage API:
 
 .. toctree::
    :maxdepth: 2
 
-   File Storage API <pithos-api-guide>
+   Object Storage API <pithos-api-guide>
 
 Implementing new clients
 ========================
@@ -218,153 +218,3 @@ Notes:
  * Updating a state (either local or remote) implies downloading, uploading or
    deleting the appropriate file.
 
-Recommended Practices and Examples
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Assuming an authentication token is obtained, the following high-level
-operations are available - shown with ``curl``:
-
-* Get account information ::
-
-    curl -X HEAD -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user
-
-* List available containers ::
-
-    curl -X GET -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user
-
-* Get container information ::
-
-    curl -X HEAD -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user/pithos
-
-* Add a new container ::
-
-    curl -X PUT -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user/test
-
-* Delete a container ::
-
-    curl -X DELETE -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user/test
-
-* List objects in a container ::
-
-    curl -X GET -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user/pithos
-
-* List objects in a container (extended reply) ::
-
-    curl -X GET -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user/pithos?format=json
-
-  It is recommended that extended replies are cached and subsequent requests
-  utilize the ``If-Modified-Since`` header.
-
-* List metadata keys used by objects in a container
-
-  Will be in the ``X-Container-Object-Meta`` reply header, included in
-  container information or object list (``HEAD`` or ``GET``). (**TBD**)
-
-* List objects in a container having a specific meta defined ::
-
-    curl -X GET -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user/pithos?meta=favorites
-
-* Retrieve an object ::
-
-    curl -X GET -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user/pithos/README.txt
-
-* Retrieve an object (specific ranges of data) ::
-
-    curl -X GET -D - \
-         -H "X-Auth-Token: 0000" \
-         -H "Range: bytes=0-9" \
-         https://pithos.dev.grnet.gr/v1/user/pithos/README.txt
-
-  This will return the first 10 bytes. To get the first 10, bytes 30-39 and the
-  last 100 use ``Range: bytes=0-9,30-39,-100``.
-
-* Add a new object (folder type) (**TBD**) ::
-
-    curl -X PUT -D - \
-         -H "X-Auth-Token: 0000" \
-         -H "Content-Type: application/directory" \
-         https://pithos.dev.grnet.gr/v1/user/pithos/folder
-
-* Add a new object ::
-
-    curl -X PUT -D - \
-         -H "X-Auth-Token: 0000" \
-         -H "Content-Type: text/plain" \
-         -T EXAMPLE.txt
-         https://pithos.dev.grnet.gr/v1/user/pithos/folder/EXAMPLE.txt
-
-* Update an object ::
-
-    curl -X POST -D - \
-         -H "X-Auth-Token: 0000" \
-         -H "Content-Length: 10" \
-         -H "Content-Type: application/octet-stream" \
-         -H "Content-Range: bytes 10-19/*" \
-         -d "0123456789" \
-         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
-
-  This will update bytes 10-19 with the data specified.
-
-* Update an object (append) ::
-
-    curl -X POST -D - \
-         -H "X-Auth-Token: 0000" \
-         -H "Content-Length: 10" \
-         -H "Content-Type: application/octet-stream" \
-         -H "Content-Range: bytes */*" \
-         -d "0123456789" \
-         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
-
-* Update an object (truncate) ::
-
-    curl -X POST -D - \
-         -H "X-Auth-Token: 0000" \
-         -H "X-Source-Object: /folder/EXAMPLE.txt" \
-         -H "Content-Range: bytes 0-0/*" \
-         -H "X-Object-Bytes: 0" \
-         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
-
-  This will truncate the object to 0 bytes.
-
-* Add object metadata ::
-
-    curl -X POST -D - \
-         -H "X-Auth-Token: 0000" \
-         -H "X-Object-Meta-First: first_meta_value" \
-         -H "X-Object-Meta-Second: second_meta_value" \
-         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
-
-* Delete object metadata ::
-
-    curl -X POST -D - \
-         -H "X-Auth-Token: 0000" \
-         -H "X-Object-Meta-First: first_meta_value" \
-         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
-
-  Metadata can only be "set". To delete ``X-Object-Meta-Second``, reset all
-  metadata.
-
-* Delete an object ::
-
-    curl -X DELETE -D - \
-         -H "X-Auth-Token: 0000" \
-         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
-
diff --git a/docs/images/pithos-backend-nodes.png b/docs/images/pithos-backend-nodes.png
new file mode 100644
index 0000000..103c36e
Binary files /dev/null and b/docs/images/pithos-backend-nodes.png differ
diff --git a/docs/images/pithos-backend-versions.png b/docs/images/pithos-backend-versions.png
new file mode 100644
index 0000000..e57cfcf
Binary files /dev/null and b/docs/images/pithos-backend-versions.png differ
diff --git a/docs/images/pithos-layers.png b/docs/images/pithos-layers.png
new file mode 100644
index 0000000..b76d264
Binary files /dev/null and b/docs/images/pithos-layers.png differ
diff --git a/docs/index.rst b/docs/index.rst
index d112c9b..087baf5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,7 +14,7 @@ synnefo is opensource software, used to create massively scalable IaaS clouds.
    :maxdepth: 1
 
    Identity Management (codename: astakos) <astakos>
-   File Storage Service (codename: pithos+) <pithos>
+   Object Storage Service (codename: pithos+) <pithos>
    Compute/Network Service (codename: cyclades) <cyclades>
    Image Registry (codename: plankton) <plankton>
    Billing Service (codename: aquarium) <http://docs.dev.grnet.gr/aquarium/latest/index.html>
diff --git a/docs/pithos-api-guide.rst b/docs/pithos-api-guide.rst
index 623962e..6b94ed6 100644
--- a/docs/pithos-api-guide.rst
+++ b/docs/pithos-api-guide.rst
@@ -1,37 +1,25 @@
 Pithos+ API
 ===========
 
-This is the Pithos+ API guide.
+Introduction
+------------
 
+Pithos is a storage service implemented by GRNET (http://www.grnet.gr). Data is stored as objects, organized in containers, belonging to an account. This hierarchy of storage layers has been inspired by the OpenStack Object Storage (OOS) API and similar CloudFiles API by Rackspace. The Pithos API follows the OOS API as closely as possible. One of the design requirements has been to be able to use Pithos with clients built for the OOS, without changes.
 
-Overview
---------
+However, to be able to take full advantage of the Pithos infrastructure, client software should be aware of the extensions that differentiate Pithos from OOS. Pithos objects can be updated, or appended to. Pithos will store sharing permissions per object and enforce corresponding authorization policies. Automatic version management, allows taking account and container listings back in time, as well as reading previous instances of objects.
 
-Pithos+ data is stored as objects, organized in containers, belonging to an
-account. This hierarchy of storage layers has been inspired by the OpenStack
-Object Storage (OOS) API and similar CloudFiles API by Rackspace. The Pithos
-API follows the OOS API as closely as possible. One of the design requirements
-has been to be able to use Pithos with clients built for the OOS, without
-changes.
-
-However, to be able to take full advantage of the Pithos infrastructure, client
-software should be aware of the extensions that differentiate Pithos from OOS.
+The storage backend of Pithos is block oriented, permitting efficient, deduplicated data placement. The block structure of objects is exposed at the API layer, in order to encourage external software to implement advanced data management operations.
 
 This document's goals are:
 
- * Define the Pithos ReST API that allows the storage and retrieval of data and
-   metadata via HTTP calls
- * Specify metadata semantics and user interface guidelines for a common
-   experience across client software implementations
+* Define the Pithos ReST API that allows the storage and retrieval of data and metadata via HTTP calls
+* Specify metadata semantics and user interface guidelines for a common experience across client software implementations
+
+The present document is meant to be read alongside the OOS API documentation. Thus, it is suggested that the reader is familiar with associated technologies, the OOS API as well as the first version of the Pithos API. This document refers to the second version of Pithos. Information on the first version of the storage API can be found at http://code.google.com/p/gss.
 
-The present document is meant to be read alongside the OOS API documentation.
-Thus, it is suggested that the reader is familiar with associated technologies,
-the OOS API as well as the first version of the Pithos API. This document
-refers to the version of Pithos+. Information on the first version of the
-storage API can be found at http://code.google.com/p/gss.
+Whatever marked as to be determined (**TBD**), should not be considered by implementors.
 
-Whatever marked as to be determined (**TBD**), should not be considered by
-implementors.
+More info about Pithos can be found here: https://code.grnet.gr/projects/pithos
 
 Document Revisions
 ^^^^^^^^^^^^^^^^^^
@@ -93,24 +81,14 @@ Revision                   Description
 0.1 (May 17, 2011)         Initial release. Based on OpenStack Object Storage Developer Guide API v1 (Apr. 15, 2011).
 =========================  ================================
 
-Users and Authentication
-------------------------
+Pithos Users and Authentication
+-------------------------------
 
-In Pithos+, each user is uniquely identified by a token. All API requests
-require a token and each token is internally resolved to an account string. The
-API uses the account string to identify the user's own files, thus whether a
-request is local or cross-account.
+In Pithos, each user is uniquely identified by a token. All API requests require a token and each token is internally resolved to an account string. The API uses the account string to identify the user's own files, thus whether a request is local or cross-account.
 
-Pithos+ does not keep a user database. For development and testing purposes,
-user identifiers and their corresponding tokens can be defined in the settings
-file. However, Pithos is designed with an external authentication service in
-mind. This service must handle the details of validating user credentials and
-communicate with Pithos via a middleware software component that, given a
-token, fills in the internal request account variable.
+Pithos does not keep a user database. For development and testing purposes, user identifiers and their corresponding tokens can be defined in the settings file. However, Pithos is designed with an external authentication service in mind. This service must handle the details of validating user credentials and communicate with Pithos via a middleware software component that, given a token, fills in the internal request account variable.
 
-Client software using Pithos+, if not already knowing a user's identifier and
-token, should forward to the ``/login`` URI. The Pithos server, depending on
-its configuration will redirect to the appropriate login page.
+Client software using Pithos, if not already knowing a user's identifier and token, should forward to the ``/login`` URI. The Pithos server, depending on its configuration will redirect to the appropriate login page.
 
 The login URI accepts the following parameters:
 
@@ -126,10 +104,10 @@ When done with logging in, the service's login URI should redirect to the URI pr
 
 A user management service that implements a login URI according to these conventions is Astakos (https://code.grnet.gr/projects/astakos), by GRNET.
 
-API Operations
+The Pithos API
 --------------
 
-The URI requests supported by the Pithos+ API follow one of the following forms:
+The URI requests supported by the Pithos API follow one of the following forms:
 
 * Top level: ``https://hostname/v1/``
 * Account level: ``https://hostname/v1/<account>``
@@ -1120,3 +1098,148 @@ Clarifications/suggestions:
 * The ``Last-Modified`` header value always reflects the actual latest change timestamp, regardless of time control parameters and version requests. Time precondition checks with ``If-Modified-Since`` and ``If-Unmodified-Since`` headers are applied to this value.
 * A copy/move using ``PUT``/``COPY``/``MOVE`` will always update metadata, keeping all old values except the ones redefined in the request headers.
 * A ``HEAD`` or ``GET`` for an ``X-Object-Manifest`` object, will include modified ``Content-Length`` and ``ETag`` headers, according to the characteristics of the objects under the specified prefix. The ``Etag`` will be the MD5 hash of the corresponding ETags concatenated. In extended container listings there is no metadata processing.
+
+Recommended Practices and Examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assuming an authentication token is obtained, the following high-level operations are available - shown with ``curl``:
+
+* Get account information ::
+
+    curl -X HEAD -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user
+
+* List available containers ::
+
+    curl -X GET -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user
+
+* Get container information ::
+
+    curl -X HEAD -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user/pithos
+
+* Add a new container ::
+
+    curl -X PUT -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user/test
+
+* Delete a container ::
+
+    curl -X DELETE -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user/test
+
+* List objects in a container ::
+
+    curl -X GET -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user/pithos
+
+* List objects in a container (extended reply) ::
+
+    curl -X GET -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user/pithos?format=json
+
+  It is recommended that extended replies are cached and subsequent requests utilize the ``If-Modified-Since`` header.
+
+* List metadata keys used by objects in a container
+
+  Will be in the ``X-Container-Object-Meta`` reply header, included in container information or object list (``HEAD`` or ``GET``). (**TBD**)
+
+* List objects in a container having a specific meta defined ::
+
+    curl -X GET -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user/pithos?meta=favorites
+
+* Retrieve an object ::
+
+    curl -X GET -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user/pithos/README.txt
+
+* Retrieve an object (specific ranges of data) ::
+
+    curl -X GET -D - \
+         -H "X-Auth-Token: 0000" \
+         -H "Range: bytes=0-9" \
+         https://pithos.dev.grnet.gr/v1/user/pithos/README.txt
+
+  This will return the first 10 bytes. To get the first 10, bytes 30-39 and the last 100 use ``Range: bytes=0-9,30-39,-100``.
+
+* Add a new object (folder type) (**TBD**) ::
+
+    curl -X PUT -D - \
+         -H "X-Auth-Token: 0000" \
+         -H "Content-Type: application/directory" \
+         https://pithos.dev.grnet.gr/v1/user/pithos/folder
+
+* Add a new object ::
+
+    curl -X PUT -D - \
+         -H "X-Auth-Token: 0000" \
+         -H "Content-Type: text/plain" \
+         -T EXAMPLE.txt
+         https://pithos.dev.grnet.gr/v1/user/pithos/folder/EXAMPLE.txt
+
+* Update an object ::
+
+    curl -X POST -D - \
+         -H "X-Auth-Token: 0000" \
+         -H "Content-Length: 10" \
+         -H "Content-Type: application/octet-stream" \
+         -H "Content-Range: bytes 10-19/*" \
+         -d "0123456789" \
+         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+  This will update bytes 10-19 with the data specified.
+
+* Update an object (append) ::
+
+    curl -X POST -D - \
+         -H "X-Auth-Token: 0000" \
+         -H "Content-Length: 10" \
+         -H "Content-Type: application/octet-stream" \
+         -H "Content-Range: bytes */*" \
+         -d "0123456789" \
+         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+* Update an object (truncate) ::
+
+    curl -X POST -D - \
+         -H "X-Auth-Token: 0000" \
+         -H "X-Source-Object: /folder/EXAMPLE.txt" \
+         -H "Content-Range: bytes 0-0/*" \
+         -H "X-Object-Bytes: 0" \
+         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+  This will truncate the object to 0 bytes.
+
+* Add object metadata ::
+
+    curl -X POST -D - \
+         -H "X-Auth-Token: 0000" \
+         -H "X-Object-Meta-First: first_meta_value" \
+         -H "X-Object-Meta-Second: second_meta_value" \
+         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+* Delete object metadata ::
+
+    curl -X POST -D - \
+         -H "X-Auth-Token: 0000" \
+         -H "X-Object-Meta-First: first_meta_value" \
+         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+  Metadata can only be "set". To delete ``X-Object-Meta-Second``, reset all metadata.
+
+* Delete an object ::
+
+    curl -X DELETE -D - \
+         -H "X-Auth-Token: 0000" \
+         https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
diff --git a/docs/pithos-plus.pdf b/docs/pithos-plus.pdf
new file mode 100644
index 0000000..84e4929
Binary files /dev/null and b/docs/pithos-plus.pdf differ
diff --git a/docs/pithos.rst b/docs/pithos.rst
index 9fd9f31..2d0a4ab 100644
--- a/docs/pithos.rst
+++ b/docs/pithos.rst
@@ -1,71 +1,367 @@
-.. _pithos:
+Object Storage Service (Pithos+)
+================================
 
-File Storage Service (pithos+)
+Pithos+ is an online storage service based on the OpenStack Object
+Storage API with several important extensions. It uses a
+block-based mechanism to allow users to upload, download, and share
+files, keep different versions of a file, and attach policies to them.
+It follows a layered, modular implementation. Pithos+ was designed to
+be used as a storage service by the total set of the Greek research
+and academic community (counting tens of thousands of users) but is
+free and open to use by anybody, under a BSD-2 clause license.
+
+A presentation of Pithos+ features and architecture is :download:`here <pithos-plus.pdf>`.
+
+Introduction
+------------
+
+In 2008 the Greek Research and Technology Network (GRNET) decided
+to offer an online storage service to the Greek research and academic
+community. The service, called Pithos, was implemented in 2008-2009,
+and was made available in spring 2009. It now has more than
+12,000 users.
+
+In 2011 GRNET decided to offer a new, evolved online storage
+service, to be called Pithos+. Pithos+ is designed to address the
+main requirements expressed by the Pithos users in the first two years of
+operation:
+
+* Provide both a web-based client and native desktop clients for
+  the most common operating systems.
+* Allow not only uploading, downloading, and sharing, but also
+  synchronization capabilities so that uses are able to select folders
+  and have then synchronized automatically with their online accounts.
+* Allow uploading of large files, regardless of browser
+  capabilities (depending on the version,  browsers may place a 2
+  GBytes upload limit).
+* Improve upload speed; not an issue as long as the user is on a
+  computer connected to the GRNET backbone, but it becomes important
+  over ADSL connections.
+* Allow access by
+  non-Shibboleth (http://shibboleth.internet2.edu/).
+  accounts. Pithos delegates user authentication to the Greek
+  Shibboleth federation, in which all research and academic
+  institutions belong. However, it is desirable to have the option to
+  open up Pithos to non-Shibboleth authenticated users as well.
+* Use open standards as far as possible.   
+
+In what follows we describe the main features of Pithos+, the elements
+of its design and the capabilities it affords. We touch on related
+work and we provide some discussion on our experiences and thoughts on
+the future.
+
+Pithos+ Features
+----------------
+
+Pithos+ is based on the OpenStack Object Storage API (Pithos
+used a home-grown API). We decided to adopt an open standard
+API in order to leverage existing clients that implement the
+API. In this way, a user can access Pithos+ with a standard
+OpenStack client - although users will want to use a Pithos+ client to
+use features going beyond those offered by the OpenStack API.
+The strategy paid off during Pithos+ development itself, as we were
+able to access and test the service with existing clients, while also
+developing new clients based on open source OpenStack clients.
+
+The major extensions on the OpenStack API are:
+
+* The use of block-based storage in lieu of an object-based one.
+  OpenStack stores objects, which may be files, but this is not
+  necessary - large files (longer than 5GBytes), for instance, must be
+  stored as a series of distinct objects accompanied by a manifest.
+  Pithos+ stores blocks, so objects can be of unlimited size.
+* Permissions on individual files and folders. Note that folders
+  do not exist in the OpenStack API, but are simulated by
+  appropriate conventions, an approach we have kept in Pithos+ to
+  avoid incompatibility.
+* Fully-versioned objects.
+* Metadata-based queries. Users are free to set metadata on their
+  objects, and they can list objects meeting metadata criteria.
+* Policies, such as whether to enable object versioning and to
+  enforce quotas. This is particularly important for sharing object
+  containers, since the user may want to avoid running out of space
+  because of collaborators writing in the shared storage.
+* Partial upload and download based on HTTP request
+  headers and parameters.
+* Object updates, where data may even come from other objects
+  already stored in Pithos+. This allows users to compose objects from
+  other objects without uploading data.
+* All objects are assigned UUIDs on creation, which can be
+  used to reference them regardless of their path location.
+
+Pithos+ Design
+--------------
+
+Pithos+ is built on a layered architecture (see Figure).
+The Pithos+ server speaks HTTP with the outside world. The HTTP
+operations implement an extended OpenStack Object Storage API.
+The back end is a library meant to be used by internal code and
+other front ends. For instance, the back end library, apart from being
+used in Pithos+ for implementing the OpenStack Object Storage API,
+is also used in our implementation of the OpenStack Image
+Service API. Moreover, the back end library allows specification
+of different namespaces for metadata, so that the same object can be
+viewed by different front end APIs with different sets of
+metadata. Hence the same object can be viewed as a file in Pithos+,
+with one set of metadata, or as an image with a different set of
+metadata, in our implementation of the OpenStack Image Service.
+
+The data component provides storage of block and the information
+needed to retrieve them, while the metadata component is a database of
+nodes and permissions. At the current implementation, data is saved to
+the filesystem and metadata in an SQL database. In the future,
+data will be saved to some distributed block storage (we are currently
+evaluating RADOS - http://ceph.newdream.net/category/rados), and metadata to a NoSQL database.
+
+.. image:: images/pithos-layers.png
+
+Block-based Storage for the Client
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since an object is saved as a set of blocks in Pithos+, object
+operations are no longer required to refer to the whole object. We can
+handle parts of objects as needed when uploading, downloading, or
+copying and moving data.
+
+In particular, a client, provided it has access permissions, can
+download data from Pithos+ by issuing a ``GET`` request on an
+object. If the request includes the ``hashmap`` parameter, then the
+request refers to a hashmap, that is, a set containing the
+object's block hashes. The reply is of the form::
+
+    {"block_hash": "sha1", 
+     "hashes": ["7295c41da03d7f916440b98e32c4a2a39351546c", ...],
+     "block_size":131072,
+     "bytes": 242}
+
+The client can then compare the hashmap with the hashmap computed from
+the local file. Any missing parts can be downloaded with ``GET``
+requests with an additional ``Range`` header containing the hashes
+of the blocks to be retrieved. The integrity of the file can be
+checked against the ``X-Object-Hash`` header, returned by the
+server and containing the root Merkle hash of the object's
+hashmap.
+
+When uploading a file to Pithos+, only the missing blocks will be
+submitted to the server, with the following algorithm:
+
+* Calculate the hash value for each block of the object to be
+  uploaded.
+* Send a hashmap ``PUT`` request for the object. This is a
+  ``PUT`` request with a ``hashmap`` request parameter appended
+  to it. If the parameter is not present, the object's data (or part
+  of it) is provided with the request. If the parameter is present,
+  the object hashmap is provided with the request.
+* If the server responds with status 201 (Created), the blocks are
+  already on the server and we do not need to do anything more.
+* If the server responds with status 409 (Conflict), the server’s
+  response body contains the hashes of the blocks that do not exist on
+  the server. Then, for each hash value in the server’s response (or all
+  hashes together) send a ``POST`` request to the server with the
+  block's data.
+
+In effect, we are deduplicating data based on their block hashes,
+transparently to the users. This results to perceived instantaneous
+uploads when material is already present in Pithos+ storage.
+
+Block-based Storage Processing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Pithos+ is the synnefo File Storage Service and implements the OpenStack Object
-Storage API + synnefo extensions.
+Hashmaps themselves are saved in blocks. All blocks are persisted to
+storage using content-based addressing. It follows that to read a
+file, Pithos+ performs the following operations:
 
+* The client issues a request to get a file, via HTTP ``GET``.
+* The API front end asks from the back end the metadata
+  of the object.
+* The back end checks the permissions of the object and, if they
+  allow access to it, returns the object's metadata.
+* The front end evaluates any HTTP headers (such as
+  ``If-Modified-Since``, ``If-Match``, etc.).
+* If the preconditions are met, the API front end requests
+  from the back end the object's hashmap (hashmaps are indexed by the
+  full path).
+* The back end will read and return to the API front end the
+  object's hashmap from the underlying storage.
+* Depending on the HTTP ``Range`` header, the 
+  API front end asks from the back end the required blocks, giving
+  their corresponding hashes.
+* The back end fetches the blocks from the underlying storage,
+  passes them to the API front end, which returns them to the client.
 
-Introduction
-============
-
-Pithos is a storage service implemented by GRNET (http://www.grnet.gr). Data is
-stored as objects, organized in containers, belonging to an account. This
-hierarchy of storage layers has been inspired by the OpenStack Object Storage
-(OOS) API and similar CloudFiles API by Rackspace. The Pithos API follows the
-OOS API as closely as possible. One of the design requirements has been to be
-able to use Pithos with clients built for the OOS, without changes.
-
-However, to be able to take full advantage of the Pithos infrastructure, client
-software should be aware of the extensions that differentiate Pithos from OOS.
-Pithos objects can be updated, or appended to. Pithos will store sharing
-permissions per object and enforce corresponding authorization policies.
-Automatic version management, allows taking account and container listings back
-in time, as well as reading previous instances of objects.
-
-The storage backend of Pithos is block oriented, permitting efficient,
-deduplicated data placement. The block structure of objects is exposed at the
-API layer, in order to encourage external software to implement advanced data
-management operations.
-
-
-Pithos Users and Authentication
-===============================
-
-In Pithos, each user is uniquely identified by a token. All API requests
-require a token and each token is internally resolved to an account string. The
-API uses the account string to identify the user's own files, thus whether a
-request is local or cross-account.
-
-Pithos does not keep a user database. For development and testing purposes,
-user identifiers and their corresponding tokens can be defined in the settings
-file. However, Pithos is designed with an external authentication service in
-mind. This service must handle the details of validating user credentials and
-communicate with Pithos via a middleware software component that, given a
-token, fills in the internal request account variable.
-
-Client software using Pithos, if not already knowing a user's identifier and
-token, should forward to the ``/login`` URI. The Pithos server, depending on
-its configuration will redirect to the appropriate login page.
-
-The login URI accepts the following parameters:
-
-======================  =========================
-Request Parameter Name  Value
-======================  =========================
-next                    The URI to redirect to when the process is finished
-renew                   Force token renewal (no value parameter)
-force                   Force logout current user (no value parameter)
-======================  =========================
-
-When done with logging in, the service's login URI should redirect to the URI
-provided with ``next``, adding ``user`` and ``token`` parameters, which contain
-the account and token fields respectively.
-
-A user management service that implements a login URI according to these
-conventions is Astakos.
-
-
-Pithos+ Architecture
-====================
+Saving data from the client to the server is done in several different
+ways.
+
+First, a regular HTTP ``PUT`` is the reverse of the HTTP ``GET``.
+The client sends the full object to the API front end.
+The API front end splits the object to blocks. It sends each
+block to the back end, which calculates its hash and saves it to
+storage. When the hashmap is complete, the API front end commands
+the back end to create a new object with the created hashmap and any
+associated metadata.
+
+Secondly, the client may send to the API front end a hashmap and
+any associated metadata, with a special formatted HTTP ``PUT``,
+using an appropriate URL parameter. In this case, if the
+back end can find the requested blocks, the object will be created as
+previously, otherwise it will report back the list of missing blocks,
+which will be passed back to the client. The client then may send the
+missing blocks by issuing an HTTP ``POST`` and then retry the
+HTTP ``PUT`` for the hashmap. This allows for very fast uploads,
+since it may happen that no real data uploading takes place, if the
+blocks are already in data storage.
+
+Copying objects does not involve data copying, but is performed by
+associating the object's hashmap with the new path. Moving objects, as
+in OpenStack, is a copy followed by a delete, again with no real data
+being moved.
+
+Updates to an existing object, which are not offered by OpenStack, are
+implemented by issuing an HTTP ``POST`` request including the
+offset and the length of the data. The API front end requests
+from the back end the hashmap of the existing object. Depending on the
+offset of the update (whether it falls within block boundaries or not)
+the front end will ask the back end to update or create new blocks. At
+the end, the front end will save the updated hashmap. It is also
+possible to pass a parameter to HTTP ``POST`` to specify that the
+data will come from another object, instead of being uploaded by the
+client. 
+
+Pithos+ Back End Nodes
+^^^^^^^^^^^^^^^^^^^^^^
+
+Pithos+ organizes entities in a tree hierarchy, with one tree node per
+path entry (see Figure). Nodes can be accounts,
+containers, and objects. A user may have multiple
+accounts, each account may have multiple containers, and each
+container may have multiple objects. An object may have multiple
+versions, and each version of an object has properties (a set of fixed
+metadata, like size and mtime) and arbitrary metadata.
+
+.. image:: images/pithos-backend-nodes.png
+
+The tree hierarchy has up to three levels, since, following the
+OpenStack API, everything is stored as an object in a container.
+The notion of folders or directories is through conventions that
+simulate pseudo-hierarchical folders. In particular, object names that
+contain the forward slash character and have an accompanying marker
+object with a ``Content-Type: application/directory`` as part of
+their metadata can be treated as directories by Pithos+ clients. Each
+node corresponds to a unique path, and we keep its parent in the
+account/container/object hierarchy (that is, all objects have a
+container as their parent).
+
+Pithos+ Back End Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For each object version we keep the root Merkle hash of the object it
+refers to, the size of the object, the last modification time and the
+user that modified the file, and its cluster. A version belongs
+to one of the following three clusters (see Figure):
+
+  * normal, which are the current versions
+  * history, which contain the previous versions of an object
+  * deleted, which contain objects that have been deleted
+
+.. image:: images/pithos-backend-versions.png
+
+This versioning allows Pithos+ to offer to its user time-based
+contents listing of their accounts. In effect, this also allows them
+to take their containers back in time. This is implemented
+conceptually by taking a vertical line in the Figure and
+presenting to the user the state on the left side of the line.
+
+Pithos+ Back End Permissions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pithos+ recognizes read and write permissions, which can be granted to
+individual users or groups of users. Groups as collections of users
+created at the account level by users themselves, and are flat - a
+group cannot contain or reference another group. Ownership of a file
+cannot be delegated.
+
+Pithos+ also recognizes a "public" permission, which means that the
+object is readable by all. When an object is made public, it is
+assigned a URL that can be used to access the object from
+outside Pithos+ even by non-Pithos+ users. 
+
+Permissions can be assigned to objects, which may be actual files, or
+directories. When listing objects, the back end uses the permissions as
+filters for what to display, so that users will see only objects to
+which they have access. Depending on the type of the object, the
+filter may be exact (plain object), or a prefix (like ``path/*`` for
+a directory). When accessing objects, the same rules are used to
+decide whether to allow the user to read or modify the object or
+directory. If no permissions apply to a specific object, the back end
+searches for permissions on the closest directory sharing a common
+prefix with the object.
+
+Related Work
+------------
+
+Commercial cloud providers have been offering online storage for quite
+some time, but the code is not published and we do not know the
+details of their implementation. Rackspace has used the OpenStack
+Object Storage in its Cloud Files product. Swift is an open source
+implementation of the OpenStack Object Storage API. As we have
+pointed out, our implementation maintains compatibility with
+OpenStack, while offering additional capabilities.
+
+Discussion
+----------
+
+Pithos+ is implemented in Python as a Django application. We use SQLAlchemy
+as a database abstraction layer. It is currently about
+17,000 lines of code, and it has taken about 50 person months of
+development effort. This development was done from scratch, with no
+reuse of the existing Pithos code. That service was written in the
+J2EE framework. We decided to move from J2EE to Python for
+two reasons: first, J2EE proved an overkill for the original
+Pithos service in its years of operation. Secondly, Python was
+strongly favored by the GRNET operations team, who are the people
+taking responsibility for running the service - so their voice is
+heard.
+
+Apart from the service implementation, which we have been describing
+here, we have parallel development lines for native client tools on
+different operating systems (MS-Windows, Mac OS X, Android, and iOS).
+The desktop clients allow synchronization with local directories, a
+feature that existing users of Pithos have been asking for, probably
+influenced by services like DropBox. These clients are offered in
+parallel to the standard Pithos+ interface, which is a web application
+build on top of the API front end - we treat our own web
+application as just another client that has to go through the API
+front end, without granting it access to the back end directly.
+
+We are carrying the idea of our own services being clients to Pithos+
+a step further, with new projects we have in our pipeline, in which a
+digital repository service will be built on top of Pithos+. It will
+use again the API front end, so that repository users will have
+all Pithos+ capabilities, and on top of them we will build additional
+functionality such as full text search, Dublin Core metadata storage
+and querying, streaming, and so on.
+
+At the time of this writing (March 2012) Pithos+ is in alpha,
+available to users by invitation. We will extend our user base as we
+move to beta in the coming months, and to our full set of users in the
+second half of 2012. We are eager to see how our ideas fare as we will
+scaling up, and we welcome any comments and suggestions.
+
+Acknowledgments
+---------------
+
+Pithos+ is financially supported by Grant 296114, "Advanced Computing
+Services for the Research and Academic Community", of the Greek
+National Strategic Reference Framework.
+
+Availability
+------------
+
+The Pithos+ code is available under a BSD 2-clause license from:
+https://code.grnet.gr/projects/pithos/repository
+
+The code can also be accessed from its source repository:
+https://code.grnet.gr/git/pithos/
+
+More information and documentation is available at:
+http://docs.dev.grnet.gr/pithos/latest/index.html
diff --git a/docs/quick-install-admin-guide.rst b/docs/quick-install-admin-guide.rst
index ce9ad7c..2d08894 100644
--- a/docs/quick-install-admin-guide.rst
+++ b/docs/quick-install-admin-guide.rst
@@ -11,7 +11,7 @@ assumes the nodes run Debian Squeeze. After successful installation, you will
 have the following services running:
 
  * Identity Management (Astakos)
- * File Storage Service (Pithos+)
+ * Object Storage Service (Pithos+)
  * Compute Service (Cyclades)
  * Image Registry Service (Plankton)
 
@@ -20,7 +20,7 @@ and a single unified Web UI to manage them all.
 The Volume Storage Service (Archipelago) and the Billing Service (Aquarium) are
 not released yet.
 
-If you just want to install the File Storage Service (Pithos+), follow the guide
+If you just want to install the Object Storage Service (Pithos+), follow the guide
 and just stop after the "Testing of Pithos+" section.
 
 
diff --git a/docs/quick-install-intgrt-guide.rst b/docs/quick-install-intgrt-guide.rst
index 3a55239..98a699d 100644
--- a/docs/quick-install-intgrt-guide.rst
+++ b/docs/quick-install-intgrt-guide.rst
@@ -15,7 +15,7 @@ install``, and assumes the nodes run Debian Squeeze. After successful
 installation, you will have the following services running:
 
  * Identity Management (Astakos)
- * File Storage Service (Pithos+)
+ * Object Storage Service (Pithos+)
  * Compute Service (Cyclades)
  * Image Registry Service (Plankton)
 
@@ -24,7 +24,7 @@ and a single unified Web UI to manage them all.
 The Volume Storage Service (Archipelago) and the Billing Service (Aquarium) are
 not released yet.
 
-If you just want to install the File Storage Service (Pithos+), follow the guide
+If you just want to install the Object Storage Service (Pithos+), follow the guide
 and just stop after the "Testing of Pithos+" section.
 
 Building a dev environment
