Discussion thread for official Zabbix Template Ceph

[iwik.sk]

I was searching how to monitor ceph in proxmox and found two ways.
First is zabbix module in ceph, seems to be working, but in documentation it is marked as deprecated.
Other option is zabbix-agent2 working using rest module and this template - but this is no win either - rest module in ceph is also deprecated - and it is not mentioned here in thread!

https://tracker.ceph.com/issues/68803#note-5

https://github.com/ceph/ceph/commit/96ec7badb8534b812bbcae20eb411304900c0d0c

https://support.zabbix.com/si/jira.issueviews:issue-html/ZBXNEXT-9402/ZBXNEXT-9402.html

[tompaah]

I have the exact same problem as this post from 2024

https://www.zabbix.com/forum/zabbix-help/495011-ceph-by-zabbix-agent-2-empty-result

All checks done by zabbix_get or the Zabbix server return

ZBX_NOTSUPPORTED: Empty result

except ceph.ping that returns

0

.

There really isn't much help in the zabbix_agent2.log, this is about what it says at loglevel=5

2026/01/21 15:12:13.710861 received passive check request from "{\"request\":\"passive checks\",\"data\":[{\"key\":\"ceph.ping[https://cephdash.mydomain:443,user,pass\",\"timeout\":30}]}": "10.0.0.210"
2026/01/21 15:12:13.710946 [1] adding new request for key: 'ceph.ping[https://cephdash.mydomain:443,user,pass]'
2026/01/21 15:12:13.710956 [1] created direct exporter task for plugin 'Ceph' itemid:0 key 'ceph.ping[https://cephdash.mydomain:443,user,pass]'
2026/01/21 15:12:13.711000 executing direct exporter task for key 'ceph.ping[https://cephdash.mydomain:443,user,pass]'
2026/01/21 15:12:13.719131 executed direct exporter task for key 'ceph.ping[[https://cephdash.mydomain:443 user pass]'

The /etc/zabbix/zabbix_agent2.d/plugins.d/ceph.conf contains

Plugins.Ceph.InsecureSkipVerify=true
Plugins.Ceph.KeepAlive=300
Plugins.Ceph.Timeout=30

I have verified that the Ceph API works by using a REST client (Insomnia) directly to it, using the same URI and authentication I try with Zabbix.
It is able to authenticate and pull data successfully with the REST client.

Requests to the Ceph API go through a proxy server so I can see what requests the Zabbix Ceph module is trying to do. Here's what it sends

10.0.0.210 - user [22/Jan/2026:17:03:33 +0100] "POST /request?wait=1 HTTP/1.1" 404 137 "-" "zbx_monitor"

Note that the request is to an URL "/request?wait=1", this is not a valid URL at the Ceph API.
Correct requests should be done to the "/api" endpoint, like what the log says when I'm authenticating and listing cephfs instances with Insomnia

192.168.1.22 - - [22/Jan/2026:17:07:10 +0100] "POST /api/auth HTTP/1.1" 201 1351 "-" "insomnia/12.2.0"
192.168.1.22 - - [22/Jan/2026:17:07:04 +0100] "GET /api/cephfs HTTP/1.1" 200 2356 "-" "insomnia/12.2.0"

Using Ceph 20.2.0 and Zabbix 7.4.6.

EDIT:
Okay so I finally found the problem, it's the incompatibility with Zabbix Agent2 and current versions of Ceph, where Ceph removed a function that was long announced to be deprecated. There is no solution to this except to wait for a new release (8) of the Agent2.

https://support.zabbix.com/si/jira.issueviews:issue-html/ZBXNEXT-9402/ZBXNEXT-9402.html

[tompaah]

