Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Ceph RESTful API

As a storage administrator, you can use the Ceph RESTful API, or simply the Ceph API, provided by the Red Hat Ceph Storage Dashboard to interact with the Red Hat Ceph Storage cluster. You can display information about the Ceph Monitors and OSDs, along with their respective configuration options. You can even create or edit Ceph pools.

The Ceph API uses the following standards:

  • HTTP 1.1
  • JSON
  • MIME and HTTP Content Negotiation
  • JWT

These standards are OpenAPI 3.0 compliant, regulating the API syntax, semantics, content encoding, versioning, authentication, and authorization.

1.1. Prerequisites

  • A healthy running Red Hat Ceph Storage cluster.
  • Access to the node running the Ceph Manager.

1.2. Versioning for the Ceph API

A main goal for the Ceph RESTful API, is to provide a stable interface. To achieve a stable interface, the Ceph API is built on the following principles:

  • A mandatory explicit default version for all endpoints to avoid implicit defaults.

  • Fine-grain change control per-endpoint.

    • The expected version from a specific endpoint is stated in the HTTP header.

      Syntax

      Accept: application/vnd.ceph.api.vMAJOR.MINOR+json
      Copy to clipboard

      Example

      Accept: application/vnd.ceph.api.v1.0+json
      Copy to clipboard

      If the current Ceph API server is not able to address that specific version, a 415 - Unsupported Media Type response will be returned.

  • Using semantic versioning.

    • Major changes are backwards incompatible. Changes might result in non-additive changes to the request, and to the response formats for a specific endpoint.
    • Minor changes are backwards and forwards compatible. Changes consist of additive changes to the request or response formats for a specific endpoint.

1.3. Authentication and authorization for the Ceph API

Access to the Ceph RESTful API goes through two checkpoints. The first is authenticating that the request is done on the behalf of a valid, and existing user. Secondly, is authorizing the previously authenticated user can do a specific action, such as creating, reading, updating, or deleting, on the target end point.

Before users start using the Ceph API, they need a valid JSON Web Token (JWT). The /api/auth endpoint allows you to retrieve this token.

Example

[root@mon ~]# curl -X POST "https://example.com:8443/api/auth" \
  -H  "Accept: application/vnd.ceph.api.v1.0+json" \
  -H  "Content-Type: application/json" \
  -d '{"username": "user1", "password": "password1"}'
Copy to clipboard

This token must be used together with every API request by placing it within the Authorization HTTP header.

Syntax

curl -H "Authorization: Bearer TOKEN" ...
Copy to clipboard

Additional Resources

  • See the Ceph user management chapter in the Red Hat Ceph Storage Administration Guide for more details.

1.4. Enabling and Securing the Ceph API module

The Red Hat Ceph Storage Dashboard module offers the RESTful API access to the storage cluster over an SSL-secured connection.

Important

If disabling SSL, then user names and passwords are sent unencrypted to the Red Hat Ceph Storage Dashboard.

Prerequisites

  • Root-level access to a Ceph Monitor node.
  • Ensure that you have at least one ceph-mgr daemon active.
  • If you use a firewall, ensure that TCP port 8443, for SSL, and TCP port 8080, without SSL, are open on the node with the active ceph-mgr daemon.

Procedure

  1. Log into the Cephadm shell:

    Example

    root@host01 ~]# cephadm shell
    Copy to clipboard

  2. Enable the RESTful plug-in: 

    [ceph: root@host01 /]# ceph mgr module enable dashboard
    Copy to clipboard

  3. Configure an SSL certificate.

    1. If your organization’s certificate authority (CA) provides a certificate, then set using the certificate files:

      Syntax

      ceph dashboard set-ssl-certificate HOST_NAME -i CERT_FILE
ceph dashboard set-ssl-certificate-key HOST_NAME -i KEY_FILE
      Copy to clipboard

      Example

      [ceph: root@host01 /]# ceph dashboard set-ssl-certificate -i dashboard.crt
[ceph: root@host01 /]# ceph dashboard set-ssl-certificate-key -i dashboard.key
      Copy to clipboard

      If you want to set unique node-based certificates, then add a HOST_NAME to the commands:

      Example

      [ceph: root@host01 /]# ceph dashboard set-ssl-certificate host01 -i dashboard.crt
