20. Módulos

Visão geral

É possível aprimorar a funcionalidade do frontend do Zabbix adicionando módulos de terceiros ou desenvolvendo seus próprios módulos, sem a necessidade de alterar o código-fonte do Zabbix.

Observe que o código do módulo será executado com os mesmos privilégios do código-fonte do Zabbix. Isso significa que:

  • módulos de terceiros podem ser prejudiciais. Você deve confiar nos módulos que está instalando;
  • Erros no código de um módulo de terceiros podem travar o frontend. Se isso acontecer, basta remover o código do módulo do frontend. Assim que você recarregar o frontend do Zabbix, verá uma mensagem informando que alguns módulos estão ausentes. Vá para Module administration (em AdministraçãoGeralMódulos) e clique em Scan directory novamente para remover módulos inexistentes do banco de dados.

Instalação

Leia sempre o manual de instalação de um módulo específico. Recomenda-se instalar novos módulos um por vez para identificar falhas facilmente.

Antes de instalar um módulo:

  • Certifique-se de que baixou o módulo de uma fonte confiável. A instalação de código prejudicial pode levar a consequências, como perda de dados.
  • Diferentes versões do mesmo módulo (com o mesmo ID) podem ser instaladas em paralelo, mas apenas uma versão pode ser ativada por vez.

Passos para instalar um módulo:

  • Descompacte o módulo dentro de sua própria pasta na pasta modules do frontend do Zabbix
  • Certifique-se de que a pasta do módulo contenha pelo menos o arquivo manifest.json
  • Navegue até Module administration e clique no botão Scan directory
  • O novo módulo aparecerá na lista, juntamente com sua versão, autor, descrição e status
  • Ative o módulo clicando em seu status

Troubleshooting:

Problema Solução
O módulo não apareceu na lista Certifique-se de que o arquivo manifest.json exista na pasta modules/your-module/ do frontend do Zabbix. Se existir, significa que o módulo não é compatível com a versão atual do Zabbix. Se o arquivo manifest.json não existir, você provavelmente descompactou na pasta errada.
O frontend travou O código do módulo não é compatível com a versão atual do Zabbix ou a configuração do servidor. Exclua os arquivos do módulo e recarregue o frontend. Você verá um aviso de que alguns módulos estão ausentes. Vá para Module administration e clique em Scan directory novamente para remover módulos inexistentes do banco de dados.
Mensagem de erro sobre namespace, ID ou ações idênticas aparece O novo módulo tentou registrar um namespace, ID ou ações que já estão registrados por outros módulos ativados. Desative o módulo conflitante (mencionado na mensagem de erro) antes de ativar o novo.
Mensagens de erro técnico aparecem Relate os erros ao desenvolvedor do módulo.

Desenvolvendo módulos

Os módulos são escritos em linguagem PHP. Controlador de visualização de modelo (MVC) design de padrão de software é o preferido, pois também é usado no Zabbix frontend e facilitará o desenvolvimento. A tipagem estrita do PHP também é bem-vindo, mas não obrigatório.

Observe que com os módulos você pode adicionar facilmente novos itens de menu e respectivas visualizações e ações para o frontend do Zabbix. Atualmente não é possível registrar uma nova API ou criar novas tabelas de banco de dados através módulos.

Estrutura do módulo

Cada módulo é um diretório (colocado dentro do diretório modules) com subdiretórios contendo controllers, views e qualquer outro código:

example_module_directory/ (obrigatório)
           manifest.json (obrigatório) Metadados e definição de ação.
           Module.php Inicialização do módulo e manipulação de eventos.
           actions/Arquivos do controlador de ação.
               AlgoView.php
               AlgoCreate.php
               AlgoDelete.php
               data_export/
                   ExportAsXml.php
                   ExportAsExcel.php
           visualizações/Visualizar arquivos.
               exemplo.algo.view.php
               exemplo.algo.excluir.php
               js/ arquivos JavaScript usados ​​em views.
                   exemplo.algo.view.js.php
           parciais/ Visualizar arquivos parciais.
               exemplo.algo.reutilizável.php
               js/ arquivos JavaScript usados ​​em parciais.
                   exemplo.algo.reutilizável.js.php

Como você pode ver, o único arquivo obrigatório dentro do módulo personalizado diretório é manifest.json. O módulo não será registrado sem isso Arquivo. Module.php é responsável por registrar itens de menu e processamento de eventos como 'onBeforeAction' e 'onTerminate'. O Os diretórios actions, views e partials contêm PHP e JavaScript código necessário para ações do módulo.

Convenção de nomes

