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.

Prerequisites

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

1.1. 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.2. 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.3. 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

Log into the Cephadm shell:
Example
```
root@host01 ~]# cephadm shell
```

Enable the RESTful plug-in:

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

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.

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.

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

The ceph dashboard --help command.
The https://HOST_NAME:8443/doc page, where HOST_NAME is the IP address or name of the node with the running ceph-mgr instance.
For more information, see the Security Hardening guide within the Product Documentation for Red Hat Enterprise Linux for your OS version, on the Red Hat Customer Portal.

1.4. Questions and Answers

1.4.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.4.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

The Configuration Guide for Red Hat Ceph Storage 8

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

The Configuration Guide for Red Hat Ceph Storage 8

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

The Configuration Guide for Red Hat Ceph Storage 8

1.4.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 8.

1.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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:

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.4.1.9, “How Can I Determine What Processes Can Be Scheduled on an OSD?” for details.
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 '{"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.4.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.4.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.4.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()

Chapter 1. Ceph RESTful API

1.1. Versioning for the Ceph API

1.2. Authentication and authorization for the Ceph API

1.3. Enabling and Securing the Ceph API module

1.4. Questions and Answers

1.4.1. Getting information

1.4.1.1. How Can I View All Cluster Configuration Options?

The curl Command

Python

Web Browser

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

The curl Command

Python

Web Browser

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

The curl Command

Python

Web Browser

1.4.1.4. How Can I View CRUSH Rules?

The curl Command

Python

Web Browser

1.4.1.5. How Can I View Information about Monitors?

The curl Command

Python

Web Browser

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

The curl Command

Python

Web Browser

1.4.1.7. How Can I View Information about OSDs?

The curl Command

Python

Web Browser

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

The curl Command

Python

Web Browser

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

The curl Command

Python

Web Browser

1.4.1.10. How Can I View Information About Pools?

The curl Command

Python

Web Browser

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

The curl Command

Python

Web Browser

1.4.1.12. How Can I View Information About Hosts?

The curl Command

Python

Web Browser

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

The curl Command

Python

Web Browser

1.4.2. Changing Configuration

1.4.2.1. How Can I Change OSD Configuration Options?

The curl Command

Python

1.4.2.2. How Can I Change the OSD State?

The curl Command

Python

1.4.2.3. How Can I Reweight an OSD?

The curl Command

Python

1.4.2.4. How Can I Change Information for a Pool?

The curl Command

Python

1.4.3. Administering the Cluster

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

The curl Command

Python

1.4.3.2. How Can I Create a New Pool?

The curl Command

Python

1.4.3.3. How Can I Remove Pools?

The curl Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command

The `curl` Command