[comment]: # ({7f44ce82-7f44ce82})
# 4 Zabbix agent 2 (UNIX)

[comment]: # ({/7f44ce82-7f44ce82})

[comment]: # ({d5608d34-d5608d34})
#### Overview

Zabbix agent 2 is a new generation of Zabbix agent and may be used in
place of Zabbix agent.

This section lists parameters supported in a Zabbix agent 2
configuration file (zabbix\_agent2.conf). 

Note that:

-   The default values reflect process defaults, not the values in the
    shipped configuration files;
-   Zabbix supports configuration files only in UTF-8 encoding without
    [BOM](https://en.wikipedia.org/wiki/Byte_order_mark);
-   Comments starting with "\#" are only supported in the beginning of
    the line.

[comment]: # ({/d5608d34-d5608d34})

[comment]: # ({65ade290-d34644cb})
#### Parameters

|Parameter|<|Mandatory|Range|Default|Description|
|-|----------|----------|----------|----------|--------------------------------------------------|
|Alias|<|no| | |Sets an alias for an item key. It can be used to substitute long and complex item key with a smaller and simpler one.<br>Multiple *Alias* parameters may be present. Multiple parameters with the same *Alias* key are not allowed.<br>Different *Alias* keys may reference the same item key.<br>Aliases can be used in *HostMetadataItem* but not in *HostnameItem* parameters.<br><br>Examples:<br><br>1. Retrieving the ID of user 'zabbix'.<br>Alias=zabbix.userid:vfs.file.regexp\[/etc/passwd,"\^zabbix:.:(\[0-9\]+)",,,,\\1\]<br>Now shorthand key **zabbix.userid** may be used to retrieve data.<br><br>2. Getting CPU utilization with default and custom parameters.<br>Alias=cpu.util:system.cpu.util<br>Alias=cpu.util\[\*\]:system.cpu.util\[\*\]<br>This allows use **cpu.util** key to get CPU utilization percentage with default parameters as well as use **cpu.util\[all, idle, avg15\]** to get specific data about CPU utilization.<br><br>3. Running multiple [low-level discovery](/manual/discovery/low_level_discovery) rules processing the same discovery items.<br>Alias=vfs.fs.discovery\[\*\]:vfs.fs.discovery<br>Now it is possible to set up several discovery rules using **vfs.fs.discovery** with different parameters for each rule, e.g., **vfs.fs.discovery\[foo\]**, **vfs.fs.discovery\[bar\]**, etc.|
|AllowKey|<|no| | |Allow execution of those item keys that match a pattern. Key pattern is a wildcard expression that supports "\*" character to match any number of any characters.<br>Multiple key matching rules may be defined in combination with DenyKey. The parameters are processed one by one according to their appearance order.<br>This parameter is supported since Zabbix 5.0.0.<br>See also: [Restricting agent checks](/manual/config/items/restrict_checks).|
|BufferSend|<|no|1-3600|5|The time interval in seconds which determines how often values are sent from the buffer to Zabbix server.<br>Note that if the buffer is full, the data will be sent sooner.|
|BufferSize|<|no|2-65535|100|Maximum number of values in a memory buffer. The agent will send all collected data to Zabbix server or proxy if the buffer is full.<br>This parameter should only be used if persistent buffer is disabled (*EnablePersistentBuffer=0*).|
|ControlSocket| |no| |/tmp/agent.sock|The control socket, used to send runtime commands with '-R' option.|
|DebugLevel|<|no|0-5|3|Specifies debug level:<br>0 - basic information about starting and stopping of Zabbix processes<br>1 - critical information<br>2 - error information<br>3 - warnings<br>4 - for debugging (produces lots of information)<br>5 - extended debugging (produces even more information)|
|DenyKey|<|no| | |Deny execution of those item keys that match a pattern. Key pattern is a wildcard expression that supports "\*" character to match any number of any characters.<br>Multiple key matching rules may be defined in combination with AllowKey. The parameters are processed one by one according to their appearance order.<br>This parameter is supported since Zabbix 5.0.0.<br>See also: [Restricting agent checks](/manual/config/items/restrict_checks).|
|EnablePersistentBuffer|<|no|0-1|0|Enable usage of local persistent storage for active items.<br>0 - disabled<br>1 - enabled<br>If persistent storage is disabled, the memory buffer will be used.|
|ForceActiveChecksOnStart|<|no|0-1|0 |Perform active checks immediately after restart for the first received configuration.<br>0 - disabled<br>1 - enabled<br>Also available as per plugin configuration parameter, for example: `Plugins.Uptime.System.ForceActiveChecksOnStart=1` <br> Supported since Zabbix 6.0.2. |
|HostInterface| |no|0-255 characters| |Optional parameter that defines host interface.<br>Host interface is used at host autoregistration process.<br>An agent will issue an error and not start if the value is over the limit of 255 characters.<br>If not defined, value will be acquired from HostInterfaceItem.<br>Supported since Zabbix 4.4.0.|
|HostInterfaceItem|<|no| | |Optional parameter that defines an item used for getting host interface.<br>Host interface is used at host autoregistration process.<br>During an autoregistration request an agent will log a warning message if the value returned by specified item is over limit of 255 characters.<br>The [*system.run[]*](/manual/config/items/itemtypes/zabbix_agent#system-data) item is supported regardless of AllowKey/DenyKey values.<br>This option is only used when HostInterface is not defined.<br>Supported since Zabbix 4.4.0.|
|HostMetadata|<|no|0-255 characters| |Optional parameter that defines host metadata. Host metadata is used at host autoregistration process.<br>An agent will issue an error and not start if the specified value is over the limit or a non-UTF-8 string.<br>If not defined, the value will be acquired from HostMetadataItem.<br>Multi-line metadata is not supported — the output will be truncated at the first line break.|
|HostMetadataItem|<|no| | |Optional parameter that defines an item used for getting host metadata. Host metadata item value is retrieved on each autoregistration attempt for host autoregistration process.<br>During an autoregistration request an agent will log a warning message if the value returned by the specified item is over the limit of 255 characters.<br>This option is only used when HostMetadata is not defined.<br>Supports UserParameters and aliases. Supports [*system.run[]*](/manual/config/items/itemtypes/zabbix_agent#system-data) regardless of AllowKey/DenyKey values.<br>The value returned by the item must be a UTF-8 string otherwise it will be ignored.<br>Multi-line metadata is not supported — the output will be truncated at the first line break.|
|Hostname|<|no| |Set by HostnameItem|List of comma-delimited unique, case-sensitive hostnames.<br>Required for active checks and must match hostnames as configured on the server. Value is acquired from HostnameItem if undefined.<br>Allowed characters: alphanumeric, '.', ' ', '\_' and '-'.<br>Maximum length: 128 characters per hostname, 2048 characters for the entire line.|
|HostnameItem|<|no| |system.hostname|Item used for generating Hostname if it is not defined. Ignored if Hostname is defined.<br>Does not support UserParameters or aliases, but does support [*system.run[]*](/manual/config/items/itemtypes/zabbix_agent#system-data) regardless of AllowKey/DenyKey values.|
|Include| |no| | |You may include individual files or all files in a directory in the configuration file.<br>During the installation Zabbix will create the include directory in /usr/local/etc, unless modified during the compile time.<br>To only include relevant files in the specified directory, the asterisk wildcard character is supported for pattern matching. For example: `/absolute/path/to/config/files/*.conf`.<br>Since Zabbix 6.0.0 a path can be relative to *zabbix\_agent2.conf* file location.<br>See also: `Include` [parameter behavior](special_notes_include).|
|ListenIP|<|no| |0.0.0.0|List of comma-delimited IP addresses that the agent should listen on.<br>The first IP address is sent to Zabbix server, if connecting to it, to retrieve the list of active checks.|
|ListenPort|<|no|1024-32767|10050|Agent will listen on this port for connections from the server.|
|LogFile|<|yes, if LogType is set to *file*, otherwise<br>no| |/tmp/zabbix\_agent2.log|Log file name if LogType is 'file'.|
|LogFileSize|<|no|0-1024|1|Maximum size of log file in MB.<br>0 - disable automatic log rotation.<br>*Note*: If the log file size limit is reached and file rotation fails, for whatever reason, the existing log file is truncated and started anew.|
|LogType|<|no| |file|Specifies where log messages are written to:<br>*system* - syslog,<br>*file* - file specified by LogFile parameter,<br>*console* - standard output.|
|PersistentBufferFile|<|no| | |The file, where Zabbix Agent2 should keep SQLite database.<br>Must be a full filename.<br>This parameter is only used if persistent buffer is enabled (*EnablePersistentBuffer=1*).|
|PersistentBufferPeriod| |no|1m-365d|1h|The time period for which data should be stored, when there is no connection to the server or proxy. Older data will be lost. Log data will be preserved.<br>This parameter is only used if persistent buffer is enabled (*EnablePersistentBuffer=1*).|
|PidFile|<|no| |/tmp/zabbix\_agent2.pid|Name of PID file.|
|Plugin|<|no| | |Since Zabbix 6.0.0 most of the plugins have their own [configuration files](/manual/appendix/config/zabbix_agent2_plugins). The agent configuration file contains plugin parameters listed below.|
| |Plugins.Log.MaxLinesPerSecond|no|1-1000|20|Maximum number of new lines the agent will send per second to Zabbix server or proxy when processing 'log' and 'logrt' or 'log*.count' active checks.<br>The provided value will be overridden by the parameter 'maxlines',<br>provided in 'log', 'logrt' or 'log*.count' item key.<br>*Note*: Zabbix will process 10 times more new lines than set in *MaxLinesPerSecond* to seek the required string in log items.<br>This parameter is supported since 4.4.2 and replaces MaxLinesPerSecond.|
|^|Plugins.SystemRun.LogRemoteCommands|no| |0|Enable logging of executed shell commands as warnings.<br>0 - disabled<br>1 - enabled<br>Commands will be logged only if executed remotely. Log entries will not be created if system.run\[\] is launched locally by HostMetadataItem, HostInterfaceItem or HostnameItem parameters.<br>This parameter is supported since 4.4.2 and replaces LogRemoteCommands.|
|PluginSocket|<|no| |/tmp/agent.plugin.sock |Path to Unix socket for loadable plugin communications.|
|PluginTimeout|<|no|1-30 |Global timeout |Timeout for connections with loadable plugins.|
|RefreshActiveChecks|<|no|60-3600|120|How often the list of active checks is refreshed, in seconds.<br>Note that after failing to refresh active checks the next refresh will be attempted after 60 seconds.|
|Server|<|no| | |List of comma-delimited IP addresses, optionally in CIDR notation, or DNS names of Zabbix servers and Zabbix proxies.<br>Incoming connections will be accepted only from the hosts listed here.<br>If IPv6 support is enabled then '127.0.0.1', '::ffff:127.0.0.1' are treated equally and '::/0' will allow any IPv4 or IPv6 address.<br>'0.0.0.0/0' can be used to allow any IPv4 address.<br><br>If left empty or not set will disable passive checks, and Zabbix agent 2 will not listen on the ListenPort.<br>Example: Server=127.0.0.1,192.168.1.0/24,::1,2001:db8::/32,zabbix.example.com<br>Spaces are allowed.|
|ServerActive|<|no| | |Zabbix server/proxy address or cluster configuration to get active checks from.<br>Server/proxy address is IP address or DNS name and optional port separated by colon.<br>Cluster configuration is one or more server addresses separated by semicolon.<br>Multiple Zabbix servers/clusters and Zabbix proxies can be specified, separated by comma.<br>More than one Zabbix proxy should not be specified from each Zabbix server/cluster.<br>If Zabbix proxy is specified then Zabbix server/cluster for that proxy should not be specified.<br>Multiple comma-delimited addresses can be provided to use several independent Zabbix servers in parallel. Spaces are allowed.<br>If port is not specified, default port is used.<br>IPv6 addresses must be enclosed in square brackets if port for that host is specified.<br>If port is not specified, square brackets for IPv6 addresses are optional.<br>If this parameter is not specified, active checks are disabled.<br>Example for Zabbix proxy:<br>ServerActive=127.0.0.1:10051<br>Example for multiple servers:<br>ServerActive=127.0.0.1:20051,zabbix.domain,\[::1\]:30051,::1,\[12fc::1\]<br>Example for high availability:<br>ServerActive=zabbix.cluster.node1;zabbix.cluster.node2:20051;zabbix.cluster.node3<br>Example for high availability with two clusters and one server:<br>ServerActive=zabbix.cluster.node1;zabbix.cluster.node2:20051,zabbix.cluster2.node1;zabbix.cluster2.node2,zabbix.domain|
|SourceIP|<|no| | |Source IP address for:<br>- outgoing connections to Zabbix server or Zabbix proxy;<br>- making connections while executing some items (web.page.get, net.tcp.port, etc.)|
|StatusPort|<|no|1024-32767| |If set, agent will listen on this port for HTTP status requests (http://localhost:<port>/status).|
|Timeout|<|no|1-30|3|Spend no more than Timeout seconds on processing.|
|TLSAccept|<|yes, if TLS certificate or PSK parameters are defined (even for *unencrypted* connection), otherwise no| | |What incoming connections to accept. Used for a passive checks. Multiple values can be specified, separated by comma:<br>*unencrypted* - accept connections without encryption (default)<br>*psk* - accept connections with TLS and a pre-shared key (PSK)<br>*cert* - accept connections with TLS and a certificate|
|TLSCAFile|<|no| | |Full pathname of a file containing the top-level CA(s) certificates for peer certificate verification, used for encrypted communications between Zabbix components.|
|TLSCertFile|<|no| | |Full pathname of a file containing the agent certificate or certificate chain, used for encrypted communications with Zabbix components.|
|TLSConnect|<|yes, if TLS certificate or PSK parameters are defined (even for *unencrypted* connection), otherwise no| | |How the agent should connect to Zabbix server or proxy. Used for active checks. Only one value can be specified:<br>*unencrypted* - connect without encryption (default)<br>*psk* - connect using TLS and a pre-shared key (PSK)<br>*cert* - connect using TLS and a certificate|
|TLSCRLFile|<|no| | |Full pathname of a file containing revoked certificates. This parameter is used for encrypted communications with Zabbix components.|
|TLSKeyFile|<|no| | |Full pathname of a file containing the agent private key used for encrypted communications with Zabbix components.|
|TLSPSKFile|<|no| | |Full pathname of a file containing the agent pre-shared key used for encrypted communications with Zabbix components.|
|TLSPSKIdentity|<|no| | |Pre-shared key identity string, used for encrypted communications with Zabbix server.|
|TLSServerCertIssuer|<|no| | |Allowed server (proxy) certificate issuer.|
|TLSServerCertSubject|<|no| | |Allowed server (proxy) certificate subject.|
|UnsafeUserParameters|<|no|0,1|0|Allow all characters to be passed in arguments to user-defined parameters.<br>The following characters are not allowed:<br>\\ ' " \` \* ? \[ \] { } \~ $ ! & ; ( ) < > \| \# @<br>Additionally, newline characters are not allowed.|
|UserParameter|<|no| | |User-defined parameter to monitor. There can be several user-defined parameters.<br>Format: UserParameter=<key>,<shell command><br>Note that shell command must not return empty string or EOL only.<br>Shell commands may have relative paths, if UserParameterDir parameter is specified.<br>Examples:<br>UserParameter=system.test,who\|wc -l<br>UserParameter=check\_cpu,./custom\_script.sh|
|UserParameterDir|<|no| | |Default search path for UserParameter commands. If used, the agent will change its working directory to the one specified here before executing a command. Thereby, UserParameter commands can have a relative `./` prefix instead of a full path.<br>Only one entry is allowed.<br>Example: UserParameterDir=/opt/myscripts|

[comment]: # ({/65ade290-d34644cb})