mrwho/Ansible-Roles
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Ansible-Roles/roles/zabbix-agent2/README.md
mrwho f9712b45b0 checkout with gigacoms
2026-05-08 22:25:29 +03:00

70 KiB
Raw Blame History

Zabbix agent role

You can use this Ansible role to deploy and configure Zabbix agents on the target machines. Both agentd and agent2 variants are available. Currently, the following OS of target machines are supported:

  • Redhat 8, 9, 10
  • Oracle Linux 8, 9
  • Alma Linux 8, 9
  • Rocky Linux 8, 9
  • CentOS Stream 9, 10
  • Ubuntu 20.04, 22.04, 24.04
  • Debian 10, 11, 12
  • Raspberry Pi Os: 11, 12

Supported distribution list to be extended.

Note: This role is still in active development. There may be unidentified issues and the role variables may change as development continues.

Table of contents

Requirements

This role uses official Zabbix packages and repository for component installation. Target machines require direct or HTTP proxy internet access to Zabbix repository repo.zabbix.com.

For self-hosted repository mirrors, override URL for agent_repository_mirror variable.

The role contains firewalld application rule to allow agent listen port. Firewalld is required on the target machines for this rule to work. Automatic mode agent_apply_firewalld_rule = auto checks if firewalld is installed. Firewalld is a recommended method as it can work with both iptables and nftables. Firewalld can be installed on RHEL- and Debian-based distributions.

Multiple tasks require superuser privileges (sudo).

Ansible core >= 2.17

Zabbix agent role requires additional tools from two Ansible certified collections:

  • ansible.posix >= 2.8
  • ansible.utils >= 1.4

You can install required collections easily:

ansible-galaxy collection install ansible.utils ansible.posix

Note that the role uses ansible.utils.ipaddr filter, which depends on Python library netaddr.

Zabbix agent role relies on Jinja2 heavily and requires version >= 3.1.2

You can install required Python libraries on the control node as follows:

python3 -m pip install "netaddr>=0.8.0" "Jinja2>=3.1.2"

Or using requirements.txt file in the role folder:

python3 -m pip install -r requirements.txt

Check the Python documentation for more details on Python modules installation.

SELinux tasks depend on policycoreutils package. It will be installed as dependency with zabbix-selinux-policy package.

Note that Ansible-core 2.17 requires at least python3.7 on the target devices. Check the compatibility matrix for other versions.

Role variables

You can modify variables listed in this section. Variables are not validated by the role itself. You should experiment with variable definition on a test instance before going for a full-scale deployment.

The default settings are aimed at the ease of installation. You can override those to improve security.

General settings:

Variable Type Default Description
agent_variant int 1 The variant of Zabbix agent (1: Zabbix agentd, 2: Zabbix agent 2).
agent_major_version string 6.0 The major version of Zabbix agent. Defaults to the latest LTS.
agent_minor_version string Zabbix agent minor version customization. For downgrade use with agent_remove_previous_packages=true. Minor version example for debian family distributions: 25-1 (minor version - package version). For RHEL family: 25 (minor version). In both cases minor version will be applied to all packages in agent_package_list.
agent_package_state string present The state of packages to be deployed. Available options: present, latest - update to the latest version if available in the installed zabbix-managed repository.
agent_remove_previous_packages boolean false Trigger removal of previous packages prior to the installation of the new ones. Mandatory to deploy earlier version than the one currently installed.
agent_2_plugin_list list [ceph, docker, memcached, modbus, mongodb, mqtt, mysql, oracle, postgresql, redis, smart] List of Zabbix agent 2 plugins to configure and deploy (if the plugin is loadable). Note that loadable plugins for 6.0 version are installed as dependencies of Zabbix agent 2 package. Starting with 6.4, loadable plugin installation is allowed at your own discretion. Default plugin list for Zabbix agent 2 >= 6.4 is [ceph, docker, memcached, modbus, mqtt, mysql, oracle, redis, smart].
agent_http_proxy string Defines HTTP proxy address for the packager.
agent_https_proxy string Defines HTTPS proxy address for the packager.
agent_repository_mirror string "https://repo.zabbix.com/" Defines repository mirror URL. You can override it to use self-hosted Zabbix repo mirror.
agent_repository_priority int 99 For RedHat family OS only. Sets the priority of the Zabbix repository. Expects integer values from 1 to 99. Covers the cases with interfering packages from central distribution repositories.
agent_repository_disable string "epel" For RedHat family OS only. Disables defined repository during package deployment. Disables EPEL by default.

User settings:

The role allows creating a custom user for Zabbix agent. User customization tasks will trigger only when agent_service_user is not "zabbix".

Variable Type Default Description
agent_service_user string zabbix The user to run Zabbix agent.
agent_service_group string zabbix User group for the custom user.
agent_service_uid string User ID for the custom user.
agent_service_gid string User group ID for the custom user group.

Adds next task sequence:

  • Creates group.
  • Creates user with home folder (defaults to /home/{{ agent_service_user }}).
  • Adds systemd overrides to manage Zabbix agent pid file (/run/zabbix_agent[d|2]/zabbix_agent[d|2].pid).
  • Changes Zabbix agent 2 sockets paths (to the folder of pid file).
  • Changes logging path (to /var/log/zabbix_agent[d|2]/zabbix_agent[d|2].log).

Firewall settings:

The role allows adding simple firewall rules on the target machine to accept passive checks. Advanced firewall configuration is out of the scope of Zabbix agent role.

Firewalld is a recommended way of applying firewall rule as it works with both iptables and nftables. Note that iptables does not work in Ubuntu since 22.04. Firewalld should be installed on target machines. It is supported on RHEL- and Debian-based distributions.