[ceph: root@host01 /]# ceph dashboard set-ssl-certificate-key host01 -i dashboard.key
      Copy to clipboard

    2. Alternatively, you can generate a self-signed certificate. However, using a self-signed certificate does not provide full security benefits of the HTTPS protocol: 

      [ceph: root@host01 /]# ceph dashboard create-self-signed-cert
      Copy to clipboard
      Warning

      Most modern web browsers will complain about self-signed certificates, which require you to confirm before establishing a secure connection.

  4. Create a user, set the password, and set the role:

    Syntax

    echo -n "PASSWORD" > PATH_TO_FILE/PASSWORD_FILE
ceph dashboard ac-user-create USER_NAME -i PASSWORD_FILE ROLE
    Copy to clipboard

    Example

    [ceph: root@host01 /]# echo -n "p@ssw0rd" > /root/dash-password.txt
[ceph: root@host01 /]# ceph dashboard ac-user-create user1 -i /root/dash-password.txt administrator
    Copy to clipboard

    This example creates a user named user1 with the administrator role.

  5. Connect to the RESTful plug-in web page. Open a web browser and enter the following URL:

    Syntax

    https://HOST_NAME:8443
    Copy to clipboard

    Example

    https://host01:8443
    Copy to clipboard

    If you used a self-signed certificate, confirm a security exception.

Additional Resources

1.5. Questions and Answers

1.5.1. Getting Information

This section describes how to use the Ceph API to view information about the storage cluster, Ceph Monitors, OSDs, pools, and hosts:

1.5.1.1. How Can I View All Cluster Configuration Options?

This section describes how to use the RESTful plug-in to view cluster configuration options and their values.

The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:CEPH_MANAGER_PORT/api/cluster_conf'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • CEPH_MANAGER_PORT with the TCP port number. The default TCP port number is 8443.

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/cluster_conf'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/cluster_conf', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/cluster_conf', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/cluster_conf
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user name and password when prompted.

Additional Resources

1.5.1.2. How Can I View a Particular Cluster Configuration Option?

This section describes how to view a particular cluster option and its value.

The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/cluster_conf/ARGUMENT'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ARGUMENT with the configuration option you want to view

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/cluster_conf/ARGUMENT'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/cluster_conf/ARGUMENT', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ARGUMENT with the configuration option you want to view
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/cluster_conf/ARGUMENT', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/cluster_conf/ARGUMENT
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ARGUMENT with the configuration option you want to view

Enter the user name and password when prompted.

Additional Resources

1.5.1.3. How Can I View All Configuration Options for OSDs?

This section describes how to view all configuration options and their values for OSDs.

The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/osd/flags'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/osd/flags'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/osd/flags', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/osd/flags', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/osd/flags
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user name and password when prompted.

Additional Resources

1.5.1.4. How Can I View CRUSH Rules?

This section describes how to view CRUSH rules.

The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/crush_rule'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/crush_rule'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/crush_rule', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/crush_rule', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/crush_rule
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user name and password when prompted.

Additional Resources
  • The CRUSH Rules section in the Administration Guide for Red Hat Ceph Storage 5.

1.5.1.5. How Can I View Information about Monitors?

This section describes how to view information about a particular Monitor, such as:

  • IP address
  • Name
  • Quorum status
The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/monitor'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/monitor'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/monitor', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/monitor', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/monitor
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user name and password when prompted.

1.5.1.6. How Can I View Information About a Particular Monitor?

This section describes how to view information about a particular Monitor, such as:

  • IP address
  • Name
  • Quorum status
The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/monitor/NAME'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • NAME with the short host name of the Monitor

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/monitor/NAME'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/monitor/NAME', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • NAME with the short host name of the Monitor
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/monitor/NAME', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/monitor/NAME
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • NAME with the short host name of the Monitor

Enter the user name and password when prompted.

1.5.1.7. How Can I View Information about OSDs?

This section describes how to view information about OSDs, such as:

  • IP address
  • Its pools
  • Affinity
  • Weight
The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/osd'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/osd'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/osd/', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/osd/', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/osd
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user name and password when prompted.

1.5.1.8. How Can I View Information about a Particular OSD?

This section describes how to view information about a particular OSD, such as:

  • IP address
  • Its pools
  • Affinity
  • Weight
The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/osd/ID'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/osd/ID'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/osd/ID', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/osd/ID', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/osd/ID
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field

Enter the user name and password when prompted.

1.5.1.9. How Can I Determine What Processes Can Be Scheduled on an OSD?

This section describes how to use the RESTful plug-in to view what processes, such as scrubbing or deep scrubbing, can be scheduled on an OSD.

The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/osd/ID/command'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/osd/ID/command'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/osd/ID/command', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/osd/ID/command', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/osd/ID/command
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field

