The "Unsupported key" error in Zabbix occurs when the Zabbix Agent cannot execute a custom script defined in an external check because the script is missing executable permissions, has incorrect ownership, or fails due to environment variable mismatches. To resolve this, ensure your script is owned by the
zabbix user, marked as executable, and includes the correct shebang line, while verifying that all dependencies like Python or MySQL clients are accessible in the agent's execution context.
Verifying Script Permissions and Ownership
The most common cause for this error is that the Zabbix Agent process does not have permission to read or execute the script file. By default, the Zabbix Agent runs under the
zabbix system user. If the script is owned by
root or another user and lacks world-executable permissions, the agent will reject it with an unsupported key error.
First, locate the script file on your Ubuntu server. It is typically stored in a directory specified by the
ExternalScripts parameter in the
zabbix_agentd.conf configuration file. You must change the ownership of this script to the
zabbix user. Use the following command to apply the correct ownership:
sudo chown zabbix:zabbix /path/to/your/script.sh
Next, you must ensure the script has executable permissions. Even if the file is readable, it cannot run without the execute bit set. Apply the standard executable permission using
chmod:
sudo chmod 755 /path/to/your/script.sh
This sets the owner to read, write, and execute, while group and others can read and execute. This configuration is generally sufficient for Zabbix agents to invoke the script successfully. Always verify the changes by listing the file details with
ls -l to confirm the owner is
zabbix and the permissions start with
-rwx.
Checking Shebang Lines and Environment Variables
If permissions are correct but the error persists, the issue often lies within the script itself. The first line of any shell script must be a valid shebang that points to an existing interpreter. For Bash scripts, this should be
#!/bin/bash or
#!/usr/bin/env bash. If this line is missing or points to a non-existent path, the operating system cannot launch the script, causing Zabbix to report the key as unsupported.
For Python scripts, ensure the shebang points to the correct Python binary, such as
#!/usr/bin/python3. Additionally, Zabbix agents run in a restricted environment. They do not inherit the interactive shell profile (like
.bashrc or
.profile) where you might have exported custom paths or aliases. If your script relies on environment variables to find tools, you must either hardcode absolute paths or export those variables directly within the script before use.
When using MySQL commands, ensure that the
mysql client is installed and available in the standard PATH for the
zabbix user. You can test this by switching to the zabbix user and running the command manually:
su -s /bin/bash zabbix -c "which mysql"
If this returns a path, the client is accessible. If it returns nothing, you need to install the MySQL client package or provide the full absolute path to the binary in your script.
Configuring Zabbix Agent Settings
The Zabbix Agent configuration file controls which directories are allowed for external scripts. On Ubuntu, this file is usually located at
/etc/zabbix/zabbix_agentd.conf. You must verify that the
ExternalScripts directive points to the directory containing your script. If this parameter is commented out or points to a different location, the agent will ignore your script.
ExternalScripts=/usr/lib/zabbix/externalscripts
Ensure that the directory specified exists and is writable by the root user (for configuration updates) but readable/executable by the
zabbix user. After modifying the configuration file, you must restart the Zabbix Agent service for changes to take effect. On Ubuntu systems using systemd, use the following command:
sudo systemctl restart zabbix-agent
It is also crucial to check the agent log file for more detailed error messages. Logs are typically found at
/var/log/zabbix/zabbix_agentd.log. Look for entries related to "cannot execute" or "permission denied" to pinpoint the exact failure reason.
Testing the External Check Manually
Before relying on the Zabbix GUI, test the external check from the command line using the
zabbix_get utility. This tool simulates how the Zabbix Server retrieves data from the agent. Replace
<agent_ip> with the IP address of your monitored host and
<key> with the actual key defined in your template.
sudo zabbix_get -s <agent_ip> -k <key>
If this command returns the expected output, the agent is functioning correctly, and the issue likely lies in the Zabbix Server configuration or network connectivity. If it returns an error, the problem is local to the agent host. Ensure that the firewall allows traffic on port 10050 between the server and the agent.
Frequently Asked Questions
Why does my script work manually but fail in Zabbix?
Manual execution uses your current user's environment, including PATH and aliases. The Zabbix Agent runs as the
zabbix user with a minimal environment, so you must use absolute paths for all binaries and avoid relying on shell aliases or sourced profiles.
How do I find the correct path for ExternalScripts?
Check the
zabbix_agentd.conf file for the
ExternalScripts parameter. If it is undefined, the default path varies by distribution but is often
/usr/lib/zabbix/externalscripts on Ubuntu. Create this directory if it does not exist and assign proper permissions.
Can I use Python scripts for external checks?
Yes, you can use Python scripts provided they have a valid shebang line and executable permissions. Ensure the Python interpreter specified in the shebang is installed and accessible to the
zabbix user, and that all required Python modules are installed globally or in a virtual environment accessible to the agent.
What should I do if the Zabbix Agent log shows 'Permission denied'?
This indicates that the
zabbix user cannot read or execute the script. Run
chown zabbix:zabbix on the script file and
chmod 755 to grant execution rights. Also, verify that the parent directories leading to the script are traversable by the
zabbix user.
Does restarting the Zabbix Service clear the Unsupported Key error?
Restarting the service applies configuration changes like new keys or updated
ExternalScripts paths. However, it does not fix underlying issues like missing permissions or syntax errors in the script. Always resolve file-level issues before restarting the service to ensure immediate recovery.