ceph-deploy – Deploy Ceph with minimal infrastructure

ceph-deploy is a way to deploy Ceph relying on just SSH access to the servers, sudo, and some Python. It runs fully on your workstation, requiring no servers, databases, or anything like that.

If you set up and tear down Ceph clusters a lot, and want minimal extra bureaucracy, this is for you.

What this tool is not

It is not a generic deployment system, it is only for Ceph, and is designed for users who want to quickly get Ceph running with sensible initial settings without the overhead of installing Chef, Puppet or Juju.

It does not handle client configuration beyond pushing the Ceph config file and users who want fine-control over security settings, partitions or directory locations should use a tool such as Chef or Puppet.


Depending on what type of usage you are going to have with ceph-deploy you might want to look into the different ways to install it. For automation, you might want to bootstrap directly. Regular users of ceph-deploy would probably install from the OS packages or from the Python Package Index.

Python Package Index

If you are familiar with Python install tools (like pip and easy_install) you can easily install ceph-deploy like:

pip install ceph-deploy

It should grab all the dependencies for you and install into the current user’s environment.

We highly recommend using virtualenv and installing dependencies in a contained way.


All new releases of ceph-deploy are pushed to all ceph DEB release repos.

The DEB release repos are found at:


This means, for example, that installing ceph-deploy from http://ceph.com/debian-giant will install the same version as from http://ceph.com/debian-firefly or http://ceph.com/debian-testing.


All new releases of ceph-deploy are pushed to all ceph RPM release repos.

The RPM release repos are found at:


Make sure you add the proper one for your distribution (i.e. el7 vs rhel7).

This means, for example, that installing ceph-deploy from http://ceph.com/rpm-giant will install the same version as from http://ceph.com/rpm-firefly or http://ceph.com/rpm-testing.


To get the source tree ready for use, run this once:


You can symlink the ceph-deploy script in this somewhere convenient (like ~/bin), or add the current directory to PATH, or just always type the full path to ceph-deploy.

SSH and Remote Connections

ceph-deploy will attempt to connect via SSH to hosts when the hostnames do not match the current host’s hostname. For example, if you are connecting to host node1 it will attempt an SSH connection as long as the current host’s hostname is not node1.

ceph-deploy at a minimum requires that the machine from which the script is being run can ssh as root without password into each Ceph node.

To enable this generate a new ssh keypair for the root user with no passphrase and place the public key (id_rsa.pub or id_dsa.pub) in:


and ensure that the following lines are in the sshd config:

PermitRootLogin yes
PermitEmptyPasswords yes

The machine running ceph-deploy does not need to have the Ceph packages installed unless it needs to admin the cluster directly using the ceph command line tool.


When not specified the connection will be done with the same username as the one executing ceph-deploy. This is useful if the same username is shared in all the nodes but can be cumbersome if that is not the case.

A way to avoid this is to define the correct usernames to connect with in the SSH config, but you can also use the --username flag as well:

ceph-deploy --username ceph install node1

ceph-deploy then in turn would use ceph@node1 to connect to that host.

This would be the same expectation for any action that warrants a connection to a remote host.

Managing an existing cluster

You can use ceph-deploy to provision nodes for an existing cluster. To grab a copy of the cluster configuration file (normally ceph.conf):

ceph-deploy config pull HOST

You will usually also want to gather the encryption keys used for that cluster:

ceph-deploy gatherkeys MONHOST

At this point you can skip the steps below that create a new cluster (you already have one) and optionally skip installation and/or monitor creation, depending on what you are trying to accomplish.

Installing packages

For detailed information on installation instructions refer to the install section.

Proxy or Firewall Installs

If attempting to install behind a firewall or through a proxy you can use the --no-adjust-repos that will tell ceph-deploy to skip any changes to the distro’s repository in order to install the packages and it will go straight to package installation.

That will allow an environment without internet access to point to its own repositories. This means that those repositories will need to be properly setup (and mirrored with all the necessary dependencies) before attempting an install.

Another alternative is to set the wget env variables to point to the right hosts, for example:


Creating a new configuration

To create a new configuration file and secret key, decide what hosts will run ceph-mon, and run:

ceph-deploy new MON [MON..]

For detailed information on new instructions refer to the new section.

For detailed information on new subcommand refer to the mon section.

Deploying monitors

To actually deploy ceph-mon to the hosts you chose, run:

ceph-deploy mon create HOST [HOST..]

Without explicit hosts listed, hosts in mon_initial_members in the config file are deployed. That is, the hosts you passed to ceph-deploy new are the default value here.

For detailed information on mon subcommand refer to the mon section.

Gather keys

To gather authentication keys (for administering the cluster and bootstrapping new nodes) to the local directory, run:

ceph-deploy gatherkeys HOST [HOST...]

where HOST is one of the monitor hosts.

Once these keys are in the local directory, you can provision new OSDs etc.

For detailed information on gatherkeys subcommand refer to the gatherkeys section.

Admin hosts

To prepare a host with a ceph.conf and ceph.client.admin.keyring keyring so that it can administer the cluster, run:

ceph-deploy admin HOST [HOST ...]

Older versions of ceph-deploy automatically added the admin keyring to all mon nodes making them admin nodes. For detailed information on the admin command refer to the admin section.

For detailed information on admin subcommand refer to the admin section.

Deploying OSDs

To create an OSD on a remote node, run:

ceph-deploy osd create HOST --data /path/to/device

Alternatively, --data can accept a logical volume in the format of vg/lv

After that, the hosts will be running OSDs for the given data disks or logical volumes. For other OSD devices like journals (when using --filestore) or block.db, and block.wal, these need to be logical volumes or GPT partitions.


Partitions aren’t created by this tool, they must be created beforehand

Forget keys

The new and gatherkeys put some Ceph authentication keys in keyrings in the local directory. If you are worried about them being there for security reasons, run:

ceph-deploy forgetkeys

and they will be removed. If you need them again later to deploy additional nodes, simply re-run:

ceph-deploy gatherkeys HOST [HOST...]

and they will be retrieved from an existing monitor node.

Multiple clusters

All of the above commands take a --cluster=NAME option, allowing you to manage multiple clusters conveniently from one workstation. For example:

ceph-deploy --cluster=us-west new
vi us-west.conf
ceph-deploy --cluster=us-west mon


Before anything

Make sure you have the latest version of ceph-deploy. It is actively developed and releases are coming weekly (on average). The most recent versions of ceph-deploy will have a --version flag you can use, otherwise check with your package manager and update if there is anything new.

Why is feature X not implemented?

Usually, features are added when/if it is sensible for someone that wants to get started with ceph and said feature would make sense in that context. If you believe this is the case and you’ve read “what this tool is not” and still think feature X should exist in ceph-deploy, open a feature request in the ceph tracker: http://tracker.ceph.com/projects/ceph-deploy/issues

A command gave me an error, what is going on?

Most of the commands for ceph-deploy are meant to be run remotely in a host that you have configured when creating the initial config. If a given command is not working as expected try to run the command that failed in the remote host and assert the behavior there.

If the behavior in the remote host is the same, then it is probably not something wrong with ceph-deploy per-se. Make sure you capture the output of both the ceph-deploy output and the output of the command in the remote host.

Issues with monitors

If your monitors are not starting, make sure that the {hostname} you used when you ran ceph-deploy mon create {hostname} match the actual hostname -s in the remote host.

Newer versions of ceph-deploy should warn you if the results are different but that might prevent the monitors from reaching quorum.