Anyone from Zabbix staff that can update the integration page to include information that this does not work on Ceph 20?
I spent nearly 2 days trying to get this to work in a corporate environment before finding out from a post in a Proxmox forum what the issue is (we're not even running Proxmox).

https://www.zabbix.com/integrations/ceph

[tompaah]

Updated the zabbix-agent2 to version 8.0.0alpha1, installed apt install zabbix-agent2-plugin-ceph, also version 8.0.0-alpha1
Configured zabbix-agent2 to load the plugin and configured the plugin itself with

Plugins.Ceph.InsecureSkipVerify=true
Plugins.Ceph.Sessions.Prod.Mode=native
​Plugins.Ceph.Sessions.Prod.ApiKey=pass
Plugins.Ceph.Sessions.Prod.User=user
Plugins.Ceph.Sessions.Prod.Uri=https://cephdash.mydomain:443

Still it appears to have trouble connecting. The zabbix-agent2.log says, on loglevel=5

2026/01/23 09:40:08.012696 received passive check request from "{\"request\":\"passive checks\",\"data\":[{\"key\":\"ceph.ping[Prod]\",\"timeout\":30}]}": "10.0.0.210"
2026/01/23 09:40:08.012758 [1] processing update request (1 requests)
2026/01/23 09:40:08.012773 [1] adding new request for key: 'ceph.ping[Prod]'
2026/01/23 09:40:08.012782 [1] created direct exporter task for plugin 'Ceph' itemid:0 key 'ceph.ping[Prod]'
2026/01/23 09:40:08.012816 executing direct exporter task for key 'ceph.ping[Prod]'
2026/01/23 09:40:08.013077 [Ceph] plugin Ceph executed Export Request request
2026/01/23 09:40:08.013100 [Ceph] plugin Ceph executing Export Request request
2026/01/23 09:40:08.019908 [Ceph] plugin Ceph export request completed
2026/01/23 09:40:08.020037 failed to execute direct exporter task for key 'ceph.ping[[Prod]]' error: 'Failed to get connection: cannot get connection: cannot create connection cephdash.mydomain:443: failed to connect: rados: ret=-22, Invalid argument.'

Tried running the plugin standalone but I have no clue how to get it to use Native mode, it apparently defaults to restful mode that doesn't work anyway. There probably is an undocumented parameter to get it to load the config file.

# /usr/libexec/zabbix/zabbix-agent2-plugin-ceph -v -t ceph.ping["https://cephdash.mydomain:443","user","pass"]
2026/01/23 10:02:20.823284 Response = {Failed:[] Finished:[] HasFailed:false Message:}
0

From the same machine that is running the zabbix-agent2 I can successfully get cURL to contact the Ceph API. In this case I didn't attempt authorization, just checking that the connection is allowed and correct response is returned. This indicates that the connection works, even the certificate is okay since I don't use the -k option.

# curl https://cephdash.mydomain:443/api/cephfs
{"status": "401 Unauthorized", "detail": "You are not authorized to access that resource", "request_id": "3281e294-bc97-4299-9cc3-cf...​​

[tompaah]

Finally got Zabbix 7.4 with the Ceph By Zabbix Agent 2-integration and Ceph 20.2.0 (tentacle) working.

The topic is very confusing topic because

1. Ceph is in a transition period with it’s APIs and
2. Zabbix hasn’t caught up to this yet and finally
3. documentation is poor and confusing

Lets begin with the foundations.
There are three methods of interacting with Ceph

1. RESTful API. This is the old Ceph API, accessible over http, that the Zabbix integration used, but this API is also deprecated since Ceph 20.2.0 (tentacle) and no longer available. Zabbix calls this method “restful” in its documentation and configuration.
   If you see reference calls, it's good to know endpoints begin with /request, /mon, /pool and more.
   Documentation at: https://docs.ceph.com/en/squid/mgr/restful/
   -
2. ceph_api. This is the new Ceph API available since Ceph 16.2.0 (pacific), accessible over http. It is OpenAPI v3-compliant and a part of Ceph Dashboard.
   Ceph By Zabbix Agent 2 does not support this at all.
   If you see reference calls, it's good to know all endpoints begin with /api
   Documentation at: https://docs.ceph.com/en/latest/mgr/ceph_api/
   -
3. msgr2 protocol. This is a proprietary protocol not accessible with http and thus is not routable through layer 7 routing, which is a very limiting factor. This protocol is what Ceph By Zabbix Agent 2 support from version 8.0.0-alpha1 and forward. It is also the only method Ceph By Zabbix Agent 2 can interact with Ceph from version 20.2.0 (tentacle) and forward. Zabbix calls this method “native” in its documentation and configuration.
   Documentation at: https://docs.ceph.com/en/latest/dev/msgr2/

From these options we can see that method 3, msgr2 / “native”, is the only working method if your Ceph cluster is of version 20.2.0 (tentacle) or newer.

How to configure msgr2 / “native”.

1. Upgrade Zabbix Agent 2 to 8.0.0-alpha1
   On the host where you wish to run the check you need to install Zabbix Agent 2 version 8.0.0-alpha1 or newer. This can be any host as long as the host has network access to the Ceph cluster.
   The installation will not be covered in detail in this post but for Debian based systems this is a matter of adding the repo, updating and installing, example:
   

   wget https://repo.zabbix.com/zabbix/8.0/release/ubuntu/pool/main/z/zabbix-release/zabbix-release_latest_8.0+ubuntu24.04_all.deb
   	dpkg -i zabbix-release_latest_8.0+ubuntu24.04_all.deb
   	apt update
   	apt install zabbix-agent2

   -
2. Install Ceph plugin on Zabbix Agent 2
   Again, for Debian-based do install the plugin with
   

   apt install zabbix-agent2-plugin-ceph

   -
3. Configure ceph.conf for Zabbix Agent 2
   Warning for confusion: When Zabbix documentation talks about "ceph.conf" it means the /etc/zabbix/zabbix_agent2.d/plugins.d/ceph.conf, NOT the /etc/ceph/ceph.conf
   This file needs at minimum have the configuration for the plugins path:
   

   Plugins.Ceph.System.Path=/usr/libexec/zabbix/zabbix-agent2-plugin-ceph

   All else is optional an is not needed now.
   Restart the Agent 2.
   -
4. Create user in Ceph for Zabbix monitoring
   Warning for confusion: There are multiple user access controls in Ceph. You cannot use a dashboard user, you cannot use a old restful user. You need to create this user with the ceph auth command. Example
   

   ceph auth add client.zabbix mon 'allow r'
   	ceph auth get-or-create-key client.zabbix mon 'allow r'

   The first line creates a user, the second outputs the users key which will be needed in the next step.
   -
5. Create host, link template and configure host
   Create a new host in Zabbix (or use one you already have).
   Add an Agent interface to the host that points to the host that has the Zabbix Agent 2 from steps 1-3.
   Link the template Ceph by Zabbix Agent 2
   Go to macros and from Inherited and host macros choose these and set them
   

   {$CEPH.API.KEY} = <the key from step 4>
   	{$CEPH.CONNSTRING} = <IP and port to your Ceph host that runs msgr2>
   	{$CEPH.USER} = <username from step 4, in this case zabbix (not client.zabbix, but only zabbix)>

   Example
   

   {$CEPH.API.KEY} = AUDwipRp7+CJCBABIPQlYTrJTgoPblhbN5DPTw==
   	{$CEPH.CONNSTRING} = 192.168.1.100:3300
   	{$CEPH.USER} = zabbix

   Save the host and it should work, it did for me.

Still having problems with discovery but all the base items works fine, that means it has connection.