Enter the user name and password when prompted.

1.5.1.10. How Can I View Information About Pools?

This section describes how to view information about pools, such as:

  • Flags
  • Size
  • Number of placement groups
The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/pool'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/pool'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/pool', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/pool', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/pool
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user name and password when prompted.

1.5.1.11. How Can I View Information About a Particular Pool?

This section describes how to view information about a particular pool, such as:

  • Flags
  • Size
  • Number of placement groups
The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/pool/ID'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the pool listed in the pool field

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/pool/ID'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/pool/ID', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the pool listed in the pool field
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/pool/ID', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/pool/ID
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the pool listed in the pool field

Enter the user name and password when prompted.

1.5.1.12. How Can I View Information About Hosts?

This section describes how to view information about hosts, such as:

  • Host names
  • Ceph daemons and their IDs
  • Ceph version
The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/host'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/host'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/host', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/host', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/host
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user name and password when prompted.

1.5.1.13. How Can I View Information About a Particular Host?

This section describes how to view information about a particular host, such as:

  • Host names
  • Ceph daemons and their IDs
  • Ceph version
The curl Command

On the command line, use: 

curl --silent --user USER 'https://CEPH_MANAGER:8080/api/host/HOST_NAME'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • HOST_NAME with the host name of the host listed in the hostname field

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/host/HOST_NAME'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/host/HOST_NAME', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • HOST_NAME with the host name of the host listed in the hostname field
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.get('https://CEPH_MANAGER:8080/api/host/HOST_NAME', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard
Web Browser

In the web browser, enter: 

https://CEPH_MANAGER:8080/api/host/HOST_NAME
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • HOST_NAME with the host name of the host listed in the hostname field

Enter the user name and password when prompted.

1.5.2. Changing Configuration

This section describes how to use the Ceph API to change OSD configuration options, the state of an OSD, and information about pools:

1.5.2.1. How Can I Change OSD Configuration Options?

This section describes how to use the RESTful plug-in to change OSD configuration options.

The curl Command

On the command line, use: 

echo -En '{"OPTION": VALUE}' | curl --request PATCH --data @- --silent --user USER 'https://CEPH_MANAGER:8080/api/osd/flags'
Copy to clipboard

Replace:

  • OPTION with the option to modify; pause, noup, nodown, noout, noin, nobackfill, norecover, noscrub, nodeep-scrub
  • VALUE with true or false
  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

echo -En '{"OPTION": VALUE}' | curl --request PATCH --data @- --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/osd/flags'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.patch('https://CEPH_MANAGER:8080/api/osd/flags', json={"OPTION": VALUE}, auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • OPTION with the option to modify; pause, noup, nodown, noout, noin, nobackfill, norecover, noscrub, nodeep-scrub
  • VALUE with True or False
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.patch('https://CEPH_MANAGER:8080/api/osd/flags', json={"OPTION": VALUE}, auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard

1.5.2.2. How Can I Change the OSD State?

This section describes how to use the RESTful plug-in to change the state of an OSD.

The curl Command

On the command line, use: 

echo -En '{"STATE": VALUE}' | curl --request PATCH --data @- --silent --user USER 'https://CEPH_MANAGER:8080/api/osd/ID'
Copy to clipboard

Replace:

  • STATE with the state to change (in or up)
  • VALUE with true or false
  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

echo -En '{"STATE": VALUE}' | curl --request PATCH --data @- --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/osd/ID'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.patch('https://CEPH_MANAGER:8080/api/osd/ID', json={"STATE": VALUE}, auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field
  • STATE with the state to change (in or up)
  • VALUE with True or False
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.patch('https://CEPH_MANAGER:8080/api/osd/ID', json={"STATE": VALUE}, auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard

1.5.2.3. How Can I Reweight an OSD?

This section describes how to change the weight of an OSD.

The curl Command

On the command line, use: 

echo -En '{"reweight": VALUE}' | curl --request PATCH --data @- --silent --user USER 'https://CEPH_MANAGER:8080/api/osd/ID'
Copy to clipboard

Replace:

  • VALUE with the new weight
  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

echo -En '{"reweight": VALUE}' | curl --request PATCH --data @- --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/osd/ID'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.patch('https://CEPH_MANAGER:8080/osd/ID', json={"reweight": VALUE}, auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field
  • VALUE with the new weight
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.patch('https://CEPH_MANAGER:8080/api/osd/ID', json={"reweight": VALUE}, auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard

1.5.2.4. How Can I Change Information for a Pool?

This section describes how to use the RESTful plug-in to change information for a particular pool.

The curl Command

On the command line, use: 

echo -En '{"OPTION": VALUE}' | curl --request PATCH --data @- --silent --user USER 'https://CEPH_MANAGER:8080/api/pool/ID'
Copy to clipboard

Replace:

  • OPTION with the option to modify
  • VALUE with the new value of the option
  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the pool listed in the pool field

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

echo -En '{"OPTION": VALUE}' | curl --request PATCH --data @- --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/pool/ID'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.patch('https://CEPH_MANAGER:8080/api/pool/ID', json={"OPTION": VALUE}, auth=("USER, "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the pool listed in the pool field
  • OPTION with the option to modify
  • VALUE with the new value of the option
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.patch('https://CEPH_MANAGER:8080/api/pool/ID', json={"OPTION": VALUE}, auth=("USER, "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard

1.5.3. Administering the Cluster

This section describes how to use the Ceph API to initialize scrubbing or deep scrubbing on an OSD, create a pool or remove data from a pool, remove requests, or create a request:

1.5.3.1. How Can I Run a Scheduled Process on an OSD?

This section describes how to use the RESTful API to run scheduled processes, such as scrubbing or deep scrubbing, on an OSD.

The curl Command

On the command line, use: 

echo -En '{"command": "COMMAND"}' | curl --request POST --data @- --silent --user USER 'https://CEPH_MANAGER:8080/api/osd/ID/command'
Copy to clipboard

Replace:

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

echo -En '{"command": "COMMAND"}' | curl --request POST --data @- --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/osd/ID/command'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.post('https://CEPH_MANAGER:8080/api/osd/ID/command', json={"command": "COMMAND"}, auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the OSD listed in the osd field
  • COMMAND with the process (scrub, deep-scrub, or repair) you want to start. Verify it the process is supported on the OSD. See Section 1.5.1.9, “How Can I Determine What Processes Can Be Scheduled on an OSD?” for details.
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.post('https://CEPH_MANAGER:8080/api/osd/ID/command', json={"command": "COMMAND"}, auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard

1.5.3.2. How Can I Create a New Pool?

This section describes how to use the RESTful plug-in to create a new pool.

The curl Command

On the command line, use: 

echo -En '{"name": "NAME", "pg_num": NUMBER}' | curl --request POST --data @- --silent --user USER 'https://CEPH_MANAGER:8080/api/pool'
Copy to clipboard

Replace:

  • NAME with the name of the new pool
  • NUMBER with the number of the placement groups
  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

echo -En '{"name": "NAME", "pg_num": NUMBER}' | curl --request POST --data @- --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/pool'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.post('https://CEPH_MANAGER:8080/api/pool', json={"name": "NAME", "pg_num": NUMBER}, auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • NAME with the name of the new pool
  • NUMBER with the number of the placement groups
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.post('https://CEPH_MANAGER:8080/api/pool', json={"name": "NAME", "pg_num": NUMBER}, auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard

1.5.3.3. How Can I Remove Pools?

This section describes how to use the RESTful plug-in to remove a pool.

This request is by default forbidden. To allow it, add the following parameter to the Ceph configuration guide. 

mon_allow_pool_delete = true
Copy to clipboard
The curl Command

On the command line, use: 

curl --request DELETE --silent --user USER 'https://CEPH_MANAGER:8080/api/pool/ID'
Copy to clipboard

Replace:

  • USER with the user name
  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the pool listed in the pool field

Enter the user’s password when prompted.

If you used a self-signed certificate, use the --insecure option: 

curl --request DELETE --silent --insecure --user USER 'https://CEPH_MANAGER:8080/api/pool/ID'
Copy to clipboard
Python

In the Python interpreter, enter: 

$ python
>> import requests
>> result = requests.delete('https://CEPH_MANAGER:8080/api/pool/ID', auth=("USER", "PASSWORD"))
>> print result.json()
Copy to clipboard

Replace:

  • CEPH_MANAGER with the IP address or short host name of the node with the active ceph-mgr instance
  • ID with the ID of the pool listed in the pool field
  • USER with the user name
  • PASSWORD with the user’s password

If you used a self-signed certificate, use the verify=False option: 

$ python
>> import requests
>> result = requests.delete('https://CEPH_MANAGER:8080/api/pool/ID', auth=("USER", "PASSWORD"), verify=False)
>> print result.json()
Copy to clipboard

1.6. Additional Resources

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat, Inc.