Discovery permite cargar tanto plugins oficiales de Pandora FMS como personalizados.
Para cargar plugins personalizados es necesario generar un paquete .disco
con todo lo necesario para que tanto la consola como el servidor de Pandora FMS sean capaces de:
Un paquete .disco
es un fichero zip con la extensión .disco el cual contiene al menos un fichero llamado discovery_definition.ini.
Opcionalmente, un paquete .disco
podrá contener un fichero llamado logo.png el cual será el logo del plugin en la consola de Pandora FMS. Si no se añade un fichero para el logo, la consola automáticamente usa un logo por defecto.
Por último, típicamente, un fichero .disco
contendrá todos los scripts, ejecutables y librerías necesarios por el servidor y la consola. Aunque no es obligatorio sí es lo común y recomendado, para evitar requisitos adicionales de instalación en los sistemas donde se quieran configurar y ejecutar las tareas que usen el plugin.
Por lo tanto, y en resumen, un fichero .disco
contendrá:
discovery_definition.ini
.logo.png
(opcional).
El fichero discovery_definition.ini es el más importante dentro de un fichero .disco
, ya que es el que contiene toda la definición del plugin.
Contiene tanto los parámetros que se mostrarán por consola para rellenarse en un formulario de definición de una tarea, como las ejecuciones que tendrá que realizar el servidor de Pandora FMS para las tareas del plugin.
Con el objetivo de facilitar su definición y procesado en la consola, el formato usado en un fichero discovery_definition.ini
es el formato INI propio de PHP.
Un fichero discovery_definition.ini
se compone fundamentalmente de 3 bloques:
discovery_extension_definition
.config_steps
(opcional).tempfile_confs
(opcional).Durante las siguientes explicaciones será común usar algunos términos. En esta sección se explican dichos términos.
Una macro es una clave de texto única usada para almacenar información (valores, rutas a ficheros, …). Cuando una macro es usada (por ejemplo durante una ejecución) lo que se quiere es usar la información que contenga en su lugar.
Una macro valida es una clave de texto que comienza y termina con guiones bajos _
y que entre medias solo puede contener letras (A-Z y a-z) y números (0-9).
Cuando se hable de STRING nos referiremos a cadenas de texto alfanuméricas.
Cuando se hable de NUMBER nos referiremos exclusivamente a números.
Cuando se hable de BOOL nos referiremos a valores true / false, 1 / 0, yes / no.
Cuando se hable de VALUE nos referiremos a un valor cualquiera (STRING, NUMBER o BOOL). Normalmente se usará en listas separadas por comas para representar valores de un mismo tipo.
Cuando se usen las letras N o M en mayúsculas, nos referiremos a un número entero positivo. Normalmente se usará junto con otros elementos como VALUE para indicar que puede repetirse más de una vez (Por ejemplo, VALUE_N).
Gran parte de la configuración de las ejecuciones para el servidor se basa en el uso de macros. Principalmente, éstas serán definidas por el usuario, pero existen algunas concretas propias del servidor de Pandora FMS que pueden resultar útiles:
__taskMD5__
→ MD5 unico de la tarea, generado a partir del ID de la tarea y el nombre corto de la aplicación. Es útil para generar elementos únicos durante las ejecuciones (como por ejemplo ficheros).__taskInterval__
→ Intervalo de ejecución de la tarea (segundos).__taskGroup__
→ Grupo de la tarea (Texto).__taskGroupID__
→ Grupo de la tarea (ID).__temp__
→ Directorio temporal del servidor configurado en el pandora_server.conf
(temporal).__incomingDir__
→ Directorio de entrada del servidor de Pandora configurado en pandora_server.conf
(incomingdir).__consoleAPIURL__
→ API URL configurado en el pandora_server.conf
(console_api_url).__consoleAPIPass__
→ API pass configurada en el pandora_server.conf
(console_api_pass).__consoleUser__
→ Usuario de la consola configurado en el pandora_server.conf
(console_user).__consolePass__
→ Contraseña de la consola configurada en el pandora_server.conf
(console_pass).Estas macros en ningún caso son utilizadas por la consola de Pandora FMS.
Este bloque define la configuración principal del plugin y cuenta con los siguientes parámetros:
A-Z
y a-z
), números (0-9
), puntos (.
), guiones (-
) y guiones bajos (_
)..disco
) a scripts y ejecutables usados por el plugin.execution_file[_exec1_] = "script1.py" execution_file[_exec2_] = "other/script2.py"
exec[] = "'_exec1_' -p '_param1_'" exec[] = "'_exec2_' -p '_param2_'"
.disco
) a un script usado para encriptar campos de tipo contraseña desde la consola.passencrypt_exec = "'_passencrypt_script_' --encrypt '_password_'"
.disco
) a un script usado para desencriptar campos de tipo contraseña desde la consola.passencrypt_exec = "'_passdecrypt_script_' --decrypt '_password_'"
default_value[_param1_] = "get_main_info" default_value[_param2_] = "" default_value[_param3_] = true default_value[_param4_] = 0 default_value[_param5_] = "[A,B,C]" default_value[_param6_] = "[]"
El siguiente ejemplo puede usarse como base para este bloque, ya que incluye todos los parámetros explicados con comentarios para cada caso:
[discovery_extension_definition] ; Mandatory ; Defines discovery application short name ; Short name must be unique ; Short names with "pandorafms." preffix are used by Pandora FMS for official applications short_name = DISCOVERY_APPLICATION_UNIQUE_NAME ; Mandatory ; Defines the section where application will be shown in console ; Possible values: ; app ; cloud ; custom section = app ; Mandatory ; Defines discovery application name, shown in console name = DISCOVERY_APPLICATION_NAME ; Mandatory ; Defines discovery application version, shown in console version = VERSION ; Optional ; Defines discovery application description, shown in console description = DESCRIPTION ; Optional ; Defines execution files inside .disco ; Several execution files can be defined execution_file[_EXEC_MACRO_N_] = SCRIPT.pl ; Mandatory ; Defines execution for discovery server ; Several executions can be defined ; At least 1 is required for server execution exec[] = SERVER_EXECUTION ; Optional ; Defines password encrypt script passencrypt_script = PASS_ENCRYPT_SCRIPT.pl ; Optional ; Defines password encrypt script execution format ; _passencrypt_script_ is replaced with the passencrypt_script file path ; _password_ is replaced with the string (password) to encrypt passencrypt_exec = EXECUTION ; Optional ; Defines password decrypt script passdecrypt_script = PASS_DECRYPT_SCRIPT.pl ; Optional ; Defines password encrypt script execution format ; _passdecrypt_script_ is replaced with the passdecrypt_script file path ; _password_ is replaced with the string (password) to encrypt passdecrypt_exec = EXECUTION ; Optional ; Defines the default values for the fields when a new task is created ; By default all values are empty or not selected ; Several default values can be defined ; Possible values depending on field type: ; string - STRING ; number - NUMBER ; password - STRING ; textarea - STRING ; checkbox - BOOL ; select - VALUE_N ; multiselect - [VALUE_1,VALUE_N] ; tree - [VALUE_1,VALUE_N] default_value[_FIELD_MACRO_N_] = DEFAULT_VALUE
Este bloque define los pasos de configuración para las tareas del plugin y cuenta con los siguientes parámetros:
Estas normas se aplican para todos los parámetros de este bloque:
[ { "macro": "_FIELD_MACRO_N_", "mandatory_field": "BOOL", "name": "FIELD_NAME", "tip": "FIELD_TIP", "type": "FIELD_TYPE", "placeholder": "PLACEHOLDER", "show_on_true": "_FIELD_MACRO_N_", "encrypt_on_true": "_FIELD_MACRO_N_", "select_data": { "VALUE_1": "TEXT_1", "VALUE_N": "TEXT_N" }, "tree_data": [ { "name": "TEXT_1", "selectable": "BOOL_1", "macro": "_FIELD_MACRO_N_", "value": "VALUE_1", "children": [ { "name": "TEXT_1_1", "selectable": "BOOL_1_1", "macro": "_FIELD_MACRO_N_", "value": "VALUE_1_1", "children": [] }, { "name": "TEXT_1_N", "selectable": "BOOL_1_N", "macro": "_FIELD_MACRO_N_", "value": "VALUE_1_N", "children": [] } ] }, { "name": "TEXT_N", "selectable": "BOOL_N", "macro": "_FIELD_MACRO_N_", "value": "VALUE_N", "children": [] } ] } ]
Por ejemplo, esta sería una forma de definir varios pasos de configuración:
[config_steps] name[1] = First step script_data_fields[1] = "'_exec2_' -p '_param1_' --get_fields" name[2] = Mid step custom_fields[2] = custom_fields_1 name[3] = Last step script_data_fields[3] = "'_exec2_' -p '_param2_' --get_fields" custom_fields[3] = custom_fields_2
En caso de indicarse script_data_fields y custom_fields para un mismo paso de configuración, el formulario mostrará primero los campos obtenidos por el script_data_fields y a continuación los definidos en el custom_fields.
El siguiente ejemplo puede usarse como base para este bloque, ya que incluye todos los parámetros explicados con comentarios para cada caso:
[config_steps] ; Following parameters can be setup for each configuration step ; Several steps can be defined using a different key (N) ; Mandatory ; Defines configuration step name name[N] = STEP_NAME ; Mandatory if not custom_fields defined ; Defines configuration fields retrieved to console by a command execution ; execution_file scripts can be used to retrieve data ; Command execution output must be JSON as follows ; [ ; { ; "macro": "_FIELD_MACRO_N_", ; "mandatory_field": "BOOL", ; "name": "FIELD_NAME", ; "tip": "FIELD_TIP", ; "type": "FIELD_TYPE", ; "placeholder": "PLACEHOLDER", ; "show_on_true": "_FIELD_MACRO_N_", ; "encrypt_on_true": "_FIELD_MACRO_N_", ; "select_data": { ; "VALUE_1": "TEXT_1", ; "VALUE_N": "TEXT_N" ; }, ; "tree_data": [ ; { ; "name": "TEXT_1", ; "selectable": "BOOL_1", ; "macro": "_FIELD_MACRO_N_", ; "value": "VALUE_1", ; "children": [ ; { ; "name": "TEXT_1_1", ; "selectable": "BOOL_1_1", ; "macro": "_FIELD_MACRO_N_", ; "value": "VALUE_1_1", ; "children": [] ; }, ; { ; "name": "TEXT_1_N", ; "selectable": "BOOL_1_N", ; "macro": "_FIELD_MACRO_N_", ; "value": "VALUE_1_N", ; "children": [] ; } ; ] ; }, ; { ; "name": "TEXT_N", ; "selectable": "BOOL_N", ; "macro": "_FIELD_MACRO_N_", ; "value": "VALUE_N", ; "children": [] ; } ; ] ; } ; ] script_data_fields[N] = CONSOLE_EXECUTION_FIELDS ; Mandatory if not script_data_fields defined ; Defines custom configuration fields custom_fields[N] = CUSTOM_FIELDS_N ; Optional ; Defines the number of fields columns for the configuration steps (1 or 2) fields_columns[N] = M
Este bloque define el formato para los ficheros de configuración temporales usados por el plugin y cuenta con los siguientes parámetros:
file[_tempConf_] = "server _param1_ user _param2_ password _param3_ log __temp__/__taskMD5__.log"
El siguiente ejemplo puede usarse como base para este bloque, ya que incluye todos los parámetros explicados con comentarios para cada caso:
[tempfile_confs] ; Mandatory ; Defines the content for the temporary file ; File will be used where temporary file macro is specified during executions ; File content replaces fields macros with their values file[_TEMP_FILE_MACRO_N_] = _FIELD_MACRO_N_,_FIELD_MACRO_M_
Este tipo de bloques puede tener el nombre que se quiera, siempre que se haya asignado como valor dentro del bloque config_steps para su parámetro custom_fields. Definen los campos para los formularios en los pasos de configuración del plugin y cuenta con los siguientes parámetros:
Estas normas se aplican para todos los parámetros de este bloque:
[1,5,12,23]
["elementA","elementF","elementK"]
Por ejemplo, esta sería una forma de definir varios campos de configuración:
[custom_fields_1] macro[1] = _param1_ name[1] = User type[1] = string macro[2] = _param2_ name[2] = Password type[2] = password encrypt_on_true[2] = _param3_ macro[3] = _param3_ name[3] = Encrypt password type[3] = checkbox macro[4] = _param4_ name[4] = Max threads type[4] = number mandatory_field[4] = false macro[5] = _param5_ name[5] = Agents group tip[5] = Agents are generated in this group type[5] = select select_data[5] = agent_groups macro[6] = _param6_ name[6] = Mode type[6] = select select_data[6] = custom_select_1 macro[7] = _param7_ name[7] = Add extra options type[7] = checkbox macro[8] = _param8_ name[8] = Extra elements type[8] = tree tree_data[8] = custom_tree_1 show_on_true[8] = _param7_ macro[9] = _param9_ name[9] = Extra options type[9] = textarea placeholder[9] = "Add extra options here" show_on_true[9] = _param7_
El siguiente ejemplo puede usarse como base para este bloque, ya que incluye todos los parámetros explicados con comentarios para cada caso:
[CUSTOM_FIELDS_N] ; Mandatory ; Defines configuration field unique macro ; Macros can be used for script executions, using their value in place macro[N] = _FIELD_MACRO_N_ ; Optional ; Defines if configuration field is mandatory or not ; By default all configuration fields are mandatory mandatory_field[N] = BOOL ; Mandatory ; Defines configuration field name to be displayed in console ; Macro will be used as name if this field is empty name[N] = FIELD_NAME ; Optional ; Defines a tip for the field, to be displayed in console tip[N] = FIELD_TIP ; Mandatory ; Defines the field type to be displayed in console ; Possible values: ; string ; number ; password ; textarea ; checkbox ; select ; multiselect ; tree type[N] = FIELD_TYPE ; Optional if type is string or textarea ; Defines a placeholder for the field, to be displayed in console placeholder[N] = PLACEHOLDER ; Optional ; Field is shown in console only if assigned field macro exists, is checkbox and is true show_on_true[N] = _FIELD_MACRO_N_ ; Optional if type is password ; Field value is encrypted when stored into database if assigned field macro exists, is checkbox and is true ; Password encrypt and decrypt depends on scripts uploaded to the discovery application encrypt_on_true[N] = _FIELD_MACRO_N_ ; Mandatory if type is select or multiselect ; Defines select data to be displayed in console ; Possible values: ; agent_groups - Uses agent groups names ; agents - Uses agents names ; module_groups - Uses module groups ; modules - Uses modules names ; module_types - Uses module types names ; tags - Uses module tags ; status - Uses module status names ; alert_templates - Uses alert templates names ; alert_actions - Uses alert actions names ; interval - Uses time interval selector ; credentials.custom - Uses pandora custom credentials selector ; credentials.aws - Uses pandora AWS credentials selector ; credentials.azure - Uses pandora Microsoft Azure credentials selector ; credentials.gcp - Uses pandora Google Cloud Platform credentials selector ; credentials.sap - Uses pandora SAP credentials selector ; credentials.snmp - Uses pandora SNMP credentials selector ; credentials.wmi - Uses pandora WMI credentials selector ; os - Uses pandora OS names ; CUSTOM_SELECT_N - Uses custom selector values ; multiselect fields value is a comma separated list of selected values select_data[N] = FIELD_DATA ; Mandatory if type is tree ; Defines tree data to be displayed in console ; tree fields value is a comma separated list of selected values tree_data[N] = CUSTOM_TREE_DATA_N
Este tipo de bloques puede tener el nombre que se quiera, siempre que se haya asignado como valor dentro de un bloque CUSTOM_FIELDS para su parámetro select_data. Definen las opciones de un desplegable del formulario de configuración del plugin y cuenta con los siguientes parámetros:
Por ejemplo:
[custom_select_1] option[v1] = Valor 1 option[v2] = Valor 2 option[v3] = Valor 3 option[v4] = Valor 4 option[v5] = Valor 5
El siguiente ejemplo puede usarse como base para este bloque, ya que incluye todos los parámetros explicados con comentarios para cada caso:
[CUSTOM_SELECT_N] ; Mandatory ; Defines the value-text pair for the select or multiselect ; Several value-text pairs can be defined option[VALUE_N] = TEXT_N
Este tipo de bloques puede tener el nombre que se quiera, siempre que se haya asignado como valor dentro de un bloque CUSTOM_FIELDS para su parámetro tree_data o dentro de otro bloque CUSTOM_TREE_DATA para su parámetro children. Definen los elementos de un árbol del formulario de configuración del plugin y cuenta con los siguientes parámetros:
Estas normas se aplican para todos los parámetros de este bloque:
["element1A","element1F","element1K"]
Por ejemplo, esta sería una forma de definir varios elementos de un árbol:
[custom_tree_1] name[1] = Performance modules selectable[1] = false children[1] = custom_tree_1_A name[2] = Counter modules selectable[2] = false children[2] = custom_tree_1_B [custom_tree_1_A] name[1] = Perf1 macro[1] = _param10_ value[1] = p1 name[2] = Perf2 macro[2] = _param10_ value[2] = p2 name[3] = Perf3 macro[3] = _param10_ value[3] = p3 [custom_tree_1_B] name[1] = Counter1 macro[1] = _param11_ value[1] = c1 name[2] = Counter1 macro[2] = _param11_ value[2] = c2 name[3] = Counter1 macro[3] = _param11_ value[3] = c3
El siguiente ejemplo puede usarse como base para este bloque, ya que incluye todos los parámetros explicados con comentarios para cada caso:
[CUSTOM_TREE_DATA_N] ; Mandatory ; Defines the name for the tree element ; Several names can be defined name[N] = TEXT_N ; Optional ; Defines if tree element is selectable or not ; By default all tree elements are selectable ; Several selectables can be defined selectable[N] = VALUE_N ; Optional if selectable is true ; Defines the macro where value is stored for the tree element ; Several macros can be defined ; Same macro can be defined for several tree elements inside the same tree ; Macro can't be the same than other outside the tree ; If no macro is defined, value is stored for the global tree macro ; Tree values are stored and used the same way as multiselect values do macro[N] = FIELD_MACRO_N ; Mandatory if selectable is true ; Defines the value for the tree element ; Several values can be defined value[N] = VALUE_N ; Optional ; Defines the children elements for the tree element ; CUSTOM_TREE_DATA_M can't be the same than in an upper level ; Several children can be defined children[N] = CUSTOM_TREE_DATA_M
Dentro de los campos que se muestran en los formularios, los selectores simples y múltiples tienen la posibilidad de utilizar datos de la propia aplicación Pandora FMS.
Dependiendo de los datos que se quieran, los valores que se almacenarán y los que se usarán en las ejecuciones variaran:
{ "user":"USER", "password":"PASSWORD" }
{ "access_key_id":"ACCESS_KEY_ID", "secret_access_key":"SECRET_ACCESS_KEY" }
{ "client_id":"CLIENT_ID", "application_secret":"APPLICATION_SECRET", "tenant_domain":"TENANT_DOMAIN", "subscription_id":"SUBSCRIPTION_ID" }
{ "type":"service_account", "project_id":"PROJECT_ID", "private_key_id":"PRIVATE_KEY_ID", "private_key":"PRIVATE_KEY", "client_email":"CLIENT_EMAIL", "client_id":"CLIENT_ID", "auth_uri":"AUTH_URI", "token_uri":"TOKEN_URI", "auth_provider_x509_cert_url":"AUTH_PROVIDER_X509_CERT_URL", "client_x509_cert_url":"CLIENT_X509_CERT_URL" }
{ "user":"USER", "password":"PASSWORD" }
{ "community":"COMMUNITY", "version":"VERSION", "securityLevelV3":"SECURITY_LEVEL_V3", "authUserV3":"USER_AUTH_V3", "authMethodV3":"AUTH_METHOD_V3", "authPassV3":"AUTH_PASS_V3", "privacyMethodV3":"PRIVACY_METHOD_V3", "privacyPassV3":"PRIVACY_PASS_V3" }
{ "user":"USER", "password":"PASSWORD", "namespace":"NAMESPACE" }
El siguiente ejemplo puede usarse como base para crear ficheros discovery_definition.ini, ya que incluye todos los posibles bloques y parámetros explicados anteriormente con comentarios para cada caso:
;-------------------------------------; ; DISCOVERY APPLICATION INI FILE BASE ; ;-------------------------------------; ; Mandatory ; Defines global application data [discovery_extension_definition] ; Mandatory ; Defines discovery application short name ; Short name must be unique ; Short names with "pandorafms." prefix are used by Pandora FMS for official applications short_name = DISCOVERY_APPLICATION_UNIQUE_NAME ; Mandatory ; Defines the section where application will be shown in console ; Possible values: ; app ; cloud ; custom section = app ; Mandatory ; Defines discovery application name, shown in console name = DISCOVERY_APPLICATION_NAME ; Mandatory ; Defines discovery application version, shown in console version = VERSION ; Optional ; Defines discovery application description, shown in console description = DESCRIPTION ; Optional ; Defines execution files inside .disco ; Several execution files can be defined execution_file[_EXEC_MACRO_N_] = SCRIPT.pl ; Mandatory ; Defines execution for discovery server ; Several executions can be defined ; At least 1 is required for server execution exec[] = SERVER_EXECUTION ; Optional ; Defines password encrypt script passencrypt_script = PASS_ENCRYPT_SCRIPT.pl ; Optional ; Defines password encrypt script execution format ; _passencrypt_script_ is replaced with the passencrypt_script file path ; _password_ is replaced with the string (password) to encrypt passencrypt_exec = EXECUTION ; Optional ; Defines password decrypt script passdecrypt_script = PASS_DECRYPT_SCRIPT.pl ; Optional ; Defines password encrypt script execution format ; _passdecrypt_script_ is replaced with the passdecrypt_script file path ; _password_ is replaced with the string (password) to encrypt passdecrypt_exec = EXECUTION ; Optional ; Defines the default values for the fields when a new task is created ; By default all values are empty or not selected ; Several default values can be defined ; Possible values depending on field type: ; string - STRING ; number - NUMBER ; password - STRING ; textarea - STRING ; checkbox - BOOL ; select - VALUE_N ; multiselect - [VALUE_1,VALUE_N] ; tree - [VALUE_1,VALUE_N] default_value[_FIELD_MACRO_N_] = DEFAULT_VALUE ;-------------------------------------; ; Optional ; Defines application configuration steps [config_steps] ; Following parameters can be setup for each configuration step ; Several steps can be defined using a different key (N) ; Mandatory ; Defines configuration step name name[N] = STEP_NAME ; Mandatory if not custom_fields defined ; Defines configuration fields retrieved to console by a command execution ; execution_file scripts can be used to retrieve data ; Command execution output must be JSON as follows ; [ ; { ; "macro": "_FIELD_MACRO_N_", ; "mandatory_field": "BOOL", ; "name": "FIELD_NAME", ; "tip": "FIELD_TIP", ; "type": "FIELD_TYPE", ; "placeholder": "PLACEHOLDER", ; "show_on_true": "_FIELD_MACRO_N_", ; "encrypt_on_true": "_FIELD_MACRO_N_", ; "select_data": { ; "VALUE_1": "TEXT_1", ; "VALUE_N": "TEXT_N" ; }, ; "tree_data": [ ; { ; "name": "TEXT_1", ; "selectable": "BOOL_1", ; "macro": "_FIELD_MACRO_N_", ; "value": "VALUE_1", ; "children": [ ; { ; "name": "TEXT_1_1", ; "selectable": "BOOL_1_1", ; "macro": "_FIELD_MACRO_N_", ; "value": "VALUE_1_1", ; "children": [] ; }, ; { ; "name": "TEXT_1_N", ; "selectable": "BOOL_1_N", ; "macro": "_FIELD_MACRO_N_", ; "value": "VALUE_1_N", ; "children": [] ; } ; ] ; }, ; { ; "name": "TEXT_N", ; "selectable": "BOOL_N", ; "macro": "_FIELD_MACRO_N_", ; "value": "VALUE_N", ; "children": [] ; } ; ] ; } ; ] script_data_fields[N] = CONSOLE_EXECUTION_FIELDS ; Mandatory if not script_data_fields defined ; Defines custom configuration fields custom_fields[N] = CUSTOM_FIELDS_N ; Optional ; Defines the number of fields columns for the configuration steps (1 or 2) fields_columns[N] = M ;-------------------------------------; ; Mandatory if not script_data_fields defined ; Defines custom configuration fields to be used by configuration steps [CUSTOM_FIELDS_N] ; Mandatory ; Defines configuration field unique macro ; Macros can be used for script executions, using their value in place macro[N] = _FIELD_MACRO_N_ ; Optional ; Defines if configuration field is mandatory or not ; By default all configuration fields are mandatory mandatory_field[N] = BOOL ; Mandatory ; Defines configuration field name to be displayed in console ; Macro will be used as name if this field is empty name[N] = FIELD_NAME ; Optional ; Defines a tip for the field, to be displayed in console tip[N] = FIELD_TIP ; Mandatory ; Defines the field type to be displayed in console ; Possible values: ; string ; number ; password ; textarea ; checkbox ; select ; multiselect ; tree type[N] = FIELD_TYPE ; Optional if type is string or textarea ; Defines a placeholder for the field, to be displayed in console placeholder[N] = PLACEHOLDER ; Optional ; Field is shown in console only if asigned field macro exists, is checkbox and is true show_on_true[N] = _FIELD_MACRO_N_ ; Optional if type is password ; Field value is encrypted when stored into database if asigned field macro exists, is checkbox and is true ; Password encrypt and decrypt depends on scripts uploaded to the discovery application encrypt_on_true[N] = _FIELD_MACRO_N_ ; Mandatory if type is select or multiselect ; Defines select data to be displayed in console ; Possible values: ; agent_groups - Uses agent groups names ; agents - Uses agents names ; module_groups - Uses module groups ; modules - Uses modules names ; module_types - Uses module types names ; tags - Uses module tags ; status - Uses module status names ; alert_templates - Uses alert templates names ; alert_actions - Uses alert actions names ; interval - Uses time interval selector ; credentials.custom - Uses pandora custom credentials selector ; credentials.aws - Uses pandora AWS credentials selector ; credentials.azure - Uses pandora Microsoft Azure credentials selector ; credentials.gcp - Uses pandora Google Cloud Platform credentials selector ; credentials.sap - Uses pandora SAP credentials selector ; credentials.snmp - Uses pandora SNMP credentials selector ; credentials.wmi - Uses pandora WMI credentials selector ; os - Uses pandora OS names ; CUSTOM_SELECT_N - Uses custom selector values ; multiselect fields value is a comma separated list of selected values select_data[N] = FIELD_DATA ; Mandatory if type is tree ; Defines tree data to be displayed in console ; tree fields value is a comma separated list of selected values tree_data[N] = CUSTOM_TREE_DATA_N ;-------------------------------------; ; Mandatory if custom tree defined ; Defines custom tree values to be used by configuration fields [CUSTOM_TREE_DATA_N] ; Mandatory ; Defines the name for the tree element ; Several names can be defined name[N] = TEXT_N ; Optional ; Defines if tree element is selectable or not ; By default all tree elements are selectable ; Several selectables can be defined selectable[N] = VALUE_N ; Optional if selectable is true ; Defines the macro where value is stored for the tree element ; Several macros can be defined ; Same macro can be defined for several tree elements inside the same tree ; Macro can't be the same than other outside the tree ; If no macro is defined, value is stored for the global tree macro ; Tree values are stored and used the same way as multiselect values do macro[N] = FIELD_MACRO_N ; Mandatory if selectable is true ; Defines the value for the tree element ; Several values can be defined value[N] = VALUE_N ; Optional ; Defines the children elements for the tree element ; CUSTOM_TREE_DATA_M can't be the same than in an upper level ; Several children can be defined children[N] = CUSTOM_TREE_DATA_M ;-------------------------------------; ; Mandatory if custom select or multiselect defined ; Defines custom select or multiselect values to be used by configuration fields [CUSTOM_SELECT_N] ; Mandatory ; Defines the value-text pair for the select or multiselect ; Several value-text pairs can be defined option[VALUE_N] = TEXT_N ;-------------------------------------; ; Optional ; Defines temporary configuration files to be created and used during scrips executions [tempfile_confs] ; Mandatory ; Defines the content for the temporary file ; File will be used where temporary file macro is specified during executions ; File content replaces fields macros with their values file[_TEMP_FILE_MACRO_N_] = _FIELD_MACRO_N_,_FIELD_MACRO_M_
A continuación mostramos un ejemplo de fichero discovery_definition.ini y como se mostraría su formulario en la consola de Pandora FMS:
[discovery_extension_definition] short_name = discoveryTest section = custom name = Discovery test version = "1.0" description = A test discovery //plugin// execution_file[_exec1_] = test.py exec[] = "'_exec1_' -c '_tempConf_'" passencrypt_script = pass_encrypter.py passencrypt_exec = "'_passencrypt_script_' --encrypt '_password_'" passdecrypt_script = pass_encrypter.py passencrypt_exec = "'_passdecrypt_script_' --decrypt '_password_'" default_value[_param1_] = "admin" default_value[_param2_] = "" default_value[_param3_] = false default_value[_param4_] = 5 default_value[_param5_] = 0 default_value[_param6_] = v1 default_value[_param7_] = true default_value[_param8_] = "[]" default_value[_param9_] = "" default_value[_param10_] = "[]" default_value[_param11_] = "[]" [config_steps] name[1] = Configuration step custom_fields[1] = custom_fields_1 [tempfile_confs] file[_tempConf_] = "user _param1_ password _param2_ encrypt_pass _param3_ threads _param4_ group _param5_ mode _param6_ extra_options _param7_ extra_elements _param8_ extra_perfs _param10_ extra_counters _param11_ log __temp__/__taskMD5__.log _param9_" [custom_fields_1] macro[1] = _param1_ name[1] = User type[1] = string macro[2] = _param2_ name[2] = Password type[2] = password encrypt_on_true[2] = _param3_ macro[3] = _param3_ name[3] = Encrypt password type[3] = checkbox macro[4] = _param4_ name[4] = Max threads type[4] = number mandatory_field[4] = false macro[5] = _param5_ name[5] = Agents group tip[5] = Agents are generated in this group type[5] = select select_data[5] = agent_groups macro[6] = _param6_ name[6] = Mode type[6] = select select_data[6] = custom_select_1 macro[7] = _param7_ name[7] = Add extra options type[7] = checkbox macro[8] = _param8_ name[8] = Extra elements type[8] = tree tree_data[8] = custom_tree_1 show_on_true[8] = _param7_ macro[9] = _param9_ name[9] = Extra options type[9] = textarea placeholder[9] = "Add extra options here" show_on_true[9] = _param7_ [custom_select_1] option[v1] = Valor 1 option[v2] = Valor 2 option[v3] = Valor 3 option[v4] = Valor 4 option[v5] = Valor 5 [custom_tree_1] name[1] = Performance modules selectable[1] = false children[1] = custom_tree_1_A name[2] = Counter modules selectable[2] = false children[2] = custom_tree_1_B [custom_tree_1_A] name[1] = Perf1 selectable[1] = true macro[1] = _param10_ value[1] = p1 name[2] = Perf2 selectable[2] = true macro[2] = _param10_ value[2] = p2 name[3] = Perf3 selectable[3] = true macro[3] = _param10_ value[3] = p3 [custom_tree_1_B] name[1] = Counter1 selectable[1] = true macro[1] = _param11_ value[1] = c1 name[2] = Counter1 selectable[2] = true macro[2] = _param11_ value[2] = c2 name[3] = Counter1 selectable[3] = true macro[3] = _param11_ value[3] = c3
Con la definición de arriba, al crear una tarea para la aplicación, este sería el formulario que se mostraría:
Los campos “Extra elements” y “Extra options” se ocultan en el momento en que “Add extra options” queda sin seleccionar, y el campo “Password” encriptaría su valor al haber seleccionado el campo “Encrypt password”:
En el momento de ejecutar esta tarea por el servidor, genería un fichero temporal (por ejemplo /var/spool/pandora/data_in/discovery/tmp/6d7fce9fee471194aa8b5b6e47267f03
) cuyo contenido podría ser:
user admin password MjZhYjBkYjkwZDcyZTI4YWQwYmExZTIyZWU1MTA1MTAgIC0K encrypt_pass 1 threads 2 group Applications mode v1 extra_options 1 extra_elements [] extra_perfs ["p1", "p2"] extra_counters ["c1"] log /tmp/b026324c6904b2a9cb4b88d6d61c81d1.log
Y el cual usaría durante la ejecución, que sería similar a esta:
'/var/spool/pandora/data_in/discovery/discoveryTest/test.py' -c '/var/spool/pandora/data_in/discovery/tmp/6d7fce9fee471194aa8b5b6e47267f03'
El servidor de Pandora FMS se encargará de ejecutar los scripts y ejecutables definidos en el fichero discovery_definition.ini
y determinará el resultado y sumario de la ejecución de cada tarea en base a la salida y código de error de cada una de las ejecuciones realizadas.
Para determinar el estado comprobará el código de error devuelto por cada una de las ejecuciones que realice. Si al menos una de las ejecuciones devuelve un código de error distinto de 0
, el estado de la tarea se considerará failed.
Para mostrar el sumario de la tarea, para cada una de las ejecuciones que realice el servidor de Pandora FMS recogerá su salida, tanto la salida estándar (STDOUT) como la salida de errores (STDERR). Normalmente se esperará obtener una salida con el siguiente formato JSON mínimo:
{ "summary": { "SUMMARY_FIELD_1": "SUMMARY_VALUE_1", "SUMMARY_FIELD_N": "SUMMARY_VALUE_N" }, "info": "ADDITIONAL_INFO" }
En la consola la clave summary se leera como una tabla de dos columnas, considerando sus claves como los elementos a la izquierda y sus valores como los elementos a la derecha.
La clave info se leera como información adicional, añadiendo una fila más a la tabla de sumario.
Cualquier otra clave del JSON o en caso de de no devolver un JSON o uno que no cumpla esa estructura, el resto de información se añadirá en una fila más en la tabla de sumario.
Se generará una tabla de sumario para cada una de las ejecuciones, enumerándolas en base al orden de as ejecuciones realizadas por el servidor. De este modo la tabla “Summary 1” se correspondería con la primera ejecución, la tabla “Summary 2” con la segunda y así sucesivamente.
Esto pretende asegurar que en la consola sea visible en todo momento el resultado de la última ejecución, tanto si ha sido existosa como si ha sido fallida.
Finalmente, a parte de las acciones que lleven a cabo los scripts o ejecutables, el servidor de Pandora FMS podrá procesar agentes y módulos a partir de la salida de las ejecuciones. Para ello el servidor de Pandora FMS esperará recibir en la salida JSON una clave adicional monitoring_data con la información de cada uno de los agentes y módulos que deba procesar, pero los datos de esta clave no se almacenarán en el sumario de ejecución.
De esta forma, el formato de salida JSON esperado para los plugins de Discovery es este:
{ "summary": { "SUMMARY_FIELD_1": "SUMMARY_VALUE_1", "SUMMARY_FIELD_N": "SUMMARY_VALUE_N" }, "info": "ADDITIONAL_INFO", "monitoring_data": [ { "agent_data": { "agent_name": "AGENT_NAME", "agent_alias": "AGENT_ALIAS", "os": "OS", "os_version": "OS_VERSION", "interval": "INTERVAL", "id_group": "ID_GROUP", "address": "ADDRESS", "description": "DESCRIPTION", "agent_version": "AGENT_VERSION", "parent_agent_name": "PARENT_AGENT_NAME", "timezone_offset": "TIMEZONE_OFFSET" }, "module_data": [ { "name": "NAME", "data": "DATA", "type": "TYPE", "description": "DESCRIPTION", "max": "MAX", "min": "MIN", "post_process": "POST_PROCESS", "module_interval": "MODULE_INTERVAL", "min_critical": "MIN_CRITICAL", "max_critical": "MAX_CRITICAL", "min_warning": "MIN_WARNING", "max_warning": "MAX_WARNING", "disabled": "DISABLED", "min_ff_event": "MIN_FF_EVENT", "datalist": "DATALIST", "status": "STATUS", "unit": "UNIT", "timestamp": "TIMESTAMP", "module_group": "MODULE_GROUP", "custom_id": "CUSTOM_ID", "str_warning": "STR_WARNING", "str_critical": "STR_CRITICAL", "critical_instructions": "CRITICAL_INSTRUCTIONS", "warning_instructions": "WARNING_INSTRUCTIONS", "unknown_instructions": "UNKNOWN_INSTRUCTIONS", "tags": "TAGS", "critical_inverse": "CRITICAL_INVERSE", "warning_inverse": "WARNING_INVERSE", "quiet": "QUIET", "module_ff_interval": "MODULE_FF_INTERVAL", "alert_template": "ALERT_TEMPLATE", "crontab": "CRONTAB", "min_ff_event_normal": "MIN_FF_EVENT_NORMAL", "min_ff_event_warning": "MIN_FF_EVENT_WARNING", "min_ff_event_critical": "MIN_FF_EVENT_CRITICAL", "ff_timeout": "FF_TIMEOUT", "each_ff": "EACH_FF", "module_parent": "MODULE_PARENT", "module_parent_unlink": "MODULE_PARENT_UNLINK", "cron_interval": "CRON_INTERVAL", "ff_type": "FF_TYPE", "min_warning_forced": "MIN_WARNING_FORCED", "max_warning_forced": "MAX_WARNING_FORCED", "min_critical_forced": "MIN_CRITICAL_FORCED", "max_critical_forced": "MAX_CRITICAL_FORCED", "str_warning_forced": "STR_WARNING_FORCED", "str_critical_forced": "STR_CRITICAL_FORCED" } ] } ] }