First draft of the documentation overhaul.

To build the docs, run ./admin/build-doc. To browse them, either get
them on any static website, or just run ./admin/serve-doc to serve
them quickly off of port 8080.

build-doc sets up a virtualenv to avoid needing Sphinx installed
system-wide. serve-doc needs thttpd installed.

Signed-off-by: Tommi Virtanen <tommi.virtanen@dreamhost.com>

33 files changed, 662 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index 4fd8426eb0d..99560459d1e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -52,3 +52,4 @@ core
 .settings
 .project
 .cproject
+/build-doc
diff --git a/admin/build-doc b/admin/build-doc
new file mode 100755
index 00000000000..fd1afe5c365
--- /dev/null
+++ b/admin/build-doc
@@ -0,0 +1,23 @@
+#!/bin/sh
+set -e
+cd "$(dirname "$0")"
+cd ..
+
+dia --filter=png-libart --export=doc/overview.png.tmp doc/overview.dia
+mv -- doc/overview.png.tmp doc/overview.png
+
+install -d -m0755 build-doc
+cd build-doc
+
+if [ ! -e virtualenv ]; then
+    virtualenv --no-site-packages virtualenv
+fi
+if [ ! -x virtualenv/bin/sphinx-build ]; then
+    ./virtualenv/bin/pip install sphinx
+fi
+
+install -d -m0755 \
+    output/html \
+    output/man
+./virtualenv/bin/sphinx-build -a -b dirhtml -d doctrees ../doc output/html
+./virtualenv/bin/sphinx-build -a -b man -d doctrees ../doc output/man
diff --git a/admin/serve-doc b/admin/serve-doc
new file mode 100755
index 00000000000..9c1bfb44c79
--- /dev/null
+++ b/admin/serve-doc
@@ -0,0 +1,29 @@
+#!/usr/bin/python
+import SimpleHTTPServer
+import SocketServer
+import os
+import sys
+
+path = os.path.dirname(sys.argv[0])
+os.chdir(path)
+os.chdir('..')
+os.chdir('build-doc/output/html')
+
+class ReusingTCPServer(SimpleHTTPServer.SimpleHTTPRequestHandler):
+    allow_reuse_address = True
+
+    def send_head(self):
+        # horrible kludge because SimpleHTTPServer is buggy wrt
+        # slash-redirecting of requests with query arguments, and will
+        # redirect to /foo?q=bar/ -- wrong slash placement
+        self.path = self.path.split('?', 1)[0]
+        return SimpleHTTPServer.SimpleHTTPRequestHandler.send_head(self)
+
+httpd = SocketServer.TCPServer(
+    ("", 8080),
+    ReusingTCPServer,
+    )
+try:
+    httpd.serve_forever()
+except KeyboardInterrupt:
+    pass
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 00000000000..295eda72a4c
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,2 @@
+*.tmp
+/overview.png
diff --git a/doc/architecture.rst b/doc/architecture.rst
new file mode 100644
index 00000000000..cf67f6be505
--- /dev/null
+++ b/doc/architecture.rst
@@ -0,0 +1,27 @@
+======================
+ Architecture of Ceph
+======================
+
+- Introduction to Ceph Project
+
+  - High-level overview of project benefits for users (few paragraphs, mention each subproject)
+  - Introduction to sub-projects (few paragraphs to a page each)
+
+    - RADOS
+    - RGW
+    - RBD
+    - Ceph
+
+  - Example scenarios Ceph projects are/not suitable for
+  - (Very) High-Level overview of Ceph
+
+    This would include an introduction to basic project terminology,
+    the concept of OSDs, MDSes, and Monitors, and things like
+    that. What they do, some of why they're awesome, but not how they
+    work.
+
+- Discussion of MDS terminology, daemon types (active, standby,
+  standby-replay)
+
+
+.. todo:: write me
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 00000000000..e8b7b6faa61
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,58 @@
+project = u'Ceph'
+copyright = u'2011, New Dream Network'
+version = 'dev'
+release = 'dev'
+
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+exclude_patterns = ['**/.#*', '**/*~']
+pygments_style = 'sphinx'
+
+html_theme = 'nature'
+html_title = "Ceph documentation"
+html_logo = 'logo.jpg'
+html_favicon = 'favicon.ico'
+html_static_path = ['_static']
+html_use_smartypants = True
+html_show_sphinx = False
+
+extensions = ['sphinx.ext.todo']
+todo_include_todos = True
+
+def _get_manpages():
+    import os
+    man_dir = os.path.join(
+        os.path.dirname(__file__),
+        'man',
+        )
+    sections = os.listdir(man_dir)
+    for section in sections:
+        section_dir = os.path.join(man_dir, section)
+        if not os.path.isdir(section_dir):
+            continue
+        for filename in os.listdir(section_dir):
+            base, ext = os.path.splitext(filename)
+            if ext != '.rst':
+                continue
+            if base == 'index':
+                continue
+            with file(os.path.join(section_dir, filename)) as f:
+                one = f.readline()
+                two = f.readline()
+                three = f.readline()
+                assert one == three
+                assert all(c=='=' for c in one.rstrip('\n'))
+                two = two.strip()
+                name, rest = two.split('--', 1)
+                assert name.strip() == base
+                description = rest.strip()
+            yield (
+                os.path.join('man', section, base),
+                base,
+                description,
+                '',
+                section,
+                )
+
+man_pages = list(_get_manpages())
diff --git a/doc/favicon.ico b/doc/favicon.ico
new file mode 100644
index 00000000000..3501dd0bbb3
--- /dev/null
+++ b/doc/favicon.ico
diff --git a/doc/glossary.rst b/doc/glossary.rst
new file mode 100644
index 00000000000..ff2e2ccc1cd
--- /dev/null
+++ b/doc/glossary.rst
@@ -0,0 +1,40 @@
+==========
+ Glossary
+==========
+
+.. glossary::
+   :sorted:
+
+   OSD
+     .. todo:: write me
+
+   MDS
+     .. todo:: write me
+
+   Mon
+     .. todo:: write me
+
+   Cap
+     .. todo:: write me
+
+   Object
+     .. todo:: write me
+
+   cosd
+     .. todo:: write me
+
+   cmon
+     .. todo:: write me
+
+   cmds
+     Ceph MDS, the actual daemon blahblah
+
+   rgw
+     .. todo:: write me
+
+   radosgw
+     .. todo:: write me
+
+
+.. todo:: what's missing from glossary
+
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 00000000000..507f5a035c0
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,106 @@
+================================
+ Ceph -- petabyte scale storage
+================================
+
+
+Welcome to Ceph
+===============
+
+Ceph is a distributed network storage and file system with distributed
+metadata management and POSIX semantics.
+
+RADOS is a reliable object store, used by Ceph, but also directly
+accessible.
+
+``radosgw`` is an S3-compatible RESTful HTTP service for object
+storage, using RADOS storage.
+
+RBD is a Linux kernel feature that exposes RADOS storage as a block
+device. Qemu/KVM also has a direct RBD client, that avoids the kernel
+overhead.
+
+.. image:: overview.png
+
+
+Getting started
+===============
+
+- :doc:`tutorial`: how to install a cluster for testing
+- `Ceph Blog <http://ceph.newdream.net/news/>`__: news and status info
+
+
+Mailing lists, bug tracker, IRC channel
+=======================================
+
+- The development mailing list is at ceph-devel@vger.kernel.org, and
+  archived at Gmane_. Send email to subscribe_ or unsubscribe_.
+- `Bug/feature tracker <http://tracker.newdream.net/projects/ceph>`__:
+  for filing bugs and feature requests.
+- IRC channel ``#ceph`` on ``irc.oftc.net``: Many of the core
+  developers are on IRC, especially daytime in the US/Pacific
+  timezone. You are welcome to join and ask questions. You can find
+  logs of the channel `here <http://irclogs.ceph.widodh.nl/>`__.
+- `Commercial support <http://ceph.newdream.net/support/>`__
+
+.. _subscribe: mailto:majordomo@vger.kernel.org?body=subscribe+ceph-devel
+.. _unsubscribe: mailto:majordomo@vger.kernel.org?body=unsubscribe+ceph-devel
+.. _Gmane: http://news.gmane.org/gmane.comp.file-systems.ceph.devel
+
+
+Status
+======
+
+The Ceph project is currently focusing on stability. Users are
+welcome, but we do not recommend storing valuable data with it yet
+without proper precautions.
+
+As of this writing, RADOS is the most stable component, and RBD block
+devices are fairly reliable, if not performance tuned yet. The OSD
+component of RADOS relies heavily on the stability and performance of
+the underlying filesystem, and we keep hearing reports of ``btrfs``
+issues; while on the long term we believe in ``btrfs``, in the short
+term you may wish to carefully consider the tradeoffs between ``ext4``
+and ``btrfs``, and make sure you are running the latest Linux kernel.
+
+Radosgw is still going through heavy development, but it will likely
+mature next.
+
+The Ceph filesystem is functionally fairly complete, but has not been
+tested well enough at scale and under load yet. Multi-master MDS is
+still problematic and we recommend running just one active MDS
+(standbys are ok). If you have problems with ``kclient`` or ``cfuse``,
+you may wish to try the other option; in general, ``kclient`` is
+expected to be faster (but be sure to use the latest Linux kernel!)
+while ``cfuse`` provides better stability by not triggering kernel
+crashes.
+
+As individual systems mature enough, we move to improving their
+performance (throughput, latency and jitter). This work is still
+mostly ahead of us.
+
+Ceph is developed on Linux. Other platforms may work, but are not the
+focus of the project. Filesystem access from other operating systems
+can be done via NFS or Samba re-exports.
+
+
+Table of Contents
+=================
+
+.. toctree::
+   :maxdepth: 3
+
+   tutorial
+   architecture
+   ops/index
+   man/index
+   papers
+   glossary
+
+
+Indices and tables
+==================
+
+- :ref:`genindex`
+- :ref:`modindex`
+- :ref:`search`
+
diff --git a/doc/logo.jpg b/doc/logo.jpg
new file mode 100644
index 00000000000..c4568999a28
--- /dev/null
+++ b/doc/logo.jpg
diff --git a/doc/man/8/ceph.rst b/doc/man/8/ceph.rst
new file mode 100644
index 00000000000..cee6c8b9d6c
--- /dev/null
+++ b/doc/man/8/ceph.rst
@@ -0,0 +1,5 @@
+==========================================
+ ceph -- ceph file system control utility
+==========================================
+
+.. todo:: write me
diff --git a/doc/man/8/index.rst b/doc/man/8/index.rst
new file mode 100644
index 00000000000..68bba2b4430
--- /dev/null
+++ b/doc/man/8/index.rst
@@ -0,0 +1,9 @@
+===========================================
+ Section 8, system administration commands
+===========================================
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *
diff --git a/doc/man/8/rados.rst b/doc/man/8/rados.rst
new file mode 100644
index 00000000000..e1aea1f1516
--- /dev/null
+++ b/doc/man/8/rados.rst
@@ -0,0 +1,5 @@
+=======================================
+ rados -- rados object storage utility
+=======================================
+
+.. todo:: write me
diff --git a/doc/man/8/rbd.rst b/doc/man/8/rbd.rst
new file mode 100644
index 00000000000..e7ead163493
--- /dev/null
+++ b/doc/man/8/rbd.rst
@@ -0,0 +1,174 @@
+===============================================
+ rbd -- manage rados block device (RBD) images
+===============================================
+
+.. program:: rbd
+
+Synopsis
+========
+
+| **rbd** [ -c *ceph.conf* ] [ -m *monaddr* ] [ -p | --pool *pool* ] [ --size *size* ] [ --order *bits* ]
+  [ *command* ... ]
+
+Description
+===========
+
+**rbd** is a utility for manipulating rados block device (RBD) images,
+used by the Linux rbd driver and the rbd storage driver for Qemu/KVM.
+RBD images are simple block devices that are striped over objects and
+stored in a RADOS object store. The size of the objects the image is
+striped over must be a power of two.
+
+
+Options
+=======
+
+.. option:: -c ceph.conf, --conf ceph.conf
+
+   Use ceph.conf configuration file instead of the default /etc/ceph/ceph.conf to
+   determine monitor addresses during startup.
+
+.. option:: -m monaddress[:port]
+
+   Connect to specified monitor (instead of looking through ceph.conf).
+
+.. option:: -p pool, --pool pool
+
+   Interact with the given pool. Required by most commands.
+
+
+Parameters
+==========
+
+.. option:: --size size-in-mb
+
+   Specifies the size (in megabytes) of the new rbd image.
+
+.. option:: --order bits
+
+   Specifies the object size expressed as a number of bits, such that
+   the object size is ``1 << order``. The default is 22 (4 MB).
+
+.. option:: --snap snap
+
+   Specifies the snapshot name for the specific operation.
+
+.. option:: --user username
+
+   Specifies the username to use with the map command.
+
+.. option:: --secret filename
+
+   Specifies a file containing the secret to use with the map command.
+
+
+Commands
+========
+
+.. todo:: rst "option" directive seems to require --foo style options, parsing breaks on subcommands.. the args show up as bold too
+
+:command:`ls` [*pool*]
+  Will list all rbd images listed in the rbd_directory object.
+
+:command:`info` [*image-name*]
+  Will dump information (such as size and order) about a specific rbd image.
+
+:command:`create` [*image-name*]
+  Will create a new rbd image. You must also specify the size via --size.
+
+:command:`resize` [*image-name*]
+  Resizes rbd image. The size parameter also needs to be specified.
+
+:command:`rm` [*image-name*]
+  Deletes rbd image (including all data blocks)
+
+:command:`rm` [*image-name*]
+  Deletes rbd image (including all data blocks)
+
+:command:`export` [*image-name*] [*dest-path*]
+  Exports image to dest path.
+
+:command:`import` [*path*] [*dest-image*]
+  Creates a new image and imports its data from path.
+
+:command:`cp` [*src-image*] [*dest-image*]
+  Copies the content of a src-image into the newly created dest-image.
+
+:command:`mv` [*src-image*] [*dest-image*]
+  Renames an image.
+
+:command:`snap` ls [*image-name*]
+  Dumps the list of snapshots inside a specific image.
+
+:command:`snap` create [*image-name*]
+  Creates a new snapshot. Requires the snapshot name parameter specified.
+
+:command:`snap` rollback [*image-name*]
+  Rollback image content to snapshot. This will iterate through the entire blocks
+  array and update the data head content to the snapshotted version.
+
+:command:`snap` rm [*image-name*]
+  Removes the specified snapshot.
+
+:command:`map` [*image-name*]
+  Maps the specified image to a block device via the rbd kernel module.
+
+:command:`unmap` [*device-path*]
+  Unmaps the block device that was mapped via the rbd kernel module.
+
+
+Image name
+==========
+
+In addition to using the --pool and the --snap options, the image name can include both
+the pool name and the snapshot name. The image name format is as follows::
+
+       [pool/]image-name[@snap]
+
+Thus an image name that contains a slash character ('/') requires specifying the pool
+name explicitly.
+
+
+Examples
+========
+
+To create a new rbd image that is 100 GB::
+
+       rbd -p mypool create myimage --size 102400
+
+or alternatively::
+
+       rbd create mypool/myimage --size 102400
+
+To use a non-default object size (8 MB)::
+
+       rbd create mypool/myimage --size 102400 --order 23
+
+To delete an rbd image (be careful!)::
+
+       rbd rm mypool/myimage
+
+To create a new snapshot::
+
+       rbd create mypool/myimage@mysnap
+
+To map an image via the kernel with cephx enabled::
+
+       rbd map myimage --user admin --secret secretfile
+
+To unmap an image::
+
+       rbd unmap /dev/rbd0
+
+
+Availability
+============
+
+**rbd** is part of the Ceph distributed file system. Please refer to
+the Ceph wiki at http://ceph.newdream.net/wiki for more information.
+
+
+See also
+========
+
+:doc:`ceph <ceph>`\(8), :doc:`rados <rados>`\(8)
diff --git a/doc/man/index.rst b/doc/man/index.rst
new file mode 100644
index 00000000000..e59fde44c85
--- /dev/null
+++ b/doc/man/index.rst
@@ -0,0 +1,9 @@
+==============
+ Manual pages
+==============
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   */index
diff --git a/doc/ops/config.rst b/doc/ops/config.rst
new file mode 100644
index 00000000000..5ee0ac66ad2
--- /dev/null
+++ b/doc/ops/config.rst
@@ -0,0 +1,16 @@
+==============================
+ Ceph configuration reference
+==============================
+
+.. todo:: write me
+
+OSD (RADOS)
+===========
+
+Monitor
+=======
+
+MDS
+===
+
+
diff --git a/doc/ops/data-placement.rst b/doc/ops/data-placement.rst
new file mode 100644
index 00000000000..f9aa4a6381c
--- /dev/null
+++ b/doc/ops/data-placement.rst
@@ -0,0 +1,20 @@
+================
+ Data placement
+================
+
+Placement policies
+==================
+
+.. todo:: brief intro to CRUSH, pointers to more
+
+Creating new pools
+==================
+
+Using custom pools in Ceph POSIX
+================================
+
+Custom pool layouts with CRUSH
+==============================
+
+Considerations and tradeoffs of different placement policies
+============================================================
diff --git a/doc/ops/filesystem.rst b/doc/ops/filesystem.rst
new file mode 100644
index 00000000000..6a9ddeca7a6
--- /dev/null
+++ b/doc/ops/filesystem.rst
@@ -0,0 +1,5 @@
+=======================================
+ Underlying filesystem recommendations
+=======================================
+
+.. todo:: Benefits of each, limits on non-btrfs ones, performance data when we have them, etc
diff --git a/doc/ops/grow/index.rst b/doc/ops/grow/index.rst
new file mode 100644
index 00000000000..6e5df4e199e
--- /dev/null
+++ b/doc/ops/grow/index.rst
@@ -0,0 +1,12 @@
+=====================================
+ Growing or shrinking a Ceph cluster
+=====================================
+
+.. todo:: write me
+
+.. toctree::
+
+   osd
+   placement-groups
+   mds
+   mon
diff --git a/doc/ops/grow/mds.rst b/doc/ops/grow/mds.rst
new file mode 100644
index 00000000000..1064b9711cb
--- /dev/null
+++ b/doc/ops/grow/mds.rst
@@ -0,0 +1,15 @@
+===============================
+ Resizing the metadata cluster
+===============================
+
+Adding new MDSes
+================
+
+
+Setting up standby and standby-replay MDSes
+-------------------------------------------
+
+
+Removing MDSes
+==============
+
diff --git a/doc/ops/grow/mon.rst b/doc/ops/grow/mon.rst
new file mode 100644
index 00000000000..eee28004ec0
--- /dev/null
+++ b/doc/ops/grow/mon.rst
@@ -0,0 +1,5 @@
+==============================
+ Resizing the monitor cluster
+==============================
+
+.. todo:: Choosing and adjusting cluster size
diff --git a/doc/ops/grow/osd.rst b/doc/ops/grow/osd.rst
new file mode 100644
index 00000000000..b1e8ebf69d3
--- /dev/null
+++ b/doc/ops/grow/osd.rst
@@ -0,0 +1,12 @@
+============================
+ Resizing the RADOS cluster
+============================
+
+Adding new OSDs
+===============
+
+
+Removing OSDs
+=============
+
+See also :ref:`recover-osd`.
diff --git a/doc/ops/grow/placement-groups.rst b/doc/ops/grow/placement-groups.rst
new file mode 100644
index 00000000000..c4fc71fa1f1
--- /dev/null
+++ b/doc/ops/grow/placement-groups.rst
@@ -0,0 +1,5 @@
+=======================
+ Splitting/joining PGs
+=======================
+
+.. todo:: write me
diff --git a/doc/ops/hardware.rst b/doc/ops/hardware.rst
new file mode 100644
index 00000000000..a3c5872d019
--- /dev/null
+++ b/doc/ops/hardware.rst
@@ -0,0 +1,10 @@
+==========================
+ Hardware recommendations
+==========================
+
+Hardware requirements and tradeoffs
+===================================
+
+Discussing the hardware requirements for each daemon, the tradeoffs of
+doing one cosd per machine versus one per disk, and hardware-related
+configuration options like journaling locations.
diff --git a/doc/ops/index.rst b/doc/ops/index.rst
new file mode 100644
index 00000000000..3221394d374
--- /dev/null
+++ b/doc/ops/index.rst
@@ -0,0 +1,16 @@
+============
+ Operations
+============
+
+.. toctree::
+
+   install
+   manage
+   config
+   radosgw
+   rbd
+   hardware
+   filesystem
+   monitor
+   grow/index
+   data-placement
diff --git a/doc/ops/install.rst b/doc/ops/install.rst
new file mode 100644
index 00000000000..692ac926bec
--- /dev/null
+++ b/doc/ops/install.rst
@@ -0,0 +1,14 @@
+===========================
+ Installing a Ceph cluster
+===========================
+
+.. todo:: write me
+
+Authentication is optional but very much recommended.
+
+Basically, everything somebody needs to go through to build a new
+cluster when not cheating via vstart or teuthology, but without
+mentioning all the design tradeoffs and options like journaling
+locations or filesystems
+
+At this point, either use 1 or 3 mons, point to :doc:`grow/mon`
diff --git a/doc/ops/manage.rst b/doc/ops/manage.rst
new file mode 100644
index 00000000000..0c3e1ccc4cc
--- /dev/null
+++ b/doc/ops/manage.rst
@@ -0,0 +1,18 @@
+=========================
+ Managing a Ceph cluster
+=========================
+
+.. todo::
+
+   - ./ceph usage
+   - ./rados usage
+
+
+Adding a new client
+===================
+
+.. _recover-osd:
+
+Recovering from disk or OSD failures
+====================================
+
diff --git a/doc/ops/monitor.rst b/doc/ops/monitor.rst
new file mode 100644
index 00000000000..f58914ea5ab
--- /dev/null
+++ b/doc/ops/monitor.rst
@@ -0,0 +1,5 @@
+=================
+ Monitoring Ceph
+=================
+
+.. todo:: write me
diff --git a/doc/ops/radosgw.rst b/doc/ops/radosgw.rst
new file mode 100644
index 00000000000..fdd48331301
--- /dev/null
+++ b/doc/ops/radosgw.rst
@@ -0,0 +1,3 @@
+=========================================
+ Radosgw installation and administration
+=========================================
diff --git a/doc/ops/rbd.rst b/doc/ops/rbd.rst
new file mode 100644
index 00000000000..07e34890ab8
--- /dev/null
+++ b/doc/ops/rbd.rst
@@ -0,0 +1,4 @@
+==============================
+ RBD setup and administration
+==============================
+
diff --git a/doc/overview.dia b/doc/overview.dia
new file mode 100644
index 00000000000..d48fd40517d
--- /dev/null
+++ b/doc/overview.dia
diff --git a/doc/papers.rst b/doc/papers.rst
new file mode 100644
index 00000000000..37546d5b1f8
--- /dev/null
+++ b/doc/papers.rst
@@ -0,0 +1,5 @@
+=================
+ Academic papers
+=================
+
+.. todo:: transfer content from http://ceph.newdream.net/publications/ ?
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
new file mode 100644
index 00000000000..819c909a369
--- /dev/null
+++ b/doc/tutorial.rst
@@ -0,0 +1,9 @@
+===============
+ Ceph tutorial
+===============
+
+.. todo:: write me
+
+   2) Quick Start (how to get a 1-3 machine cluster running quickly)
+   - Simple setup guide (single machine, vstart)
+   - Simple setup guide (mutliple machines)