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

      Example

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

      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"}'

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

Syntax

curl -H "Authorization: Bearer TOKEN" ...

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

  2. Enable the RESTful plug-in:

    [ceph: root@host01 /]# ceph mgr module enable dashboard
  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

      Example

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

      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

    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
      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

    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

    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

    Example

    https://host01:8443

    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'

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'
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()

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/cluster_conf

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'

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'
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()

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/cluster_conf/ARGUMENT

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'

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'
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()

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/osd/flags

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'

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'
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()

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/crush_rule

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'

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'
Python

In the Python interpreter, enter:

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

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/monitor

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'

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'
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()

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/monitor/NAME

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'

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'
Python

In the Python interpreter, enter:

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

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/osd

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'

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'
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()

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/osd/ID

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'

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'
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()

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/osd/ID/command

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'

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'
Python

In the Python interpreter, enter:

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

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/pool

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'

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'
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()

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/pool/ID

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'

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'
Python

In the Python interpreter, enter:

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

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/host

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'

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'
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()

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()
Web Browser

In the web browser, enter:

https://CEPH_MANAGER:8080/api/host/HOST_NAME

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'

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'
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()

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()

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'

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'
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()

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()

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'

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'
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()

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()

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'

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'
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()

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()

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'

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'
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()

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()

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'

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'
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()

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()

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
The curl Command

On the command line, use:

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

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'
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()

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()

1.6. Additional Resources