.. todo:: write about vstart, somewhere
+The Ceph Storage System consists of multiple components, and can be
+used in multiple ways. To guide you through it, please pick an aspect
+of Ceph that is most interesting to you:
+
+- :doc:`Object storage <object>`: read and write objects,
+ flexible-sized data containers that have both data (a sequence of
+ bytes) and metadata (mapping from keys to values), either via a
+ :doc:`library interface </api/index>`, or via an :ref:`HTTP API
+ <radosgw>`.
+
+ *Example*: an asset management system
+
+- :doc:`Block storage <block>`: use a remote data store as if it was a
+ local hard disk, for example for virtual machine disk storage, for
+ high-availability, etc.
+
+ *Example*: virtual machine system with live migration
+
+- :doc:`Distributed filesystem <filesystem>`: access the data store as
+ a network filesystem, with strict POSIX semantics such as locking.
+
+ *Example*: organization with hundreds of Linux servers with active
+ users accessing them remotely
+
+.. todo:: should the api mention above link to librados or libradospp
+ directly? which one?
+
+.. todo:: fs example could be thin clients, HPC, typical university
+ setting, what to pick?
+
+
+.. toctree::
+ :hidden:
+
+ object
+ block
+ filesystem
--- /dev/null
+=======================
+ Starting to use RADOS
+=======================
+
+.. highlight:: python
+
+
+Introduction
+============
+
+`RADOS` is the object storage component of Ceph.
+
+An object, in this context, means a named entity that has
+
+- a `name`: a sequence of bytes, unique within its container, that is
+ used to locate and access the object
+- `content`: sequence of bytes
+- `metadata`: a mapping from keys to values, for example ``color:
+ blue, importance: low``
+
+None of these have any prescribed meaning to Ceph, and can be freely
+chosen by the user.
+
+`RADOS` takes care of distributing the objects across the whole
+storage cluster and replicating them for fault tolerance.
+
+
+Installation
+============
+
+To use `RADOS`, you need to install a Ceph cluster. Follow the
+instructions in :doc:`/ops/install/index`. Continue with these
+instructions once you have a healthy cluster running.
+
+
+Setup
+=====
+
+First, we need to create a `pool` that will hold our assets. Follow
+the instructions in :ref:`create-new-pool`. Let's name the pool
+``assets``.
+
+Then, we need a ``client`` key that is authorized to access that
+pool. Follow the instructions in :ref:`add-new-key`. Let's set the
+``id`` of the key to be ``webapp``. You could set up one key per
+machine running the web service, or let them share a single key; your
+call. Make sure the keyring containing the new key is available on the
+machine running the asset management system.
+
+Then, authorize the key to access the new pool. Follow the
+instructions in :ref:`auth-pool`.
+
+
+Usage
+=====
+
+`RADOS` is accessed via a network protocol, implemented in the
+:doc:`/api/librados` and :doc:`/api/libradospp` libraries. There are
+also wrappers for other languages.
+
+.. todo:: link to python, phprados here
+
+Instead of a low-level programming library, you can also use a
+higher-level service, with user accounts, access control and such
+features, via the :ref:`radosgw` HTTP service. See :doc:`/ops/radosgw`
+for more.
+
+
+.. rubric:: Example: Asset management
+
+Let's say we write our asset management system in Python. We'll use
+the ``rados`` Python module for accessing `RADOS`.
+
+.. todo:: link to rados.py, where ever it'll be documented
+
+With the key we created in Setup_, we'll be able to open a RADOS
+connection::
+
+ import rados
+
+ r=rados.Rados('webapp')
+ r.conf_read_file()
+ r.connect()
+
+ ioctx = r.open_ioctx('assets')
+
+and then write an object::
+
+ # holding content fully in memory to make the example simpler;
+ # see API docs for how to do this better
+ ioctx.write_full('1.jpg', 'jpeg-content-goes-here')
+
+and read it back::
+
+ # holding content fully in memory to make the example simpler;
+ # see API docs for how to do this better
+ content = ioctx.write_full('1.jpg')
+
+
+We can also manipulate the metadata related to the object::
+
+ ioctx.set_xattr('1.jpg', 'content-type', 'image/jpeg')
+
+
+Now you can use these as fits the web server framework of your choice,
+passing the ``ioctx`` variable from initialization to the request
+serving function.
projects / ceph.git / commitdiff