diff options
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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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) |
