If you have a running Ceph Object Storage cluster in production, you may need the RESTful API for administration, integration with other systems and monitoring. The RESTful API plugin for the Ceph Manager (ceph-mgr) provides an API for interacting with your Ceph Storage cluster.

In this guide we will show you how to enable the RESTful API access on Ceph Storage cluster and creation of user for any integrations that you’ll need. Before you continue, ensure you have a working Ceph Storage Cluster. Below guides can be used as reference for small setup, not for serious production workloads.

Install Ceph 15 (Octopus) Cluster on CentOS 8

How To Install Ceph Storage Cluster on Ubuntu 18.04

The Ceph REST API allows you to:

  • Show the information about Monitors and OSDs
  • Create or edit pools
  • View and start scheduled processes on OSDs
  • Show configuration options for the cluster, Monitor, and OSDs
  • Among many other operations

Step 1: Enable RESTful API MGR Plugin

The Ceph Manager daemon (ceph-mgr) runs alongside monitor daemons, to provide additional monitoring and interfaces to external monitoring and management systems. We will enable the Ceph REST Plugin in MGR.

Login to your Ceph Cluster node with ceph configurations done correctly and run the following command to enable RESTful API plugin.

# ceph mgr module enable restful

To see all available modules status, use the command:

# ceph mgr module ls

From UI:

enable ceph mgr rest api module

Step 2: Configure SSL certificate for the API endpoint

The module will accept HTTPS requests on port 8003 on all IPv4 and IPv6 addresses on the host where mgr is running. This is the default setting unless you set it otherwise. Before the API endpoint is available, you will need to configure an SSL certificate.

If you don’t have a valid certificate signed by your company, generate a self-signed certificate with the command:

# ceph restful create-self-signed-cert

The service will be started automatically after the configuration is updated. To confirm it is working fine, use curl command to test on the active MGR node.

# curl -k https://localhost:8003/
    "api_version": 1,
    "auth": "Use \"ceph restful create-key <key>\" to create a key pair, pass it as HTTP Basic auth to authenticate",
    "doc": "See /doc endpoint",
    "info": "Ceph Manager RESTful API server"

If you use a firewall, ensure that the 8003 port is enabled on the node with the active ceph-mgr daemon. Confirm with:

# ceph -s
# firewall-cmd --add-port=5000/tcp --permanent
# firewall-cmd --reload

If you have well signed certificates, apply them using the commands:

ceph config-key set mgr/restful/crt -i restful.crt
ceph config-key set mgr/restful/key -i restful.key


  • restful.crt is the name of the certificate to apply
  • restful.key is the name of the key used with the certificate

Step 3: Create an API HTTP user with basic authentication

A user is needed for API access. Let’s create an HTTP user and generate a password for HTTP basic authentication.

The command syntax is:

# ceph restful create-key <username>

I’ll create a user called cephadmin

# ceph restful create-key cephadmin

You can always check the username and key using the following command:

# ceph restful list-keys
  "cephadmin": "1c4dcb01-587b-4558-8878-1209b525de8c"

Once the credentials are generated, you can use curl to validate API access. The command syntax is:


Here is an example:

# curl -k https://cephadmin:[email protected]:8003/server
        "ceph_version": "ceph version 14.2.7 (3d58626ebeec02d8385a4cefb92c6cbc3a45bfe8) nautilus (stable)",
        "hostname": "cephmon01.example.com",
        "services": [
                "id": "cephmon01",
                "type": "mgr"
                "id": "cephmon02",
                "type": "mon"
                "id": "cephmon03",
                "type": "rgw"

# url -k https://cephadmin:[email protected]:8003/config/osd


Your support is our everlasting motivation,
that cup of coffee is what keeps us going!

As we continue to grow, we would wish to reach and impact more people who visit and take advantage of the guides we have on our blog. This is a big task for us and we are so far extremely grateful for the kind people who have shown amazing support for our work over the time we have been online.

Thank You for your support as we work to give you the best of guides and articles. Click below to buy us a coffee.


Please enter your comment!
Please enter your name here