Antes de criar um módulo, é importante concordar com a nomenclatura convenção para diferentes itens de módulo, como diretórios e arquivos, que poderíamos manter as coisas bem organizadas. Você também pode encontrar exemplos acima, na seção Estrutura do módulo.

Item Regras de nomenclatura Exemplo
Diretório do módulo minúsculas [a-z], sublinhado e dígitos decimais exemplo_v2
Subdiretórios de ação minúsculas [a-z] e caractere de sublinhado dados_export
Arquivos de ação CamelCase, terminando com tipo de ação SomethingView.php
Visualização e arquivos parciais minúsculas [az]
Palavras separadas por ponto
Prefixado por module. seguido pelo nome do módulo
Terminando com tipo de ação e extensão de arquivo .php
module.example .algo.view.php
Arquivos Javascript As mesmas regras se aplicam aos arquivos de visualização e parciais, exceto a extensão de arquivo .js.php. module.example.something.view.js.php

Observe que o prefixo 'módulo' e a inclusão do nome são obrigatórios para visualização e nomes de arquivos parciais, a menos que você precise substituir as visualizações principais do Zabbix ou parciais. Essa regra, no entanto, não se aplica a nomes de arquivos de ação.

Preparação do manifesto

Cada módulo deve ter um arquivo manifest.jsoncom os seguintes campos no formato JSON:

Parâmetro Obrigatório Tipo Padrão Descrição
manifest_version Sim Double - Versão do manifesto do módulo. A versão atualmente suportada é 1.
id Sim String - ID do módulo. Apenas um módulo com o ID fornecido pode ser ativado ao mesmo tempo.
name Sim String - Nome do módulo conforme exibido na seção Administração.
version Sim String - Versão do módulo conforme exibido na seção Administração.
namespace Sim String - Namespace PHP para Module.php e classes de ação.
author Não String "" Autor do módulo conforme exibido na seção Administração.
url Não String "" URL do módulo conforme exibido na seção Administração.
description Não String "" Descrição do módulo conforme exibido na seção Administração.
actions Não Objeto {} Ações a serem registradas com este módulo. Veja Ações.
config Não Objeto {} Configuração do módulo.

Para referência, consulte um exemplo de manifest.json na seção Reference.

Ações

O módulo terá controle sobre as ações de frontend definidas no objeto actions no arquivo manifest.json. Dessa forma, novas ações podem ser definidas. Da mesma maneira, você pode redefinir ações existentes. Cada chave de actions deve representar o nome da ação, e o valor correspondente deve conter as chaves class e, opcionalmente, layout e view.

Uma ação é definida por quatro componentes: nome, controlador, visualização (view) e layout. A validação e preparação dos dados normalmente são feitas no controlador, o formato da saída é feito na visualização ou parciais (partials), e o layout é responsável por decorar a página com elementos como menu, cabeçalho, rodapé e outros.

As ações do módulo devem ser definidas no arquivo manifest.json como um objeto actions:

Parâmetro Obrigatório Tipo Padrão Descrição
key Sim String - Nome da ação, em letras minúsculas [a-z], separando palavras com ponto.
class Sim String - Nome da classe da ação, incluindo o caminho do subdiretório (se usado) dentro do diretório actions.
layout Não String "layout.htmlpage" Layout da ação.
view Não String null Visualização da ação.

Existem vários layouts predefinidos, como layout.json ou layout.xml. Estes são destinados para ações que produzem um resultado diferente de HTML. Você pode explorar os layouts predefinidos no diretório app/views/ ou até criar os seus próprios.

Às vezes, é necessário redefinir apenas a parte da visualização de alguma ação, mantendo o controlador intacto. Nesse caso, basta colocar os arquivos de visualização e/ou parciais necessários dentro do diretório views do módulo.

Para referência, veja um exemplo de arquivo de controlador de ação na seção Reference. Não hesite em explorar as ações atuais do código-fonte do Zabbix, localizado no diretório app/.

Module.php

Esse arquivo PHP opcional é responsável pela inicialização do módulo, bem como pelo tratamento de eventos. A classe 'Module' deve ser definida nesse arquivo, estendendo a classe base \Core\CModule. A classe Module deve ser definida dentro do namespace especificado no arquivo manifest.json.

<?php
       
       namespace Modules\Example;
       use Core\CModule as BaseModule;
       
       class Module extends BaseModule {
           ...
       }

Para referência, veja um exemplo de Module.php na seção Reference.

Referência

Esta seção contém versões básicas de diferentes elementos do módulo introduzido nas seções anteriores.

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"
           }
       }

Módulo.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 {
           }
       }

Controlador de ação

<?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);
           }
       }

Visualização de ação

<?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();