You are viewing documentation for the development version, it may be incomplete.
Join our translation project and help translate Zabbix documentation into your native language.

3 Agent 2

Overview

Zabbix agent 2 is a new generation of Zabbix agent and may be used in place of Zabbix agent. Zabbix agent 2 has been developed to:

  • reduce the number of TCP connections
  • provide improved concurrency of checks
  • be easily extendible with plugins. A plugin should be able to:
    • provide trivial checks consisting of only a few simple lines of code
    • provide complex checks consisting of long-running scripts and standalone data gathering with periodic sending back of the data
  • be a drop-in replacement for Zabbix agent (in that it supports all the previous functionality)

Agent 2 is written in Go programming language (with some C code of Zabbix agent reused). A configured Go environment with a currently supported Go version is required for building Zabbix agent 2.

Agent 2 does not have built-in daemonization support on Linux; it can be run as a Windows service.

Passive and active checks

Passive checks work similarly to Zabbix agent. Active checks support scheduled/flexible intervals and check concurrency within one active server.

By default, after a restart, Zabbix agent 2 will schedule the first data collection for active checks at a conditionally random time within the item's update interval to prevent spikes in resource usage. To perform active checks that do not have Scheduling update interval immediately after the agent restart, set ForceActiveChecksOnStart parameter (global-level) or Plugins.<Plugin name>.System.ForceActiveChecksOnStart (affects only specific plugin checks) in the configuration file. Plugin-level parameter, if set, will override the global parameter.

Check concurrency

Checks from different plugins can be executed concurrently. The number of concurrent checks within one plugin is limited by the plugin capacity setting. Each plugin may have a hardcoded capacity setting (1000 being default) that can be lowered using the Plugins.<PluginName>.System.Capacity=N setting in the Plugins configuration parameter.

Supported platforms

Zabbix agent 2 is supported on the following platforms:

Installation

To install Zabbix agent 2, the following options are available:

Windows:

Linux:

  • from distribution packages - follow the instructions on the Zabbix packages page, available by choosing your distribution and the Agent 2 component
  • from sources - see Installation from sources; note that you must configure the sources by specifying the --enable-agent2 configuration option

Zabbix agent 2 monitoring capabilities can be extended with plugins. While built-in plugins are available out-of-the-box, loadable plugins must be installed separately. For more information, see Plugins.

Options

The following command-line parameters can be used with Zabbix agent 2:

Parameter Description
UNIX and Windows agent
-c --config <config-file> Path to the configuration file.
You may use this option to specify a configuration file that is not the default one.
On UNIX, default is /usr/local/etc/zabbix_agent2.conf or as set by compile-time variables --sysconfdir or --prefix
On Windows, default is C:\Program Files\Zabbix Agent 2\zabbix_agent2.conf
-f --foreground Run Zabbix agent in foreground (default: true).
-p --print Print known items and exit.
Note: To return user parameter results as well, you must specify the configuration file (if it is not in the default location).
-t --test <item key> Test specified item and exit.
Note: To return user parameter results as well, you must specify the configuration file (if it is not in the default location).
-T --test-config Validate configuration file and exit.
-h --help Print help information and exit.
-v --verbose Print debugging information. Use this option with -p and -t options.
-V --version Print agent version and license information.
-R --runtime-control <option> Perform administrative functions. See runtime control.
Windows agent only
-m --multiple-agents Use multiple agent instances (with -i, -d, -s, -x options).
To distinguish service names of instances, each service name will include the Hostname value from the specified configuration file.
-S --startup-type <value> Set the startup type of the Zabbix Windows agent service. Allowed values:
automatic - (default) start the service automatically at Windows startup;
delayed - delay starting the service after the automatically started services have completed startup;
manual - start the service manually (by a user or application);
disabled - disable the service, so that it cannot be started by a user or application.
You may use this option together with the -i option, or separately to modify the startup type of an already installed service.
-i --install Install Zabbix Windows agent as service.
-d --uninstall Uninstall Zabbix Windows agent service.
-s --start Start Zabbix Windows agent service.
-x --stop Stop Zabbix Windows agent service.

Specific examples of using command-line parameters:

  • print all built-in agent items with values
  • test a user parameter with "mysql.ping" key defined in the specified configuration file
  • installing a "Zabbix Agent" service for Windows using the default path to configuration file C:\Program Files\Zabbix Agent 2\zabbix_agent2.conf
  • modifying the startup type of an installed "Zabbix Agent" service for Windows using the configuration file zabbix_agent2.conf located in the same folder as agent executable
zabbix_agent2 --print
       zabbix_agent2 -t "mysql.ping" -c /etc/zabbix/zabbix_agentd.conf
       zabbix_agent2.exe -i
       zabbix_agent2.exe -c zabbix_agent2.conf -S delayed
Runtime control

Runtime control provides some options for remote control.

Option Description
log_level_increase Increase log level.
log_level_decrease Decrease log level.
metrics List available metrics.
version Display agent version.
userparameter_reload Reload values of the UserParameter and Include options from the current configuration file.
help Display help information on runtime control.

Examples:

  • increasing log level for agent 2
  • print runtime control options
zabbix_agent2 -R log_level_increase
       zabbix_agent2 -R help

Configuration file

The configuration parameters of agent 2 are mostly compatible with Zabbix agent with some exceptions.

New parameters Description
ControlSocket The runtime control socket path. Agent 2 uses a control socket for runtime commands.
EnablePersistentBuffer,
PersistentBufferFile,
PersistentBufferPeriod
These parameters are used to configure persistent storage on agent 2 for active items.
ForceActiveChecksOnStart Determines whether the agent should perform active checks immediately after restart or spread evenly over time.
Plugins Plugins may have their own parameters, in the format Plugins.<Plugin name>.<Parameter>=<value>. A common plugin parameter is System.Capacity, setting the limit of checks that can be executed at the same time.
StatusPort The port agent 2 will be listening on for HTTP status request and display of a list of configured plugins and some internal parameters
Dropped parameters Description
AllowRoot, User Not supported because daemonization is not supported.
LoadModule, LoadModulePath Loadable modules are not supported.
StartAgents This parameter was used in Zabbix agent to increase passive check concurrency or disable them. In Agent 2, the concurrency is configured at a plugin level and can be limited by a capacity setting. Whereas disabling passive checks is not currently supported.
HostInterface, HostInterfaceItem Not yet supported.

For more details see the configuration file options for zabbix_agent2.

Exit codes

Zabbix agent 2 can also be compiled with older OpenSSL versions (1.0.1, 1.0.2).

In this case Zabbix provides mutexes for locking in OpenSSL. If a mutex lock or unlock fails then an error message is printed to the standard error stream (STDERR) and Agent 2 exits with return code 2 or 3, respectively.