Variable Type Default Description
agent_apply_firewalld_rule string false Defines application of firewalld rule. Possible options: ["auto", "force"]. Undefined or any other string will skip the rule application.
agent_apply_iptables_rule boolean false Defines application of iptables rule. Possible options: [true, false].
agent_firewalld_zone string default Firewalld zone for the rule application.
agent_firewall_allow_from string Only IP addresses allowed. Limits source address of passive check using the firewall rule. For firewalld, this setting will change the rule from simple to rich rule.

You can notice Python module "firewall" sometimes failing to import during these tasks. Most common issue is that Ansible chooses wrong Python interpreter from multiple versions available on host. A solution to this is to provide ansible_python_interpreter with a correct path to legit Python installation on target hosts for specific operating systems. Normally it is defined on inventory level.

Logrotate configuration for Zabbix agent

You can modify rotation options of Zabbix agent[2] log file. It requires default option overriding in agent_logrotate_options variable. This is a list type variable, and it defaults to the list of the following options:

  • weekly
  • maxsize 5M
  • rotate 12
  • compress
  • delaycompress
  • missingok
  • notifempty
  • create 0640 {{ agent_service_user }} {{ agent_service_group }}

Note that most distributions execute logrotate jobs on a daily basis by default. If you wish to change rotation calendar, modify cronjob or systemd timer accordingly or add separate cronjob/timer to process only Zabbix agent[2] log.

Local path variables table:

Variables prefixed with source_ should point to a file or folder located on Ansible execution environment. These files are about to be transferred to the target machines.

Variable Type Default Description
agent_source_conf_dir string Path to the configuration folder on Ansible execution environment that needs to be transferred to the target machine and included in Zabbix agent configuration. For example, a folder with Userparameters.
agent_source_scripts_dir string Path to the scripts folder on Ansible execution environment. Will be copied under the agent_service_user home folder. Scripts can be utilized by UserParameters.
agent_source_modules_dir string Path to Zabbix agentd modules folder on Ansible execution environment. Will be copied to default location for default user. For custom user modules, will be placed under the agent_service_user home folder.
agent_source_tlspskfile string .PSK/{{ inventory_hostname }}.psk Path to the PSK key location on Ansible execution environment. The role will look for the files having the same names as inventory_hostname (hostname from inventory) and generate new if not found. This key will be placed under agent_service_user home folder and added to Zabbix agent configuration automatically.
agent_source_tlscafile string Path to the file on Ansible execution environment containing the top-level CA(s) certificates for peer certificate verification. Will be placed under agent_service_user home folder and added to Zabbix agent configuration automatically.
agent_source_tlscertfile string Path to the file on Ansible execution environment containing the agent certificate or certificate chain. Will be placed under agent_service_user home folder and added to Zabbix agent configuration automatically.
agent_source_tlscrlfile string Path to the file on Ansible execution environment containing revoked certificates. Will be placed under agent_service_user home folder and added to Zabbix agent configuration automatically.
agent_source_tlskeyfile string Path to the file containing the agent private key. Will be placed under agent_service_user home folder and added to Zabbix agent configuration automatically.

SELinux settings:

SELinux tasks will be processed only when SELinux status on the target machine is enabled SELinux tasks depend on policycoreutils package. It will be installed as dependency with zabbix-selinux-policy package.

Variable Type Default Description
agent_apply_seport boolean true Adds custom agent port defined in agent_param_listenport to SELinux port type zabbix_agent_port_t. Enabled by default and triggers when agent_param_listenport is not equal to 10050.
agent_apply_semodule boolean false Adds SELinux policy extension to make a transition of Zabbix agent 2 to SE domain zabbix_agent_t. Additionally, it allows socket usage for the same domain. It also enables read permission on RPM database for system.sw.packages.get key.
agent_seboolean_zabbix_run_sudo string Enables/disables default SELinux boolean zabbix_run_sudo. For task processing, expects string values "on" or "off". Undefined by default, in order to skip task processing. Use with caution as it holds allow rules for a set of domains.

Why audit2allow tool is not included in the role:

  • not secure (it just allows everything that was denied);
  • requires several days of auditlog to collect all needed denials. Use it only as a policy creation consultant.

Default SE boolean zabbix_run_sudo does not fit all possible privileged usage and should be avoided in most cases. Create custom policies for environments with specific security requirements.

Common Zabbix agent configuration parameters:

These parameters are common for both agent variants

