Essentials (tl;dr)

This chapter presents essential information that every Ceph developer needs to know.


The Ceph project is led by Sage Weil. In addition, each major project component has its own lead. The following table shows all the leads and their nicks on GitHub:



GitHub nick


Sage Weil



Neha Ojha



Yehuda Sadeh



Matt Benjamin



Jason Dillaman



Patrick Donnelly



Lenz Grimmer



Joao Luis



Ken Dreyer


The Ceph-specific acronyms in the table are explained in Architecture.


See the History chapter of the Wikipedia article.


Ceph is free software.

Unless stated otherwise, the Ceph source code is distributed under the terms of the LGPL2.1 or LGPL3.0. For full details, see the file COPYING in the top-level directory of the source-code tree.

Source code repositories

The source code of Ceph lives on GitHub in a number of repositories below the Ceph “organization”.

To make a meaningful contribution to the project as a developer, a working knowledge of git is essential.

Although the Ceph “organization” includes several software repositories, this document covers only one:

Redmine issue tracker

Although GitHub is used for code, Ceph-related issues (Bugs, Features, Backports, Documentation, etc.) are tracked at, which is powered by Redmine.

The tracker has a Ceph project with a number of subprojects loosely corresponding to the various architectural components (see Architecture).

Mere registration in the tracker automatically grants permissions sufficient to open new issues and comment on existing ones.

To report a bug or propose a new feature, jump to the Ceph project and click on New issue.

Mailing list

The list is for discussion about the development of Ceph, its interoperability with other technology, and the operations of the project itself.

Ceph development email discussions the list is open to all. Subscribe by sending a message to with the line:

subscribe ceph-devel

in the body of the message.

The list is for discussion and patch review for the Linux kernel Ceph client component. Note that this list used to be an all encompassing list for developers. So when searching archives here are the generic devel-ceph archives pre mid-2018.

Subscription works in the same way, sending a message to with the line:

subscribe ceph-devel

in the body of the message.

Ceph development email discussions the list is open to all. Subscribe by sending a message to with the line:

subscribe ceph-devel

in the body of the message.

Subscribing to the

There are also other Ceph-related mailing lists.


In addition to mailing lists, the Ceph community also communicates in real time using Internet Relay Chat.

See for how to set up your IRC client and a list of channels.

Submitting patches

The canonical instructions for submitting patches are contained in the file CONTRIBUTING.rst in the top-level directory of the source-code tree. There may be some overlap between this guide and that file.

All newcomers are encouraged to read that file carefully.

Building from source

See instructions at Build Ceph.

Using ccache to speed up local builds

Rebuilds of the ceph source tree can benefit significantly from use of ccache.

Many a times while switching branches and such, one might see build failures for certain older branches mostly due to older build artifacts. These rebuilds can significantly benefit the use of ccache. For a full clean source tree, one could do

$ make clean

# note the following will nuke everything in the source tree that
# isn't tracked by git, so make sure to backup any log files /conf options

$ git clean -fdx; git submodule foreach git clean -fdx

ccache is available as a package in most distros. To build ceph with ccache one can:

$ cmake -DWITH_CCACHE=ON ..

ccache can also be used for speeding up all builds in the system. for more details refer to the run modes of the ccache manual. The default settings of ccache can be displayed with ccache -s.


It is recommended to override the max_size, which is the size of cache, defaulting to 10G, to a larger size like 25G or so. Refer to the configuration section of ccache manual.

To further increase the cache hit rate and reduce compile times in a development environment, it is possible to set version information and build timestamps to fixed values, which avoids frequent rebuilds of binaries that contain this information.

This can be achieved by adding the following settings to the ccache configuration file ccache.conf:

sloppiness = time_macros
run_second_cpp = true

Now, set the environment variable SOURCE_DATE_EPOCH to a fixed value (a UNIX timestamp) and set ENABLE_GIT_VERSION to OFF when running cmake:

$ export SOURCE_DATE_EPOCH=946684800


Binaries produced with these build options are not suitable for production or debugging purposes, as they do not contain the correct build time and git version information.

Development-mode cluster

See Developer Guide (Quick).

Kubernetes/Rook development cluster

See Hacking on Ceph in Kubernetes with Rook


All bugfixes should be merged to the master branch before being backported. To flag a bugfix for backporting, make sure it has a tracker issue associated with it and set the Backport field to a comma-separated list of previous releases (e.g. “hammer,jewel”) that you think need the backport. The rest (including the actual backporting) will be taken care of by the Stable Releases and Backports team.

Guidance for use of cluster log

If your patches emit messages to the Ceph cluster log, please consult this guidance: Use of the cluster log.