The Comprehensive Ceph Guide
فارسیGet started
Version 1.6 · new specialist part: RADOS, RBD and RGW
A Ceph handbook

The Comprehensive Ceph Guide

Designing, Implementing and Operating Scalable Storage — from the Code to Operations

From the first cluster to source code and on-disk bytes, with tested commands, purpose-made figures and algorithms taken straight from the Ceph code.

Start reading Get started Read the Persian edition

42chapters
375figures
188algorithm boxes
4parts

Written by Ramin Najarbashi

Version 1.6 · November 2026
Technical basis: Ceph Squid (19.2), Tentacle (20.2) and Umbrella (21.2)

Cover of the book "The Comprehensive Ceph Guide" by Ramin Najarbashi

Where should I start?

Pick a path for what you need from Ceph today. Every chapter stands on its own and links to the others.

Chapter 1New to CephLearn the RADOS and CRUSH architecture and bring up a first cluster.Open Chapter 11DeploymentLab, cephadm, Ansible and Rook, from hardware design to a production cluster.Open Chapter 7Day-to-day operationsPools and PGs, upgrades, disk replacement and an operator's routine tasks.Open Chapter 17When something breaksStuck PGs, slow OSDs, lost quorum: a step-by-step troubleshooting method.Open Chapter 22DevelopersFollow the Ceph code structure and a request's path from librados to BlueStore.Open Part IVRADOS, RBD and RGW specialistsOn-RADOS formats, algorithms and complete command references, checked against main.Open

Interactive lab

Seven small simulators that run the book's algorithms in your browser: no network, no installation. The arithmetic is a line-by-line port of Ceph's own code and is checked against it by the tests in tests/sims (make check-sims).

CRUSH playgroundBuild a root, hosts and OSDs, choose a rule, and watch straw2 place every PG; mark an OSD out or down or change a weight and see which PGs move.PG count calculatorGive the OSD count and each pool's share of the data: see the classic pgcalc answer and what the pg_autoscaler would choose, pass by pass.Replication or erasure codingChoose k, m and the plugin and compare usable capacity, overhead, the failures each layout survives and the cost of repairing one chunk.Peering and recovery stepperStep through three stories of one PG with three replicas and watch the PeeringState machine, the up and acting sets and the PG logs.BlueStore write pathChoose the device, offset and length of a write and watch BlueStore split it and decide what goes through the WAL (deferred) and what is written directly.RGW PUT and multipartGive a key and a size and follow an S3 PUT through radosgw to the bucket index and the data pool, with the RADOS objects it creates.RBD striping mapperSet an image's object size, stripe_unit and stripe_count and an I/O's offset and length: see which rbd_data objects it touches and where.

Interactive lab

The four parts of the book

The book starts with day-to-day work and goes one layer deeper at a time.

Part I · Chapters 1–21

Foundations and operations

Architecture and a first cluster, RBD, RGW and multisite, CephFS, operations, BlueStore, erasure coding, troubleshooting, monitoring and tuning.

10 h 47 min

123456789101112131415161718192021
Special part · Chapter 22

Code architecture

The layout of the Ceph repository and the full path of a request, function by function, from client to disk.

19 min

22
Part III · Chapters 23–33

Lower Layers

Chapters 23–33 revisit Ceph from the lowest layer up.

4 h 21 min

2324252627282930313233
Part IV · Chapters 34–42New

Specialist Part: RADOS, RBD and RGW

Chapters 34–42 examine RADOS, RBD and RGW in depth, at the code level.

2 h 23 min

343536373839404142

Contents

The list of all chapters and appendices, with their main sections and reading times, is on a separate contents page.

Full table of contents

About this work

About this work. This book is an original work. The text, explanations, examples, commands, exercises and all figures were written and designed for it. The English edition is the author's English version of the Persian text.

Source code. Short excerpts of Ceph code are quoted with their paths from github.com/ceph/ceph (LGPL-2.1/3.0). Chapters 25 and 29 cite function names, constants and string formats from RocksDB (Apache-2.0/GPL-2.0) and the Linux kernel (GPL-2.0) with their paths. All other code is pseudocode or an example written for this book.

Trademarks. Ceph and the names of other projects and products mentioned are trademarks of their respective owners. The cover design is original and uses no publisher's logo or design.

Licence. © 2026 Ramin Najarbashi. The text, figures and tools of this work are licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0): you may share and adapt it with attribution and under the same licence, but commercial use is not permitted without written permission. Full licence: creativecommons.org/licenses/by-nc-sa/4.0. Quoted code excerpts keep their original licences.

Use. This work is provided for personal, educational and non-commercial use. The technical information was prepared with care but comes without any warranty. Test commands in a lab before running them in production.