Last Updated on December 30, 2024 by Thiago Crepaldi
From previous posts, we have deployed Zabbix Server on a Proxmox container. We also hardened the installation through Let’s Encrypt certificates for the web frontend and TLS encryption for the communication between Server and Agents/Proxies, after all, although encrypted Zabbix Server <-> Agent/Proxy communication with PSK or SSL certificates π
In this post I will cover how to monitor a Proxmox Virtual Environment (PVE) using Zabbix Agent template. Templates are great because they already pack a bunch of monitoring items, actions, triggers, etc that we would have to add one by one otherwise. Using template is smart because when we need to make changes, we just do it in the template and all hosts that use them will see the new settings. On a manual setup, you would have to make the change in each host, one by one…
This post assumes you already installed and configured your Zabbix Agent, but if you didn’t, refer to How to install and configure Zabbix agent and resume from here when you are done.
Configuring Proxmox VE
In order to allow the Zabbix Server to monitor Proxmox VE, we need to create an user, a Token ID and set some permissions to them.
After logging in to your Proxmox VE, navigate to Server View >> Datacenter followed by submenu Permissions >> User and click on Add
- User name: zabbix
- Realm: Linux PAM
- Group: empty
- Expire: never
- Enabled: checked
- First Name: be creative
- Last Name: keep creative
- E-mail: less creative, maybe an actual valid email for a possible notification
- Comment: be creative
- Key ID: leave empty
Click on Add to create the user. Next go to Permissions >> API Tokens and click on Add:
- User: Select the just created user
- Token ID: Identifier name without space and special characters (e.g. ZabbixMonitoring01)
- Privilege separation: checked
- Expire: never
- Comments: be creative
Create the Token by clicking Add. Once you do that, a dialog will be shown with Token ID and Secret. Take note of them because they won’t be shown again!
Lastly, let’s create some permissions binding the user and token created to actual resources on the Proxmox by clicking on Permissions submenu followed by Add >> API Token permission:
- Path: /
- API Token: Select the token just created
- Role: PVEAuditor
- Propagate: checked
Click on Add to complete, and create a new permission again:
- Path: /nodes/<your_proxmox_node>
- API Token: Select the token just created
- Role: PVEAuditor
- Propagate: checked
Click on Add to complete, and create a new permission again:
- Path: /vms
- API Token: Select the token just created
- Role: PVEAuditor
- Propagate: checked
Click on Add to complete.
Configuring Zabbix Server through Web UI
Go to Configuration >> Hosts and select your agent with Proxmox VE running. When the configuration dialog open, the Host tab should be the default one. Look for the Templates section. In the text box, type “Proxmox” and select the “Proxmox VE by HTTP” in the search result. This will link the template to your agent.
The last step is setting the Proxmox API token information in the plugin so that it can connect to the server and fetch metadata. Click on Macros tab. We will need to add 2 macros related to credentials. Click on Add and fill in the new row as follow:
- Macro: {$PVE.TOKEN.ID}
- Value: Type your Token ID
- Description: A helpful description or leave it empty
Click on Add again
- Macro: {$PVE.TOKEN.SECRET}
- Value: Type your Token password
- Description: A helpful description or leave it empty
That is it, let’s try it. Go to Monitoring >> Latest data. In the filter section, type the name of your Proxmox server in the Hosts box, Proxmox in the Name box and finally hit Apply. A list of items should be displayed for it, such as Proxmox: API service status, etc
That is it, have fun!
Maybe a bug or a change in behavior. Here my Promox 7.3-4 monitored by Zabbix 6.2.6 I needed to add the permissions not only to the token, but also for the user! Until adding the user also I always got a “403 Permission check failed (/, Sys.Audit)” even when trying to connect via postman
Thx for this, I had the same problem with proxmox 7.4.13 and zabbix 6.4.3.
How do you do this? I have this issue but don’t understand what it means to add permissions to the user.
You must look here: Lastly, letβs create some permissions binding the user and token created to actual resources on the Proxmox by clicking on Permissions submenu followed by Add >> User Permission, the same as API permissins above.
Excellent work and information! this site has been a huge help in getting ZABBIX monitoring for my home lab up and running.
Thanks a million!
Hi
Thanks for the support but follow all your steps i get the Unknown Error (520)
There is no post on internet to help about how to help with this issue =(
Thanks for your support
Hi
Please could you try to help me with this error Unknown Error (520)
There is no post or forum on internet that explain as you did but follow all your steps same result for this error
Can you paste the logs? It might be that you have low memory and need to change Zabbix configuration to decrease the amount of simultaneous tasks or maximum memory used
Hy
One Question, why do you use a pam user?
On a Cluster with multiple Node the pam have to be created on every node I think.
A pve User is replicated via Proxmox Usermanagement.
kr
Roland
I am still using a single server Proxmox, but you got a good point. I think βProxmox VE Authenticationβ should work too. If you try that route, let me know your findings and I can update the post with this possibility too. Thanks
One reason to use pam is the user is automatically created when the agent is installed, but its a service account that cant be logged into so its secure. No need in creating a full user account that can be logged into.
Why do you have to list each of the /nodes/pve[1-n] but can get away with /vms?
You must create new permissions where, path: / user: zabbix@pam, role ex PVEAuditor oraz Propagate: true.
I’m getting Unknown Error (520). I have done all of the steps above on a new user Linux and on root. Nothing changes. Went as far as to install ufw on zabbix server and allowed all the necessary ports. Let me know, what am I missing?
Thanks a million for this post. I would make a donation but I stopped using paypal a while back. There must be another payment system you could use.
Hello Matthew, I just added a “Buy me a coffee” button on the top right corner which accepts money using credit card through Stripe. Give it a try and thank you for your support π
Do you need to add the server details in SNMP portion when configuring the host? If so is it SNMP1/2/3 what is the community string? I’m getting the same error as above “Unknown Error 502”
I figured it out from some further searching. You need to add another MACRO : {$PVE.URL.HOST} and the IP address. This worked!!!
Thanks for this, its the actual IP address and not https://123.123.123.123, just 123.123.123.123.
If only this was made clearer since URL = https:// and IP == IP π Slight confusion in macro naming.
Hello everyone
I am using this guide, but with Proxmox 8.2.4 I get error 403 in the query api2/json/nodes/pve-01/statusβ.
I have tried with give full permission to the API, and even create the user in the Linux console, but still to that query is always 403.
403 ForbiddenThe client does not have the necessary permissions for certain content, so the server is refusing to give a proper response.
I don’t understand where the problem is
Thank you very much for your comments
Translated with DeepL.com (free version)
Hello
When Zabbix will report API service is not available when is need to be update settings in macro and add”: {$PVE.URL.HOST} and put ip address (without http or https) for proxomox.
Thank you for your article. This provided great value!
I had to add a port macro.
{$PVE.URL.PORT}
Also, the value for toket ID in zabbix was “username@pam!toketid”. I just put the token ID but didnt work.
lxc metric work but node metric no data, what was wrong.