Variable Type Default Parameter Description
agent_param_alias list Alias Set an alias for the item key. Location of aliases on target machine: `/etc/zabbix/zabbix_agent[d
agent_param_allowkey list AllowKey Allow execution of the item keys that match the pattern.
agent_param_buffersend int BufferSend Do not keep data in the buffer longer than N seconds.
agent_param_buffersize int BufferSize Maximum number of values in the memory buffer.
agent_param_debuglevel int DebugLevel Debug level.
agent_param_denykey list DenyKey Deny execution of the item keys that match the pattern.
agent_param_heartbeatfrequency int HeartbeatFrequency Frequency of the heartbeat messages in seconds. Added in 6.4.
agent_param_hostinterface string HostInterface Optional parameter that defines the host interface.
agent_param_hostinterfaceitem string HostInterfaceItem Optional parameter that defines the item used for getting the host interface.
agent_param_hostmetadata string HostMetadata Optional parameter that defines the host metadata.
agent_param_hostmetadataitem string HostMetadataItem Optional parameter that defines Zabbix agent item used for getting the host metadata.
agent_param_hostname string {{inventory_hostname}} Hostname Optional parameter that defines the hostname. Defaults to the hostname taken from the inventory.
agent_param_hostnameitem string HostnameItem Optional parameter that defines Zabbix agent item used for getting the hostname.
agent_param_include list agentd: ["/etc/zabbix/zabbix_agentd.d/*.conf"] agent2: ["/etc/zabbix/zabbix_agent2.d/*.conf"] Include You may include individual files or all files in a directory in the configuration file.
agent_param_listenip string ListenIP List of comma-delimited IP addresses that the agent should listen on.
agent_param_listenport int ListenPort The agent will listen on this port for connections from the server.
agent_param_logfile string agentd: /var/log/zabbix/zabbix_agentd.log agent2: /var/log/zabbix/zabbix_agent2.log LogFile Name of the log file.
agent_param_logfilesize int 0 LogFileSize Maximum size of the log file.
agent_param_logtype string file LogType Type of the log output.
agent_param_pidfile string agentd: /run/zabbix/zabbix_agentd.pid agent2: /run/zabbix/zabbix_agent2.pid PidFile Name of the PID file.
agent_param_refreshactivechecks int RefreshActiveChecks How often the list of active checks is refreshed.
agent_param_server string ::/0 Server List of comma-delimited IP addresses, optionally in CIDR notation, or hostnames of Zabbix servers and Zabbix proxies.
agent_param_serveractive string ServerActive Zabbix server/proxy address or cluster configuration to get the active checks from.
agent_param_sourceip string SourceIP Source IP address.
agent_param_timeout int Timeout Spend no more than Timeout seconds on processing.
agent_param_tlsaccept list ["unencrypted"] TLSAccept Incoming connections to be accepted. Available options: unencrypted, cert, psk.
agent_param_tlsconnect string unencrypted TLSConnect How the agent should connect to Zabbix server or proxy. Available options: unencrypted, cert, psk.
agent_param_tlscafile string TLSCAFile Path to the top-level CA(s) certificates for peer certificate verification. Use only when agent_source_tlscafile is not defined!
agent_param_tlscertfile string TLSCertFile Path to the agent certificate or certificate chain. Use only when agent_source_tlscertfile is not defined!
agent_param_tlscrlfile string TLSCRLFile Path to revoked certificates. Use only when agent_source_tlscrlfile is not defined!
agent_param_tlscipherall string TLSCipherAll Override the default ciphersuite selection criteria for certificate- and PSK-based encryption.
agent_param_tlscipherall13 string TLSCipherAll13 Override the default ciphersuite selection criteria for certificate- and PSK-based encryption.
agent_param_tlsciphercert string TLSCipherCert Override the default ciphersuite selection criteria for certificate-based encryption.
agent_param_tlsciphercert13 string TLSCipherCert13 Override the default ciphersuite selection criteria for certificate-based encryption.
agent_param_tlscipherpsk string TLSCipherPSK Override the default ciphersuite selection criteria for PSK-based encryption.
agent_param_tlscipherpsk13 string TLSCipherPSK13 Override the default ciphersuite selection criteria for PSK-based encryption.
agent_param_tlskeyfile string TLSKeyFile Path to the agent private key. Use only when agent_source_tlskeyfile is not defined!
agent_param_tlspskidentity string PSK_ID_{{ inventory_hostname }} TLSPSKIdentity Pre-shared key identity string used for encrypted communications with Zabbix server. Default value uses prefixed hostname from inventory.
agent_param_tlsservercertissuer string TLSServerCertIssuer Allowed server (proxy) certificate issuer.
agent_param_tlsservercertsubject string TLSServerCertSubject Allowed server (proxy) certificate subject.
agent_param_unsafeuserparameters int UnsafeUserParameters Allow all characters to be passed in arguments to user-defined parameters.
agent_param_userparameter list UserParameter User-defined parameter to monitor. Listed user parameters will be placed into the target machine folder: `/etc/zabbix/zabbix_agent[d
agent_param_userparameterdir string UserParameterDir Default search path for UserParameter commands.

Zabbix agentd unique parameters:

Variable Type Default Parameter Description
agent_param_allowroot int AllowRoot Allow the agent to run as 'root'.
agent_param_enableremotecommands int EnableRemoteCommands Whether remote commands from Zabbix server are allowed.
agent_param_listenbacklog int ListenBacklog Maximum number of pending connections in the TCP queue.
agent_param_loadmodule list LoadModule Module to load at agent startup.
agent_param_loadmodulepath string /usr/lib64/zabbix/modules LoadModulePath Full path to the location of agent modules.
agent_param_logremotecommands int LogRemoteCommands Enable logging of executed shell commands as warnings.
agent_param_maxlinespersecond int MaxLinesPerSecond Maximum number of new lines per second that the agent will send to Zabbix server or proxy when processing 'log' and 'logrt' active checks.
agent_param_startagents int StartAgents Number of pre-forked instances of zabbix_agentd processing the passive checks.
agent_param_user string User Drop privileges to a specific user existing in the system.

Zabbix agent 2 unique parameters:

Variable Type Default Parameter Description
agent_param_controlsocket string /run/zabbix/agent.sock ControlSocket Control socket used to send runtime commands with the '-R' option.
agent_param_enablepersistentbuffer int EnablePersistentBuffer Enable the usage of local persistent storage for active items.
agent_param_forceactivechecksonstart int ForceActiveChecksOnStart Perform active checks immediately after the restart for the first received configuration.
agent_param_persistentbufferfile string PersistentBufferFile File where Zabbix agent 2 should keep the SQLite database.
agent_param_persistentbufferperiod string PersistentBufferPeriod Time period of storing the data when there is no connection to the server or proxy.
agent_param_plugins_log_maxlinespersecond int {{ agent_param_maxlinespersecond }} Plugins.Log.MaxLinesPerSecond Maximum number of new lines per second to be sent by the agent to Zabbix server or proxy when processing 'log' and 'logrt' active checks. By default, works like alias to agent_param_maxlinespersecond.
agent_param_plugins_systemrun_logremotecommands int {{ agent_param_logremotecommands }} Plugins.SystemRun.LogRemoteCommands Enable the logging of the executed shell commands as warnings. By default, works like alias to agent_param_logremotecommands.
agent_param_pluginsocket string /run/zabbix/agent.plugin.sock PluginSocket Path to the UNIX socket for loadable plugin communications.
agent_param_plugintimeout int PluginTimeout Timeout for connections with loadable plugins, in seconds.
agent_param_refreshactivechecks int RefreshActiveChecks How often the list of active checks is refreshed.
agent_param_statusport int StatusPort If set, the agent will listen on this port for HTTP status requests (http://localhost:<port>/status).
agent_param_includeplugins list ["/etc/zabbix/zabbix_agent2.d/plugins.d/*.conf"] Include Path to plugin configuration files. You may include individual files or all files in a directory in the configuration file.

Zabbix agent 2 Ceph plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list.

Variable Type Parameter Description
agent_param_plugins_ceph_insecureskipverify string Plugins.Ceph.InsecureSkipVerify Determines whether the HTTP client should verify the server's certificate chain and host name. If true, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks (should be used only for testing).
agent_param_plugins_ceph_keepalive int Plugins.Ceph.KeepAlive Maximum time of waiting (in seconds) before unused plugin connections are closed.
agent_param_plugins_ceph_timeout int Plugins.Ceph.Timeout Request execution timeout (how long to wait for a request to complete before shutting it down).
agent_param_plugins_ceph_sessions list of dictionaries Plugins.Ceph.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", apikey: "", user: "", uri: ""}
agent_param_plugins_ceph_default dictionary Plugins.Ceph.Default Holds the default connection credentials in dictionary form with the keys: { apikey: "", user: "", uri: ""}

Zabbix agent 2 Docker plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list.

Variable Type Parameter Description
agent_param_plugins_docker_endpoint string Plugins.Docker.Endpoint Docker daemon unix-socket location. Must contain a scheme (only unix:// is supported).
agent_param_plugins_docker_timeout int Plugins.Docker.Timeout Request execution timeout (how long to wait for a request to complete before shutting it down).

Zabbix agent 2 Memcached plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list.

Variable Type Parameter Description
agent_param_plugins_memcached_keepalive int Plugins.Memcached.KeepAlive Maximum time of waiting (in seconds) before unused plugin connections are closed.
agent_param_plugins_memcached_timeout int Plugins.Memcached.Timeout Request execution timeout (how long to wait for a request to complete before shutting it down).
agent_param_plugins_memcached_sessions list of dictionaries Plugins.Memcached.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", password: "", user: "", uri: ""}
agent_param_plugins_memcached_default dictionary Plugins.Memcached.Default Holds the default connection credentials in dictionary form with the keys: { password: "", user: "", uri: ""}

Zabbix agent 2 Modbus plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list.

Variable Type Parameter Description
agent_param_plugins_modbus_timeout int Plugins.Modbus.Timeout Request execution timeout (how long to wait for a request to complete before shutting it down).
agent_param_plugins_modbus_sessions list of dictionaries Plugins.Modbus.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", endpoint: "", slaveid: "", timeout: ""}

Zabbix agent 2 MongoDB plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list. To encrypt session, define tlsconnect key. After tlsconnect session key is defined, all 3 certificate files become mandatory! Parameter prefixes source_ should point to the certificate files located on Ansible execution environment. The certificate files will be placed on the target machine and added to configuration automatically.

You can also manage session certificate files outside this role. In this case, use same keys without source_ prefix and fill them with final path to files on the target machine. Here is the dictionary skeleton for self-managed certificate files: { name: "", uri: "", user: "", password: "", tlsconnect: "", tlscafile: "", tlscertfile: "", tlskeyfile: ""}

Don't use both local path and final path to avoid unpredictable results!

Variable Type Default Parameter Description
agent_param_plugins_mongodb_keepalive int Plugins.MongoDB.KeepAlive Maximum time of waiting (in seconds) before unused plugin connections are closed.
agent_param_plugins_mongodb_timeout int Plugins.MongoDB.Timeout Request execution timeout (how long to wait for a request to complete before shutting it down).
agent_param_plugins_mongodb_system_path string Zabbix version <=7.0: /usr/sbin/zabbix-agent2-plugin/zabbix-agent2-plugin-mongodb Zabbix version >= 7.2: /usr/libexec/zabbix/zabbix-agent2-plugin-mongodb Plugins.MongoDB.System.Path Path to external plugin executable. Supported since Zabbix 6.0.6.
agent_param_plugins_mongodb_sessions list of dictionaries Plugins.MongoDB.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", uri: "", user: "", password: "", tlsconnect: "", source_tlscafile: "", source_tlscertfile: "", source_tlskeyfile: ""}
agent_param_plugins_mongodb_default dictionary Plugins.MongoDB.Default Holds the default connection credentials in dictionary form with the keys: { uri: "", user: "", password: "",}

Zabbix agent 2 MQTT plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list.

You can also manage session certificate files outside this role. In this case, use same keys without source_ prefix and fill them with final path to files on the target machine. Here is the dictionary skeleton for self-managed certificate files: { name: "", url: "", topic: "", user: "", password: "", tlscafile: "", tlscertfile: "", tlskeyfile: ""}

Don't use both local path and final path to avoid unpredictable results!

Variable Type Parameter Description
agent_param_plugins_mqtt_timeout int Plugins.MQTT.Timeout Request execution timeout (how long to wait for a request to complete before shutting it down).
agent_param_plugins_mqtt_sessions list of dictionaries Plugins.MQTT.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", url: "", topic: "", user: "", password: "", source_tlscafile: "", source_tlscertfile: "", source_tlskeyfile: ""}
agent_param_plugins_mqtt_default dictionary Plugins.MQTT.Default Holds the list of connection credentials in dictionary form with the keys: { url: "", topic: "", user: "", password: "", source_tlscafile: "", source_tlscertfile: "", source_tlskeyfile: ""}

Zabbix agent 2 Oracle plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list.

Variable Type Parameter Description
agent_param_plugins_oracle_calltimeout int Plugins.Oracle.CallTimeout Maximum time of waiting (in seconds) for a request to be done.
agent_param_plugins_oracle_connecttimeout int Plugins.Oracle.ConnectTimeout Maximum time of waiting (in seconds) for a connection to be established.
agent_param_plugins_oracle_customqueriespath string Plugins.Oracle.CustomQueriesPath Full pathname of the directory containing .sql files with custom queries. Disabled by default. Example: /etc/zabbix/oracle/sql
agent_param_plugins_oracle_keepalive int Plugins.Oracle.KeepAlive Maximum time of waiting (in seconds) before unused plugin connections are closed.
agent_param_plugins_oracle_sessions list of dictionaries Plugins.Oracle.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", uri: "", service: "", user: "", password: "" }
agent_param_plugins_oracle_default list of dictionaries Plugins.Oracle.Sessions Holds the default connection credentials in dictionary form with the keys: { uri: "", service: "", user: "", password: "" }

Zabbix agent 2 PostgreSQL plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list. To encrypt session, define tlsconnect key. After tlsconnect session key is defined, all 3 certificate files become mandatory! Parameter prefixes source_ should point to the certificate files located on Ansible execution environment. The certificate files will be placed on the target machine and added to configuration automatically.

You can also manage session certificate files outside this role. In this case, use same keys without source_ prefix and fill them with final path to files on the target machine. Here is the dictionary skeleton for self-managed certificate files: { name: "", uri: "", user: "", password: "", database: "", tlsconnect: "", tlscafile: "", tlscertfile: "", tlskeyfile: "", cachemode: ""}

Don't use both local path and final path to avoid unpredictable results!

Variable Type Default Parameter Description
agent_param_plugins_postgresql_calltimeout int Plugins.Postgresql.CallTimeout Maximum time of waiting (in seconds) for a request to be done.
agent_param_plugins_postgresql_customqueriespath string Plugins.Postgresql.CustomQueriesPath Full pathname of the directory containing .sql files with custom queries. Disabled by default. Example: /etc/zabbix/postgresql/sql
agent_param_plugins_postgresql_keepalive int Plugins.Postgresql.KeepAlive Time of waiting (in seconds) for unused connections to be closed.
agent_param_plugins_postgresql_timeout int Plugins.Postgresql.Timeout Maximum time of waiting (in seconds) for a connection to be established.
agent_param_plugins_postgresql_system_path string Zabbix version <=7.0: /usr/sbin/zabbix-agent2-plugin/zabbix-agent2-plugin-postgresql Zabbix version >= 7.2: /usr/libexec/zabbix/zabbix-agent2-plugin-postgresql Plugins.Postgresql.System.Path Path to the external plugin executable. Supported since Zabbix 6.0.6.
agent_param_plugins_postgresql_sessions list of dictionaries Plugins.Postgresql.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", uri: "", user: "", password: "", database: "", tlsconnect: "", source_tlscafile: "", source_tlscertfile: "", source_tlskeyfile: "", cahcemode: ""}
agent_param_plugins_postgresql_default dictionary Plugins.Postgresql.Default Holds the default connection credentials in dictionary form with the keys: { uri: "", user: "", password: "", database: "", tlsconnect: "", source_tlscafile: "", source_tlscertfile: "", source_tlskeyfile: "", cachemode: ""}

Zabbix agent 2 MySQL plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list. To encrypt session, define tlsconnect key. After tlsconnect session key is defined, all 3 certificate files become mandatory! Parameter prefixes source_ should point to the certificate files located on Ansible execution environment. The certificate files will be placed on the target machine and added to configuration automatically.

You can also manage session certificate files outside this role. In this case, use same keys without source_ prefix and fill them with final path to files on the target machine. Here is the dictionary skeleton for self-managed certificate files: { name: "", uri: "", user: "", password: "", tlsconnect: "", tlscafile: "", tlscertfile: "", tlskeyfile: ""}

Don't use both local path and final path to avoid unpredictable results!

Variable Type Parameter Description
agent_param_plugins_mysql_calltimeout int Plugins.Mysql.CallTimeout Maximum time of waiting (in seconds) for a request to be done.
agent_param_plugins_mysql_keepalive int Plugins.Mysql.KeepAlive Time of waiting (in seconds) before unused connections are closed.
agent_param_plugins_mysql_timeout int Plugins.Mysql.Timeout Maximum time of waiting (in seconds) for a connection to be established.
agent_param_plugins_mysql_customqueriespath string Plugins.Mysql.CustomQueriesPath Full pathname of a directory containing .sql files with custom queries.
agent_param_plugins_mysql_sessions list of dictionaries Plugins.Mysql.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", uri: "", user: "", password: "", tlsconnect: "", source_tlscafile: "", source_tlscertfile: "", source_tlskeyfile: ""}
agent_param_plugins_mysql_default dictionary Plugins.Mysql.Default.* Holds the default connection credentials in dictionary form with the keys: { uri: "", user: "", password: "", tlsconnect: "", source_tlscafile: "", source_tlscertfile: "", source_tlskeyfile: ""}

Zabbix agent 2 MSSQL plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list. Parameter prefixes source_ should point to the certificate files located on Ansible execution environment. The certificate files will be placed on the target machine and added to configuration automatically.

You can also manage session certificate files outside this role. In this case, use same keys without source_ prefix and fill them with final path to files on the target machine. Here is the dictionary skeleton for self-managed certificate files: { name: "", uri: "", user: "", password: "", cacertpath: "", trustservercertificate: "", hostnameincertificate: "", encrypt: "", tlsminversion: ""}

Don't use both local path and final path to avoid unpredictable results!

Variable Type Default Parameter Description
agent_param_plugins_mssql_keepalive int Plugins.MSSQL.KeepAlive Time of waiting (in seconds) before unused connections are closed.
agent_param_plugins_mssql_timeout int Plugins.MSSQL.Timeout The amount of time to wait for a server to respond when first connecting and on follow-up operations in the session.
agent_param_plugins_mssql_customqueriespath string Plugins.MSSQL.CustomQueriesPath Full pathname of a directory containing .sql files with custom queries. Changes requires Zabbix agent2 restart.
agent_param_plugins_mssql_system_path string Zabbix version <=7.0: /usr/sbin/zabbix-agent2-plugin/zabbix-agent2-plugin-mssql Zabbix version >= 7.2: /usr/libexec/zabbix/zabbix-agent2-plugin-mssql Plugins.MSSQL.System.Path Path to the external plugin executable.
agent_param_plugins_mssql_sessions list of dictionaries Plugins.MSSQL.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", uri: "", user: "", password: "", source_cacertpath: "", trustservercertificate: "", hostnameincertificate: "", encrypt: "", tlsminversion: ""}
agent_param_plugins_mssql_default dictionary Plugins.MSSQL.Default.* Holds the default connection credentials in dictionary form with the keys: { uri: "", user: "", password: "", source_cacertpath: "", trustservercertificate: "", hostnameincertificate: "", encrypt: "", tlsminversion: ""}

Zabbix agent 2 NVIDIA GPU plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list.

Variable Type Default Parameter Description
agent_param_plugins_nvidia_system_path string /usr/libexec/zabbix/zabbix-agent2-plugin-nvidia-gpu Plugins.NVIDIA.System.Path Path to the NVIDIA GPU plugin executable.
agent_param_plugins_nvidia_timeout int Plugins.NVIDIA.Timeout Specifies the maximum time (in seconds) to wait for a server response during connection attempts and subsequent operations in the session. The global item-type timeout or individual item timeout will override this value if greater.

Zabbix agent 2 Redis plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list.

Variable Type Parameter Description
agent_param_plugins_redis_keepalive int Plugins.Redis.KeepAlive Maximum time of waiting (in seconds) before unused plugin connections are closed.
agent_param_plugins_redis_timeout int Plugins.Redis.Timeout Request execution timeout (how long to wait for a request to complete before shutting it down).
agent_param_plugins_redis_sessions list of dictionaries Plugins.Redis.Sessions Holds the list of connection credentials in dictionary form with the keys: { name: "", uri: "", password: "" }
agent_param_plugins_redis_default dictionary Plugins.Redis.Sessions Holds the default connection credentials in dictionary form with the keys: { uri: "", password: "" }

Zabbix agent 2 Smart plugin parameters:

For these settings to take effect, the plugin should be listed in agent_2_plugin_list.

Variable Type Parameter Description
agent_param_plugins_smart_path string Plugins.Smart.Path Path to the smartctl executable.
agent_param_plugins_smart_timeout int Plugins.Smart.Timeout Request execution timeout (how long to wait for a request to complete before shutting it down).

Hints & Tags

  • Wrong variable definition level can be punishing for starters. Begin with variable precedence learning. We recommend organizing host and group variables on inventory level. It is handy for big environments and will fit most use cases.

  • Zabbix agent role uses handlers to reload systemd daemon and restart zabbix-agent[2] service. To trigger handler execution each time (not only after changes made), compliment your run with restart tag. Add it after all tag or other tasks (those not marked with restart tag will be skipped).

    ansible-playbook -i inventory play.yml -t all,restart

  • To stop and remove zabbix-agent[2] service, use remove tag. This will clear custom overrides if present and uninstall packages, according to variables defined.

    ansible-playbook -i inventory play.yml -t remove

  • If agent_param_userparameter is modified and registered as the only change during role run, it will trigger Zabbix agent[2] runtime command to reload user parameters without agent restart.

  • To run only tasks that modify user parameters, pass userparam tag. Task sequence will be limited to:

    • Copying include folder.

    • Copying script folder.

    • Adding a list of user parameters from agent_param_userparameter variable to configuration file.

    • Executing runtime command to reload user parameters.

      ansible-playbook -i inventory play.yml -t userparam

Playbook examples

  • Playbook 1:

    Latest LTS Zabbix agentd deployment for active checks only.

    1. Here we will deploy Zabbix agentd (from defaults: agent_variant = 1).
    2. Major version defaults to current LTS version.
    3. Since we are removing passive checks with agent_param_startagents = 0, firewalld rule application will be skipped.
    4. Hostname of the agent or agent_param_hostname defaults to the inventory hostname.
    5. We can prepare metadata for active agent autoregistration by using Ansible special variables and filters. In this example we will use groups from the inventory to form the metadata. Special variable group_names contains the list of groups assigned to the host. Let's concatenate this list to the string separated by commas. It will look as follows: "DB,Linux,MySQL,etc"
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        agent_param_serveractive: 127.0.0.1   # address of Zabbix server to connect using active checks;
        agent_param_startagents: 0            # do not spawn passive check processes that listen for connections;
        agent_param_hostmetadata: '{{ group_names | join(",") }}'   # concatenate group list to the string;

  • Playbook 2:

    6.4 version of Zabbix agent 2 for both passive and active checks + Iptables.

    1. To deploy Zabbix agent 2, define agent_variant = 2.
    2. You can specify Zabbix agent major version manually: agent_major_version: "6.4".
    3. Same metadata as described in the first example.
    4. Disable application of the firewall rule using firewalld daemon: agent_apply_firewalld_rule: false.
    5. Enable firewall rule application using iptables module. Note that modern Ubuntu distributions use nftables, and iptables are DEPRECATED.
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        agent_variant: 2
        agent_major_version: 6.4
        agent_param_server: 127.0.0.1         # address of Zabbix server to accept connections from;
        agent_param_serveractive: 127.0.0.1   # address of Zabbix server to connect using active checks;
        agent_param_hostmetadata: '{{ group_names | join(",") }}'   # concatenate group list to the string;
        agent_apply_firewalld_rule: false                          # "auto" is the default and recommended value;
        agent_apply_iptables_rule: true                          # "auto" is the default value;
        agent_firewall_allow_from: 127.0.0.1  # limit listening on agent port only from the defined source address

  • Playbook 3:

    Zabbix agentd for both passive and active checks with PSK encryption for autoregistration.

    1. Same metadata for autoregistration as described in the first example.
    2. Set incoming and outgoing connection to be encrypted with psk
    • agent_param_tlsconnect is a single-type setting, so string input is expected;
    • agent_param_tlsaccept can simultaneously work with all 3 types, so we are using list format here;
    • agent_source_tlspskfile can use relative or absolute path to an existent key or a place where it should be generated. Because of autoregistration, single PSK key should be used and identity for all agents should be registered. After the key is generated, add it to Zabbix using GUI (Administration > General > Autoregistration);
    • agent_param_tlspskidentity is used for passing the identity name to be placed in Zabbix agent configuration file. The same should be placed in Zabbix autoregistration options (Administration > General > Autoregistration).
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        agent_param_server: 127.0.0.1         # address of Zabbix server to accept connections from;
        agent_param_serveractive: 127.0.0.1   # address of Zabbix server to connect using active checks;
        agent_param_hostmetadata: '{{ group_names | join(",") }}'   # concatenate group list to the string;
        agent_param_tlsconnect: psk
        agent_param_tlsaccept: [psk]
        agent_source_tlspskfile: TEST/autoregistration.psk # "autoregistration" key will be placed to TEST folder;
        agent_param_tlspskidentity: 'PSK_ID_AUTOREGISTRATION' # length <= 128 char

  • Playbook 4:

    Zabbix agentd with certificate-secured connections.

    1. When passive checks are enabled, the role attempts to apply firewalld rule to allow listening on Zabbix agent port (which defaults to agent_param_listenport = 10050). Firewalld should be installed on the target machine or this step will be skipped.
    2. Same metadata as described in the first example.
    3. When cert is specified in agent_param_tlsconnect or agent_param_tlsaccept source, the path to certificate files becomes mandatory. Check the configuration example below. We are pointing to "certs/" folder which holds the certificate files named according to the host inventory name.
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        agent_param_server: 127.0.0.1                                # address of Zabbix server to accept connections from;
        agent_param_serveractive: 127.0.0.1                          # address of Zabbix server to connect using active checks;
        agent_param_hostmetadata: '{{ group_names | join(",") }}'    # concatenate group list to the string;
        agent_param_tlsconnect: cert                                 # restrict active checks to certificate only;
        agent_param_tlsaccept: ["cert", "unencrypted"]               # allow encrypted and unencrypted passive checks;
        agent_source_tlscafile: certs/ca.crt                         # provide the path to CA certificate file on Ansible execution environment;
        # agent_source_tlscrlfile:                                   # certificate revocation list, can be omitted;
        agent_source_tlscertfile: certs/{{ inventory_hostname }}.crt # Zabbix agent certificate path on the execution environment;
        agent_source_tlskeyfile: certs/{{ inventory_hostname }}.key  # key file path on the execution environment;
        agent_param_tlsservercertissuer: CN=root-ca                  # certificate issuer restriction (optional);
        agent_param_tlsservercertsubject: CN=server                   # certificate subject restriction (optional);

  • Playbook 5:

    6.4 version of Zabbix agent 2 for MongoDB monitoring.

    1. To deploy Zabbix agent 2, define agent_variant = 2.
    2. You can specify Zabbix agent major version manually: agent_major_version: "6.4".
    3. Same metadata as described in the first example.
    4. When passive checks are enabled, the role attempts to apply firewalld rule to allow listening on Zabbix agent port (which defaults to agent_param_listenport = 10050). Firewalld should be installed on the target machine or this step will be skipped.
    5. Since Zabbix 6.4, loadable plugins are not installed by zabbix-agent2 package as dependency. We need to add it to agent_2_plugin_list.
    6. We will configure a TLS connection session within MongoDB, using the same approach with source files. The role will transfer them to the target machine and configure automatically. The certificate files will be placed to Zabbix agent service user home folder.
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        agent_variant: 2
        agent_major_version: 6.4
        agent_param_server: 127.0.0.1         # address of Zabbix server to accept connections from;
        agent_param_serveractive: 127.0.0.1   # address of Zabbix server to connect using active checks;
        agent_param_hostmetadata: '{{ group_names | join(",") }}'   # concatenate group list to the string;
        agent_2_plugin_list: [ceph, docker, memcached, modbus, mqtt, mysql, oracle, redis, smart, mongodb]
        agent_param_plugins_mongodb_sessions:
          - name: "sessionname"
            uri: "someuri"
            user: "someuser"
            password: "somepassword"
            tlsconnect: "required"
            ## Location of the source certificate files on Ansible execution environment.
            source_tlscafile: "certs/ca.crt"
            source_tlscertfile: "certs/{{ inventory_hostname }}.crt"
            source_tlskeyfile: "certs/{{ inventory_hostname }}.key"

  • Playbook 6:

    Zabbix agentd downgrade from 6.4 to 6.0

    1. You can specify Zabbix agent major version manually: agent_major_version: "6.0".
    2. The attempt to install earlier version will fail because the newer one is already installed. To overcome this, previous packages should be removed first.
    3. Same metadata as described in the first example.
    4. When passive checks are enabled, the role attempts to apply firewalld rule to allow listening on Zabbix agent port (which defaults to agent_param_listenport = 10050). Firewalld should be installed on the target machine or this step will be skipped.
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        agent_major_version: "6.0"
        agent_remove_previous_packages: true  # removes previously installed package of Zabbix agent (according to current settings);
        agent_param_server: 127.0.0.1         # address of Zabbix server to accept connections from;
        agent_param_serveractive: 127.0.0.1   # address of Zabbix server to connect using active checks;
        agent_param_hostmetadata: '{{ group_names | join(",") }}'   # concatenate group list to the string;

  • Playbook 7:

    Zabbix agentd running under custom user

    1. Same metadata as described in the first example.
    2. When passive checks are enabled, the role attempts to apply firewalld rule to allow listening on Zabbix agent port (which defaults to agent_param_listenport = 10050). Firewalld should be installed on the target machine or this step will be skipped.
    3. Setting agent_service_user will trigger custom user task list. It will create user, user group, home folder, systemd overrides and a separate log folder.
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        agent_param_server: 127.0.0.1         # address of Zabbix server to accept connections from;
        agent_param_serveractive: 127.0.0.1   # address of Zabbix server to connect using active checks;
        agent_param_hostmetadata: '{{ group_names | join(",") }}'   # concatenate group list to the string;
        agent_service_user: dor               # if agent_service_user is not "zabbix", multiple changes are applied
        agent_service_group: blue
        agent_service_uid: 1115
        agent_service_gid: 1115

  • Playbook 8:

    Update Zabbix agentd to latest minor version

    1. Same metadata as described in the first example.
    2. When passive checks are enabled, the role attempts to apply firewalld rule to allow listening on Zabbix agent port (which defaults to agent_param_listenport = 10050). Firewalld should be installed on the target machine or this step will be skipped.
    3. Setting agent_package_state = latest will install the latest minor version of the packages.
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        agent_param_server: 127.0.0.1         # address of Zabbix server to accept connections from;
        agent_param_serveractive: 127.0.0.1   # address of Zabbix server to connect using active checks;
        agent_param_hostmetadata: '{{ group_names | join(",") }}'   # concatenate group list to the string;
        agent_package_state: latest           # use latest available minor version

  • Playbook 9:

    Deploy Zabbix agent without direct internet access from target machine, by using HTTP proxy.

    1. Same metadata as described in the first example.
    2. When passive checks are enabled, the role attempts to apply firewalld rule to allow listening on Zabbix agent port (which defaults to agent_param_listenport = 10050). Firewalld should be installed on the target machine or this step will be skipped.
    3. Supply HTTP proxy address to the agent_http_proxy variable.
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        agent_param_server: 127.0.0.1         # address of Zabbix server to accept connections from;
        agent_param_serveractive: 127.0.0.1   # address of Zabbix server to connect using active checks;
        agent_param_hostmetadata: '{{ group_names | join(",") }}'   # concatenate group list to the string;
        agent_http_proxy: http://host.containers.internal:8123  # HTTP proxy address.

  • Playbook 10:

    Deploy Zabbix agent with passive checks only and add hosts to Zabbix.

    1. Fill Zabbix agent configuration. Here we will allow Zabbix server to communicate with agent and apply firewall rule to accept connection only from Zabbix server.
    2. Active agent autoregistration does not work with passive checks. So we need to use Zabbix API to add new host with passive checks only. Add zabbix.zabbix.host role to the same Ansible play to inherit variables from the first role.
    3. Fill Zabbix API connection properties.
    4. Fill Zabbix host configuration. This time, we will add only template to assign. Default configuration will apply host name and agent connection properties from Ansible inventory.
      - hosts: all
    roles:
      - role: zabbix.zabbix.agent
        ### Zabbix agent configuration
        agent_param_server: 256.256.256.256                     # address of Zabbix server to accept connections from monitoring instance;
        agent_firewall_allow_from: 256.256.256.256              # address of Zabbix server to allow connections from monitoring instance using firewalld;
      - role: zabbix.zabbix.host
        ### Zabbix API properties
        host_zabbix_api_server: zabbix.frontend.loc             # Zabbix frontend server;
        host_zabbix_api_port: 443                             # Zabbix fronted connection port;
        host_zabbix_api_user: Admin                           # Zabbix user name for API connection;
        host_zabbix_api_password: zabbix                      # Zabbix user password for API connection;
        host_zabbix_api_use_ssl: True                         # Use secure connection;
        ### Zabbix host configuration
        host_templates: ["Linux by Zabbix agent"]  # Assign list of templates to the host;

License

Ansible Zabbix collection is released under the GNU Affero General Public License (AGPL) version 3. The formal terms of the GPL can be found at http://www.fsf.org/licenses/.