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 Typeresponse 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.
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-mgrdaemon active. -
If you use a firewall, ensure that TCP port
8443, for SSL, and TCP port8080, without SSL, are open on the node with the activeceph-mgrdaemon.
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.
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
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
WarningMost 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
user1with theadministratorrole.Connect to the RESTful plug-in web page. Open a web browser and enter the following URL:
Syntax
https://HOST_NAME:8443Example
https://host01:8443
If you used a self-signed certificate, confirm a security exception.
Additional Resources
-
The
ceph dashboard --helpcommand. -
The
https://HOST_NAME:8443/docpage, where HOST_NAME is the IP address or name of the node with the runningceph-mgrinstance. - The Red Hat Enterprise Linux 8 Security Hardening guide.
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:
- Section 1.5.1.1, “How Can I View All Cluster Configuration Options?”
- Section 1.5.1.2, “How Can I View a Particular Cluster Configuration Option?”
- Section 1.5.1.3, “How Can I View All Configuration Options for OSDs?”
- Section 1.5.1.4, “How Can I View CRUSH Rules?”
- Section 1.5.1.5, “How Can I View Information about Monitors?”
- Section 1.5.1.6, “How Can I View Information About a Particular Monitor?”
- Section 1.5.1.7, “How Can I View Information about OSDs?”
- Section 1.5.1.8, “How Can I View Information about a Particular OSD?”
- Section 1.5.1.9, “How Can I Determine What Processes Can Be Scheduled on an OSD?”
- Section 1.5.1.10, “How Can I View Information About Pools?”
- Section 1.5.1.11, “How Can I View Information About a Particular Pool?”
- Section 1.5.1.12, “How Can I View Information About Hosts?”
- Section 1.5.1.13, “How Can I View Information About a Particular Host?”
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
CEPH_MANAGER_PORTwith 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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
USERwith the user name -
PASSWORDwith 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_confReplace:
-
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
Enter the user name and password when prompted.
Additional Resources
- The Configuration Guide for Red Hat Ceph Storage 5
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
ARGUMENTwith 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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
ARGUMENTwith the configuration option you want to view -
USERwith the user name -
PASSWORDwith 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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
ARGUMENTwith 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 5
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
USERwith the user name -
PASSWORDwith 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/flagsReplace:
-
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
Enter the user name and password when prompted.
Additional Resources
- The Configuration Guide for Red Hat Ceph Storage 5
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
USERwith the user name -
PASSWORDwith 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_ruleReplace:
-
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
USERwith the user name -
PASSWORDwith 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/monitorReplace:
-
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
NAMEwith 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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
NAMEwith the short host name of the Monitor -
USERwith the user name -
PASSWORDwith 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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
NAMEwith 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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
USERwith the user name -
PASSWORDwith 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/osdReplace:
-
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield -
USERwith the user name -
PASSWORDwith 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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield -
USERwith the user name -
PASSWORDwith 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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
USERwith the user name -
PASSWORDwith 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/poolReplace:
-
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the pool listed in thepoolfield
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the pool listed in thepoolfield -
USERwith the user name -
PASSWORDwith 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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the pool listed in thepoolfield
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
USERwith the user name -
PASSWORDwith 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/hostReplace:
-
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
HOST_NAMEwith the host name of the host listed in thehostnamefield
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
HOST_NAMEwith the host name of the host listed in thehostnamefield -
USERwith the user name -
PASSWORDwith 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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
HOST_NAMEwith the host name of the host listed in thehostnamefield
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:
-
OPTIONwith the option to modify;pause,noup,nodown,noout,noin,nobackfill,norecover,noscrub,nodeep-scrub -
VALUEwithtrueorfalse -
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
OPTIONwith the option to modify;pause,noup,nodown,noout,noin,nobackfill,norecover,noscrub,nodeep-scrub -
VALUEwithTrueorFalse -
USERwith the user name -
PASSWORDwith 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:
-
STATEwith the state to change (inorup) -
VALUEwithtrueorfalse -
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield -
STATEwith the state to change (inorup) -
VALUEwithTrueorFalse -
USERwith the user name -
PASSWORDwith 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:
-
VALUEwith the new weight -
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield -
VALUEwith the new weight -
USERwith the user name -
PASSWORDwith 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:
-
OPTIONwith the option to modify -
VALUEwith the new value of the option -
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the pool listed in thepoolfield
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the pool listed in thepoolfield -
OPTIONwith the option to modify -
VALUEwith the new value of the option -
USERwith the user name -
PASSWORDwith 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:
-
COMMANDwith the process (scrub,deep-scrub, orrepair) 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. -
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the OSD listed in theosdfield -
COMMANDwith the process (scrub,deep-scrub, orrepair) 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. -
USERwith the user name -
PASSWORDwith 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:
-
NAMEwith the name of the new pool -
NUMBERwith the number of the placement groups -
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
NAMEwith the name of the new pool -
NUMBERwith the number of the placement groups -
USERwith the user name -
PASSWORDwith 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:
-
USERwith the user name -
CEPH_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the pool listed in thepoolfield
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_MANAGERwith the IP address or short host name of the node with the activeceph-mgrinstance -
IDwith the ID of the pool listed in thepoolfield -
USERwith the user name -
PASSWORDwith 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
- See Appendix A, The Ceph RESTful API specifications for specific details on the API.
- See the Testing the API Python script on GitHub.