It is possible to enhance Zabbix frontend functionality by adding third-party modules or by developing your own modules without the need to change the source code of Zabbix.
Note that the module code will run with the same privileges as Zabbix source code. This means:
Please always read the installation manual for a particular module. It is recommended to install new modules one by one to catch failures easily.
Just before you install a module:
Steps to install a module:
modules
folder of the Zabbix frontendTroubleshooting:
Problem | Solution |
---|---|
Module did not appear in the list | Make sure that the manifest.json file exists in modules/your-module/ folder of the Zabbix frontend. If it does that means the module does not suit the current Zabbix version. If manifest.json file does not exist, you have probably unpacked in the wrong directory. |
Frontend crashed | The module code is not compatible with the current Zabbix version or server configuration. Please delete module files and reload the frontend. You'll see a notice that some modules are absent. Go to Module administration and click Scan directory again to remove non-existent modules from the database. |
Error message about identical namespace, ID or actions appears | New module tried to register a namespace, ID or actions which are already registered by other enabled modules. Disable the conflicting module (mentioned in error message) prior to enabling the new one. |
Technical error messages appear | Report errors to the developer of the module. |
Modules are written in PHP language. Model-view-controller (MVC) software pattern design is preferred, as it is also used in Zabbix frontend and will ease the development. PHP strict typing is also welcome but not mandatory.
Please note that with modules you can easily add new menu items and respective views and actions to Zabbix frontend. Currently it is not possible to register new API or create new database tables through modules.
Each module is a directory (placed within the modules
directory) with sub-directories containing controllers, views and any other code:
example_module_directory/ (required)
manifest.json (required) Metadata and action definition.
Module.php Module initialization and event handling.
actions/ Action controller files.
SomethingView.php
SomethingCreate.php
SomethingDelete.php
data_export/
ExportAsXml.php
ExportAsExcel.php
views/ View files.
example.something.view.php
example.something.delete.php
js/ JavaScript files used in views.
example.something.view.js.php
partials/ View partial files.
example.something.reusable.php
js/ JavaScript files used in partials.
example.something.reusable.js.php
As you can see, the only mandatory file within the custom module directory is manifest.json
. The module will not register without this file. Module.php
is responsible for registering menu items and processing events such as 'onBeforeAction' and 'onTerminate'. The actions, views and partials directories contain PHP and JavaScript code needed for module actions.
Before you create a module, it is important to agree on the naming convention for different module items such as directories and files so that we could keep things well organized. You can also find examples above, in the Module structure section.
Item | Naming rules | Example |
---|---|---|
Module directory | Lowercase [a-z], underscore and decimal digits | example_v2 |
Action subdirectories | Lowercase [a-z] and underscore character | data_export |
Action files | CamelCase, ending with action type | SomethingView.php |
View and partial files | Lowercase [a-z] Words separated with dot Prefixed by module. followed by module nameEnding with action type and .php file extension |
module.example.something.view.php |
Javascript files | The same rules apply as for view and partial files, except the .js.php file extension. | module.example.something.view.js.php |
Note that the 'module' prefix and name inclusion is mandatory for view and partial file names, unless you need to override Zabbix core views or partials. This rule, however, does not apply to action file names.
Each module is expected to have a manifest.json file with the following fields in JSON format:
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
manifest_version | Yes | Double | - | Manifest version of the module. Currently supported version is 1. |
id | Yes | String | - | Module ID. Only one module with given ID can be enabled at the same time. |
name | Yes | String | - | Module name as displayed in the Administration section. |
version | Yes | String | - | Module version as displayed in the Administration section. |
namespace | Yes | String | - | PHP namespace for Module.php and action classes. |
author | No | String | "" | Module author as displayed in the Administration section. |
url | No | String | "" | Module URL as displayed in the Administration section. |
description | No | String | "" | Module description as displayed in the Administration section. |
actions | No | Object | {} | Actions to register with this module. See Actions. |
config | No | Object | {} | Module configuration. |
For reference, please see an example of manifest.json in the Reference section.
The module will have control over frontend actions defined within the actions object in the manifest.json file. This way new actions are defined. In the same way you may redefine existing actions. Each key of actions should represent the action name and the corresponding value should contain class
and optionally layout
and view
keys.
One action is defined by four counterparts: name, controller, view and layout. Data validation and preparation is typically done in the controller, output formatting is done in the view or partials, and the layout is responsible for decorating the page with elements such as menu, header, footer and others.
Module actions must be defined in the manifest.json file as actions object:
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
key | Yes | String | - | Action name, in lowercase [a-z], separating words with dot. |
class | Yes | String | - | Action class name, including subdirectory path (if used) within the actions directory. |
layout | No | String | "layout.htmlpage" | Action layout. |
view | No | String | null | Action view. |
There are several predefined layouts, like layout.json
or layout.xml
. These are intended for actions which produce different result than an HTML. You may explore predefined layouts in the app/views/ directory or even create your own.
Sometimes it is necessary to only redefine the view part of some action leaving the controller intact. In such case just place the necessary view and/or partial files inside the views
directory of the module.
For reference, please see an example action controller file in the Reference section. Please do not hesitate to explore current actions of Zabbix source code, located in the app/ directory.
Module.php
This optional PHP file is responsible for module initialization as well as event handling. Class 'Module' is expected to be defined in this file, extending base class \Core\CModule
. The Module class must be defined within the namespace specified in the manifest.json file.
<?php
namespace Modules\Example;
use Core\CModule as BaseModule;
class Module extends BaseModule {
...
}
For reference, please see an example of Module.php in the Reference section.
This section contains basic versions of different module elements introduced in the previous sections.
manifest.json
{
"manifest_version": 1.0,
"id": "example_module",
"name": "Example module",
"version": "1.0",
"namespace": "Example",
"author": "John Smith",
"url": "http://module.example.com",
"description": "Short description of the module.",
"actions": {
"example.something.view": {
"class": "SomethingView",
"view": "module.example.something.view"
},
"example.something.create": {
"class": "SomethingCreate",
"layout": null
},
"example.something.delete": {
"class": "SomethingDelete",
"layout": null
},
"example.something.export.xml": {
"class": "data_export/ExportAsXml",
"layout": null
},
"example.something.export.excel": {
"class": "data_export/ExportAsExcel",
"layout": null
}
},
"config": {
"username": "john_smith"
}
}
Module.php
<?php declare(strict_types = 1);
namespace Modules\Example;
use APP;
use CController as CAction;
/**
* Please see Core\CModule class for additional reference.
*/
class Module extends \Core\CModule {
/**
* Initialize module.
*/
public function init(): void {
// Initialize main menu (CMenu class instance).
APP::Component()->get('menu.main')
->findOrAdd(_('Reports'))
->getSubmenu()
->add((new \CMenuItem(_('Example wide report')))
->setAction('example.report.wide.php')
)
->add((new \CMenuItem(_('Example narrow report')))
->setAction('example.report.narrow.php')
);
}
/**
* Event handler, triggered before executing the action.
*
* @param CAction $action Action instance responsible for current request.
*/
public function onBeforeAction(CAction $action): void {
}
/**
* Event handler, triggered on application exit.
*
* @param CAction $action Action instance responsible for current request.
*/
public function onTerminate(CAction $action): void {
}
}
Action controller
<?php declare(strict_types = 1);
namespace Modules\Example\Actions;
use CControllerResponseData;
use CControllerResponseFatal;
use CController as CAction;
/**
* Example module action.
*/
class SomethingView extends CAction {
/**
* Initialize action. Method called by Zabbix core.
*
* @return void
*/
public function init(): void {
/**
* Disable SID (Session ID) validation. Session ID validation should only be used for actions which involve data
* modification, such as update or delete actions. In such case Session ID must be presented in the URL, so that
* the URL would expire as soon as the session expired.
*/
$this->disableSIDvalidation();
}
/**
* Check and sanitize user input parameters. Method called by Zabbix core. Execution stops if false is returned.
*
* @return bool true on success, false on error.
*/
protected function checkInput(): bool {
$fields = [
'name' => 'required|string',
'email' => 'required|string',
'phone' => 'string'
];
// Only validated data will further be available using $this->hasInput() and $this->getInput().
$ret = $this->validateInput($fields);
if (!$ret) {
$this->setResponse(new CControllerResponseFatal());
}
return $ret;
}
/**
* Check if the user has permission to execute this action. Method called by Zabbix core.
* Execution stops if false is returned.
*
* @return bool
*/
protected function checkPermissions(): bool {
$permit_user_types = [USER_TYPE_ZABBIX_ADMIN, USER_TYPE_SUPER_ADMIN];
return in_array($this->getUserType(), $permit_user_types);
}
/**
* Prepare the response object for the view. Method called by Zabbix core.
*
* @return void
*/
protected function doAction(): void {
$contacts = $this->getInput('email');
if ($this->hasInput('phone')) {
$contacts .= ', '.$this->getInput('phone');
}
$data = [
'name' => $this->getInput('name'),
'contacts' => $contacts
];
$response = new CControllerResponseData($data);
$this->setResponse($response);
}
}
Action view
<?php declare(strict_types = 1);
/**
* @var CView $this
*/
$this->includeJsFile('example.something.view.js.php');
(new CWidget())
->setTitle(_('Something view'))
->addItem(new CDiv($data['name']))
->addItem(new CPartial('module.example.something.reusable', [
'contacts' => $data['contacts']
])
->show();