1 Zabbix agent

Overview

This section provides details on the item keys that use communication with Zabbix agent for data gathering.

There are passive and active agent checks. When configuring an item, you can select the required type:

• Zabbix agent - for passive checks
• Zabbix agent (active) - for active checks

Note that all item keys supported by Zabbix agent on Windows are also supported by the new generation Zabbix agent 2. See the additional item keys that you can use with the agent 2 only.

Supported item keys

The item keys that you can use with Zabbix agent are listed below.

The item keys are listed without parameters and additional information. Click on the item key to see the full details.

Supported platforms

Except where specified differently in the item details, the agent items (and all parameters) are supported on:

• Linux
• FreeBSD
• Solaris
• HP-UX
• AIX
• Tru64
• MacOS X
• OpenBSD
• NetBSD

Many agent items are also supported on Windows. See the Windows agent item page for details.

Item key details

Parameters without angle brackets are mandatory. Parameters marked with angle brackets < > are optional.

kernel.maxfiles

The maximum number of opened files supported by OS.
Return value: Integer.
Supported platforms: Linux, FreeBSD, MacOS X, OpenBSD, NetBSD.

kernel.maxproc

The maximum number of processes supported by OS.
Return value: Integer.
Supported platforms: Linux 2.6 and later, FreeBSD, Solaris, MacOS X, OpenBSD, NetBSD.

kernel.openfiles

The number of currently open file descriptors.
Return value: Integer.
Supported platforms: Linux (the item may work on other UNIX-like platforms).

log[file,<regexp>,<encoding>,<maxlines>,<mode>,<output>,<maxdelay>,<options>,<persistent dir>]

The monitoring of a log file.
Return value: Log.
See supported platforms.

Parameters:

• file - the full path and name of a log file;

• regexp - a regular expression describing the required pattern;

• encoding - the code page identifier;

• maxlines - the maximum number of new lines per second the agent will send to Zabbix server or proxy. This parameter overrides the value of ‘MaxLinesPerSecond’ in zabbix_agentd.conf;

• mode - possible values: all (default) or skip - skip processing of older data (affects only newly created items);
  output - an optional output formatting template. The \0 escape sequence is replaced with the matched part of text (from the first character where match begins until the character where match ends) while an \N (where N=1…9) escape sequence is replaced with Nth matched group (or an empty string if the N exceeds the number of captured groups).

• maxdelay - the maximum delay in seconds. Type: float. Values: 0 - (default) never ignore log file lines; > 0.0 - ignore older lines in order to get the most recent lines analyzed within “maxdelay” seconds. Read the maxdelay notes before using it!

• options - additional options:
  mtime-noreread - non-unique records, reread only if the file size changes (ignore modification time change). (This parameter is deprecated since 5.0.2, because now mtime is ignored.)

• persistent dir (only in zabbix_agentd on Unix systems; not supported in Zabbix agent 2) - the absolute pathname of directory where to store persistent files. See also additional notes on persistent files.

Comments:

• The item must be configured as an active check;
• If the file is missing or permissions do not allow access, the item turns unsupported;
• If output is left empty - the whole line containing the matched text is returned. Note that all global regular expression types except ‘Result is TRUE’ always return the whole matched line and the output parameter is ignored.
• Content extraction using the output parameter takes place on the agent.

Examples:

log[/var/log/syslog]
       log[/var/log/syslog,error]
       log[/home/zabbix/logs/logfile,,,100]

Example of using the output parameter for extracting a number from log record:

log[/app1/app.log,"task run [0-9.]+ sec, processed ([0-9]+) records, [0-9]+ errors",,,,\1] #this item will match a log record "2015-11-13 10:08:26 task run 6.08 sec, processed 6080 records, 0 errors" and send only '6080' to server. Because a numeric value is being sent, the "Type of information" for this item can be set to "Numeric (unsigned)" and the value can be used in graphs, triggers etc.

Example of using the output parameter for rewriting a log record before sending to server:

log[/app1/app.log,"([0-9 :-]+) task run ([0-9.]+) sec, processed ([0-9]+) records, ([0-9]+) errors",,,,"\1 RECORDS: \3, ERRORS: \4, DURATION: \2"] #this item will match a log record "2015-11-13 10:08:26 task run 6.08 sec, processed 6080 records, 0 errors" and send a modified record "2015-11-13 10:08:26 RECORDS: 6080, ERRORS: 0, DURATION: 6.08" to the server.

log.count[file,<regexp>,<encoding>,<maxproclines>,<mode>,<maxdelay>,<options>,<persistent dir>]

The count of matched lines in a monitored log file.
Return value: Integer.
See supported platforms.

Parameters:

• file - the full path and name of log file;

• regexp - a regular expression describing the required pattern;

• encoding - the code page identifier;

• maxproclines - the maximum number of new lines per second the agent will analyze (cannot exceed 10000). The default value is 10*‘MaxLinesPerSecond’ in zabbix_agentd.conf.

• mode - possible values: all (default) or skip - skip processing of older data (affects only newly created items).

• maxdelay - the maximum delay in seconds. Type: float. Values: 0 - (default) never ignore log file lines; > 0.0 - ignore older lines in order to get the most recent lines analyzed within “maxdelay” seconds. Read the maxdelay notes before using it!

• options - additional options:
  mtime-noreread - non-unique records, reread only if the file size changes (ignore modification time change). (This parameter is deprecated since 5.0.2, because now mtime is ignored.)

• persistent dir (only in zabbix_agentd on Unix systems; not supported in Zabbix agent 2) - the absolute pathname of directory where to store persistent files. See also additional notes on persistent files.

Comments:

• The item must be configured as an active check;
• Matching lines are counted in the new lines since the last log check by the agent, and thus depend on the item update interval;
• If the file is missing or permissions do not allow access, the item turns unsupported.

logrt[file regexp,<regexp>,<encoding>,<maxlines>,<mode>,<output>,<maxdelay>,<options>,<persistent dir>]

The monitoring of a log file that is rotated.
Return value: Log.
See supported platforms.

Parameters:

• file regexp - the absolute path to file and the file name described by a regular expression. Note that only the file name is a regular expression.

• regexp - a regular expression describing the required content pattern;

• encoding - the code page identifier;

• maxlines - the maximum number of new lines per second the agent will send to Zabbix server or proxy. This parameter overrides the value of ‘MaxLinesPerSecond’ in zabbix_agentd.conf.

• mode - possible values: all (default) or skip - skip processing of older data (affects only newly created items).

• output - an optional output formatting template. The \0 escape sequence is replaced with the matched part of text (from the first character where match begins until the character where match ends) while an \N (where N=1…9) escape sequence is replaced with Nth matched group (or an empty string if the N exceeds the number of captured groups).

• maxdelay - the maximum delay in seconds. Type: float. Values: 0 - (default) never ignore log file lines; > 0.0 - ignore older lines in order to get the most recent lines analyzed within “maxdelay” seconds. Read the maxdelay notes before using it!

• options - the type of log file rotation and other options. Possible values:
  rotate (default),
  copytruncate - note that copytruncate cannot be used together with maxdelay. In this case maxdelay must be 0 or not specified; see copytruncate notes,
  mtime-reread - non-unique records, reread if modification time or size changes (default),
  mtime-noreread - non-unique records, reread only if the size changes (ignore modification time change).

• persistent dir (only in zabbix_agentd on Unix systems; not supported in Zabbix agent 2) - the absolute pathname of directory where to store persistent files. See also additional notes on persistent files.

Comments:

• The item must be configured as an active check;
• Log rotation is based on the last modification time of files;
• Note that logrt is designed to work with one currently active log file, with several other matching inactive files rotated. If, for example, a directory has many active log files, a separate logrt item should be created for each one. Otherwise if one logrt item picks up too many files it may lead to exhausted memory and a crash of monitoring.
• If output is left empty - the whole line containing the matched text is returned. Note that all global regular expression types except ‘Result is TRUE’ always return the whole matched line and the output parameter is ignored.
• Content extraction using the output parameter takes place on the agent.

Examples:

logrt["/home/zabbix/logs/^logfile[0-9]{1,3}$",,,100] #this item will match a file like "logfile1" (will not match ".logfile1")
       logrt["/home/user/^logfile_.*_[0-9]{1,3}$","pattern_to_match","UTF-8",100] #this item will collect data from files such "logfile_abc_1" or "logfile__001"

Example of using the output parameter for extracting a number from log record:

logrt[/app1/^test.*log$,"task run [0-9.]+ sec, processed ([0-9]+) records, [0-9]+ errors",,,,\1] #this item will match a log record "2015-11-13 10:08:26 task run 6.08 sec, processed 6080 records, 0 errors" and send only '6080' to server. Because a numeric value is being sent, the "Type of information" for this item can be set to "Numeric (unsigned)" and the value can be used in graphs, triggers etc.

Example of using the output parameter for rewriting a log record before sending to server:

logrt[/app1/^test.*log$,"([0-9 :-]+) task run ([0-9.]+) sec, processed ([0-9]+) records, ([0-9]+) errors",,,,"\1 RECORDS: \3, ERRORS: \4, DURATION: \2"] #this item will match a log record "2015-11-13 10:08:26 task run 6.08 sec, processed 6080 records, 0 errors" and send a modified record "2015-11-13 10:08:26 RECORDS: 6080, ERRORS: 0, DURATION: 6.08" to server. |

logrt.count[file regexp,<regexp>,<encoding>,<maxproclines>,<mode>,<maxdelay>,<options>,<persistent dir>]

The count of matched lines in a monitored log file that is rotated.
Return value: Integer.
See supported platforms.

Parameters:

• file regexp - the absolute path to file and regular expression describing the file name pattern;

• regexp - a regular expression describing the required pattern;

• encoding - the code page identifier;

• maxproclines - the maximum number of new lines per second the agent will analyze (cannot exceed 10000). The default value is 10*‘MaxLinesPerSecond’ in zabbix_agentd.conf.

• mode - possible values: all (default) or skip - skip processing of older data (affects only newly created items).

• maxdelay - the maximum delay in seconds. Type: float. Values: 0 - (default) never ignore log file lines; > 0.0 - ignore older lines in order to get the most recent lines analyzed within “maxdelay” seconds. Read the maxdelay notes before using it!

• options - the type of log file rotation and other options. Possible values:
  rotate (default),
  copytruncate - note that copytruncate cannot be used together with maxdelay. In this case maxdelay must be 0 or not specified; see copytruncate notes,
  mtime-reread - non-unique records, reread if modification time or size changes (default),
  mtime-noreread - non-unique records, reread only if the size changes (ignore modification time change).

• persistent dir (only in zabbix_agentd on Unix systems; not supported in Zabbix agent 2) - the absolute pathname of directory where to store persistent files. See also additional notes on persistent files.

Comments:

• The item must be configured as an active check;
• Matching lines are counted in the new lines since the last log check by the agent, and thus depend on the item update interval;
• Log rotation is based on the last modification time of files..

modbus.get[endpoint,<slave id>,<function>,<address>,<count>,<type>,<endianness>,<offset>]

Reads Modbus data.
Return value: JSON object.
Supported platforms: Linux.

Parameters:

• endpoint - the endpoint defined as protocol://connection_string;

• slave id - the slave ID;

• function - the Modbus function;

• address - the address of first registry, coil or input;

• count - the number of records to read;

• type - the type of data;

• endianness - the endianness configuration;

• offset - the number of registers, starting from ‘address’, the results of which will be discarded.

See a detailed description of parameters.

net.dns[<ip>,name,<type>,<timeout>,<count>,<protocol>]

Checks if the DNS service is up.
Return values: 0 - DNS is down (server did not respond or DNS resolution failed); 1 - DNS is up.
See supported platforms.

Parameters:

• ip - the IP address of DNS server (leave empty for the default DNS server, ignored on Windows unless using Zabbix agent 2);
• name - the DNS name to query;
• type - the record type to be queried (default is SOA);
• timeout (ignored on Windows unless using Zabbix agent 2) - the timeout for the request in seconds (default is 1 second);
• count (ignored on Windows unless using Zabbix agent 2) - the number of tries for the request (default is 2);
• protocol - the protocol used to perform DNS queries: udp (default) or tcp.

Comments:

• The possible values for type are: ANY, A, NS, CNAME, MB, MG, MR, PTR, MD, MF, MX, SOA, NULL, WKS (not supported for Zabbix agent on Windows, Zabbix agent 2 on all OS), HINFO, MINFO, TXT, SRV
• Internationalized domain names are not supported, please use IDNA encoded names instead.

Example:

net.dns[198.51.100.1,example.com,MX,2,1]

net.dns.record[<ip>,name,<type>,<timeout>,<count>,<protocol>]

Performs a DNS query.
Return value: a character string with the required type of information.
See supported platforms.

Parameters:

• ip - the IP address of DNS server (leave empty for the default DNS server, ignored on Windows unless using Zabbix agent 2);
• name - the DNS name to query;
• type - the record type to be queried (default is SOA);
• timeout (ignored on Windows unless using Zabbix agent 2) - the timeout for the request in seconds (default is 1 second);
• count (ignored on Windows unless using Zabbix agent 2) - the number of tries for the request (default is 2);
• protocol - the protocol used to perform DNS queries: udp (default) or tcp.

Comments:

• The possible values for type are:
  ANY, A, NS, CNAME, MB, MG, MR, PTR, MD, MF, MX, SOA, NULL, WKS (not supported for Zabbix agent on Windows, Zabbix agent 2 on all OS), HINFO, MINFO, TXT, SRV
• Internationalized domain names are not supported, please use IDNA encoded names instead.

Example:

net.dns.record[198.51.100.1,example.com,MX,2,1]

net.if.collisions[if]

The number of out-of-window collisions.
Return value: Integer.
Supported platforms: Linux, FreeBSD, Solaris, AIX, MacOS X, OpenBSD, NetBSD. Root privileges are required on NetBSD.

Parameter:

• if - network interface name

net.if.discovery

The list of network interfaces. Used for low-level discovery.
Return value: JSON object.
Supported platforms: Linux, FreeBSD, Solaris, HP-UX, AIX, OpenBSD, NetBSD.

net.if.in[if,<mode>]

The incoming traffic statistics on a network interface.
Return value: Integer.
Supported platforms: Linux, FreeBSD, Solaris5, HP-UX, AIX, MacOS X, OpenBSD, NetBSD. Root privileges are required on NetBSD.

Parameters:

• if - network interface name (Unix); network interface full description or IPv4 address; or, if in braces, network interface GUID (Windows);
• mode - possible values:
  bytes - number of bytes (default)
  packets - number of packets
  errors - number of errors
  dropped - number of dropped packets
  overruns (fifo) - the number of FIFO buffer errors
  frame - the number of packet framing errors
  compressed - the number of compressed packets received by the device driver
  multicast - the number of multicast frames received by the device driver

Comments:

• You may use this key with the Change per second preprocessing step in order to get the bytes-per-second statistics;
• The dropped mode is supported only on Linux, FreeBSD, HP-UX, MacOS X, OpenBSD, NetBSD;
• The overruns, frame, compressed, multicast modes are supported only on Linux;
• On HP-UX this item does not provide details on loopback interfaces (e.g. lo0).

Examples:

net.if.in[eth0]
       net.if.in[eth0,errors]

net.if.out[if,<mode>]

The outgoing traffic statistics on a network interface.
Return value: Integer.
Supported platforms: Linux, FreeBSD, Solaris5, HP-UX, AIX, MacOS X, OpenBSD, NetBSD. Root privileges are required on NetBSD.

Parameters:

• if - network interface name (Unix); network interface full description or IPv4 address; or, if in braces, network interface GUID (Windows);
• mode - possible values:
  bytes - number of bytes (default)
  packets - number of packets
  errors - number of errors
  dropped - number of dropped packets
  overruns (fifo) - the number of FIFO buffer errors
  collisions (colls) - the number of collisions detected on the interface
  carrier - the number of carrier losses detected by the device driver
  compressed - the number of compressed packets transmitted by the device driver

Comments:

• You may use this key with the Change per second preprocessing step in order to get the bytes-per-second statistics;
• The dropped mode is supported only on Linux, HP-UX;
• The overruns, collision, carrier, compressed modes are supported only on Linux;
• On HP-UX this item does not provide details on loopback interfaces (e.g. lo0).

Examples:

net.if.out[eth0]
       net.if.out[eth0,errors]

net.if.total[if,<mode>]

The sum of incoming and outgoing traffic statistics on a network interface.
Return value: Integer.
Supported platforms: Linux, FreeBSD, Solaris5, HP-UX, AIX, MacOS X, OpenBSD, NetBSD. Root privileges are required on NetBSD.

Parameters:

• if - network interface name (Unix); network interface full description or IPv4 address; or, if in braces, network interface GUID (Windows);
• mode - possible values:
  bytes - number of bytes (default)
  packets - number of packets
  errors - number of errors
  dropped - number of dropped packets
  overruns (fifo) - the number of FIFO buffer errors
  collisions (colls) - the number of collisions detected on the interface
  compressed - the number of compressed packets transmitted or received by the device driver

Comments:

• You may use this key with the Change per second preprocessing step in order to get the bytes-per-second statistics;
• The dropped mode is supported only on Linux, HP-UX. Dropped packets are supported only if both net.if.in and net.if.out work for dropped packets on your platform.
• The overruns, collision, compressed modes are supported only on Linux;
• On HP-UX this item does not provide details on loopback interfaces (e.g. lo0).

Examples:

net.if.total[eth0]
       net.if.total[eth0,errors]

net.tcp.listen[port]

Checks if this TCP port is in LISTEN state.
Return values: 0 - it is not in LISTEN state; 1 - it is in LISTEN state.
Supported platforms: Linux, FreeBSD, Solaris, MacOS X.

Parameter:

• port - TCP port number

On Linux kernels 2.6.14 and above, the information about listening TCP sockets is obtained from the kernel’s NETLINK interface, if possible. Otherwise, the information is retrieved from /proc/net/tcp and /roc/net/tcp6 files.

Example:

net.tcp.listen[80]

net.tcp.port[<ip>,port]

Checks if it is possible to make a TCP connection to the specified port.
Return values: 0 - cannot connect; 1 - can connect.
See supported platforms.

Parameters:

• ip - the IP address or DNS name (default is 127.0.0.1);
• port - the port number.

Comments:

• For simple TCP performance testing use net.tcp.service.perf[tcp,<ip>,<port>];
• These checks may result in additional messages in system daemon logfiles (SMTP and SSH sessions being logged usually).

Example:

net.tcp.port[,80] #this item can be used to test the web server availability running on port 80

net.tcp.service[service,<ip>,<port>]

Checks if a service is running and accepting TCP connections.
Return values: 0 - service is down; 1 - service is running.
See supported platforms.

Parameters:

• service - ssh, ldap, smtp, ftp, http, pop, nntp, imap, tcp, https, or telnet (see details);
• ip - the IP address or DNS name (default is 127.0.0.1);
• port - the port number (by default the standard service port number is used).

Comments:

• These checks may result in additional messages in system daemon logfiles (SMTP and SSH sessions being logged usually);
• Checking of encrypted protocols (like IMAP on port 993 or POP on port 995) is currently not supported. As a workaround, please use net.tcp.port[] for checks like these.
• Checking of LDAP and HTTPS on Windows is only supported by Zabbix agent 2;
• The telnet check looks for a login prompt (‘:’ at the end).

Example:

net.tcp.service[ftp,,45] #this item can be used to test the availability of FTP server on TCP port 45

net.tcp.service.perf[service,<ip>,<port>]

Checks the performance of a TCP service.
Return values: Float (0 - service is down; seconds - the number of seconds spent while connecting to the service).
See supported platforms.

Parameters:

• service - ssh, ldap, smtp, ftp, http, pop, nntp, imap, tcp, https, or telnet (see details);
• ip - the IP address or DNS name (default is 127.0.0.1);
• port - the port number (by default the standard service port number is used).

Comments:

• Checking of encrypted protocols (like IMAP on port 993 or POP on port 995) is currently not supported. As a workaround, please use net.tcp.service.perf[tcp,<ip>,<port>] for checks like these.
• The telnet check looks for a login prompt (‘:’ at the end).

Example:

net.tcp.service.perf[ssh] #this item can be used to test the speed of initial response from the SSH server

net.tcp.socket.count[<laddr>,<lport>,<raddr>,<rport>,<state>]

Returns the number of TCP sockets that match parameters.
Return value: Integer.
Supported platforms: Linux.

Parameters:

• laddr - the local IPv4/6 address or CIDR subnet;
• lport - the local port number or service name;
• raddr - the remote IPv4/6 address or CIDR subnet;
• rport - the remote port number or service name;
• state - the connection state (established, syn_sent, syn_recv, fin_wait1, fin_wait2, time_wait, close, close_wait, last_ack, listen, closing).

Example:

net.tcp.socket.count[,80,,,established] #the number of connections to local TCP port 80 in the established state

net.udp.listen[port]

Checks if this UDP port is in LISTEN state.
Return values: 0 - it is not in LISTEN state; 1 - it is in LISTEN state.
Supported platforms: Linux, FreeBSD, Solaris, MacOS X.

Parameter:

• port - UDP port number

Example:

net.udp.listen[68]

net.udp.service[service,<ip>,<port>]

Checks if a service is running and responding to UDP requests.
Return values: 0 - service is down; 1 - service is running.
See supported platforms.

Parameters:

• service - ntp (see details);
• ip - the IP address or DNS name (default is 127.0.0.1);
• port - the port number (by default the standard service port number is used).

Example:

net.udp.service[ntp,,45] #this item can be used to test the availability of NTP service on UDP port 45

net.udp.service.perf[service,<ip>,<port>]

Checks the performance of a UDP service.
Return values: Float (0 - service is down; seconds - the number of seconds spent waiting for response from the service).
See supported platforms.

Parameters:

• service - ntp (see details);
• ip - the IP address or DNS name (default is 127.0.0.1);
• port - the port number (by default the standard service port number is used).

Example:

net.udp.service.perf[ntp] #this item can be used to test response time from NTP service

net.udp.socket.count[<laddr>,<lport>,<raddr>,<rport>,<state>]

Returns the number of UDP sockets that match parameters.
Return value: Integer.
Supported platforms: Linux.

Parameters:

• laddr - the local IPv4/6 address or CIDR subnet;
• lport - the local port number or service name;
• raddr - the remote IPv4/6 address or CIDR subnet;
• rport - the remote port number or service name;
• state - the connection state (established, unconn).

Example:

net.udp.socket.count[,,,,established] #returns the number of UDP sockets in the connected state

proc.cpu.util[<name>,<user>,<type>,<cmdline>,<mode>,<zone>]

The process CPU utilization percentage.
Return value: Float.
Supported platforms: Linux, Solaris6.

Parameters:

• name - the process name (default is all processes);
• user - the user name (default is all users);
• type - the CPU utilization type: total (default), user, or system;
• cmdline - filter by command line (it is a regular expression);
• mode - the data gathering mode: avg1 (default), avg5, or avg15;
• zone - the target zone: current (default) or all. This parameter is supported on Solaris only.

Comments:

• The returned value is based on a single CPU core utilization percentage. For example, the CPU utilization of a process fully using two cores is 200%.
• The process CPU utilization data is gathered by a collector which supports the maximum of 1024 unique (by name, user and command line) queries. Queries not accessed during the last 24 hours are removed from the collector.
• When setting the zone parameter to current (or default) in case the agent has been compiled on a Solaris without zone support, but running on a newer Solaris where zones are supported, then the agent will return NOTSUPPORTED (the agent cannot limit results to only the current zone). However, all is supported in this case.

Examples:

proc.cpu.util[,root] #CPU utilization of all processes running under the "root" user
       proc.cpu.util[zabbix_server,zabbix] #CPU utilization of all zabbix_server processes running under the zabbix user

proc.get[<name>,<user>,<cmdline>,<mode>]

The list of OS processes and their parameters. Can be used for low-level discovery.
Return value: JSON object.
Supported platforms: Linux, FreeBSD, Windows, OpenBSD, NetBSD.

Parameters:

• name - the process name (default all processes);
• user - the user name (default all users);
• cmdline - filter by command line (it is a regular expression). This parameter is not supported for Windows; on other platforms it is not supported if mode is set to ‘summary’.
• mode - possible values:
  process (default), thread (not supported for NetBSD), summary. See a list of process parameters returned for each mode and OS.

Comments:

• If a value cannot be retrieved, for example, because of an error (process already died, lack of permissions, system call failure), -1 will be returned;
• See notes on selecting processes with name and cmdline parameters (Linux-specific).

Examples:

proc.get[zabbix,,,process] #list of all Zabbix processes, returns one entry per PID
       proc.get[java,,,thread] #list of all Java processes, returns one entry per thread
       proc.get[zabbix,,,summary] #combined data for Zabbix processes of each type, returns one entry per process name

proc.mem[<name>,<user>,<mode>,<cmdline>,<memtype>]

The memory used by the process in bytes.
Return value: Integer - with mode as max, min, sum; Float - with mode as avg
Supported platforms: Linux, FreeBSD, Solaris, AIX, Tru64, OpenBSD, NetBSD.

Parameters:

• name - the process name (default is all processes);
• user - the user name (default is all users);
• mode - possible values: avg, max, min, or sum (default);
• cmdline - filter by command line (it is a regular expression);
• memtype - the type of memory used by process

Comments:

• The memtype parameter is supported only on Linux, FreeBSD, Solaris6, AIX;

• When several processes use shared memory, the sum of memory used by processes may result in large, unrealistic values.

  See notes on selecting processes with name and cmdline parameters (Linux-specific).

  When this item is invoked from the command line and contains a command line parameter (e.g. using the agent test mode: zabbix_agentd -t proc.mem[,,,apache2]), one extra process will be counted, as the agent will count itself.

Examples:

proc.mem[,root] #the memory used by all processes running under the "root" user
       proc.mem[zabbix_server,zabbix] #the memory used by all zabbix_server processes running under the zabbix user
       proc.mem[,oracle,max,oracleZABBIX] #the memory used by the most memory-hungry process running under Oracle having oracleZABBIX in its command line

proc.num[<name>,<user>,<state>,<cmdline>,<zone>]

The number of processes.
Return value: Integer.
Supported platforms: Linux, FreeBSD, Solaris6, HP-UX, AIX, Tru64, OpenBSD, NetBSD.

Parameters:

• name - the process name (default is all processes);
• user - the user name (default is all users);
• state - possible values:
  all (default),
  disk - uninterruptible sleep,
  run - running,
  sleep - interruptible sleep,
  trace - stopped,
  zomb - zombie;
• cmdline - filter by command line (it is a regular expression);
• zone - the target zone: current (default), or all. This parameter is supported on Solaris only.

Comments:

• The disk and trace state parameters are supported only on Linux, FreeBSD, OpenBSD, NetBSD;
• When this item is invoked from the command line and contains a command line parameter (e.g. using the agent test mode: zabbix_agentd -t proc.num[,,,apache2]), one extra process will be counted, as the agent will count itself;
• When setting the zone parameter to current (or default) in case the agent has been compiled on a Solaris without zone support, but running on a newer Solaris where zones are supported, then the agent will return NOTSUPPORTED (the agent cannot limit results to only the current zone). However, all is supported in this case.
• See notes on selecting processes with name and cmdline parameters (Linux-specific).

Examples:

proc.num[,mysql] #the number of processes running under the mysql user
       proc.num[apache2,www-data] #the number of apache2 processes running under the www-data user
       proc.num[,oracle,sleep,oracleZABBIX] #the number of processes in sleep state running under Oracle having oracleZABBIX in its command line

sensor[device,sensor,<mode>]

Hardware sensor reading.
Return value: Float.
Supported platforms: Linux, OpenBSD.

Parameters:

• device - the device name, can be a regular expression if mode is omitted;
• sensor - the sensor name, can be a regular expression if mode is omitted;
• mode - possible values: avg, max, or min (if this parameter is omitted, device and sensor are treated verbatim).

Comments:

• Reads /proc/sys/dev/sensors on Linux 2.4;
• Reads /sys/class/hwmon on Linux 2.6+. See a more detailed description of sensor item on Linux.
• Reads the hw.sensors MIB on OpenBSD.

Example:

sensor[w83781d-i2c-0-2d,temp1]
       sensor[cpu0,temp0] #the temperature of one CPU
       sensor["cpu[0-2]$",temp,avg] #the average temperature of the first three CPUs

system.boottime

The system boot time.
Return value: Integer (Unix timestamp).
Supported platforms: Linux, FreeBSD, Solaris, MacOS X, OpenBSD, NetBSD.

system.cpu.discovery

The list of detected CPUs/CPU cores. Used for low-level discovery.
Return value: JSON object.
See supported platforms.

system.cpu.intr

The device interrupts.
Return value: Integer.
Supported platforms: Linux, FreeBSD, Solaris, AIX, OpenBSD, NetBSD.

system.cpu.load[<cpu>,<mode>]

The CPU load).
Return value: Float.
See supported platforms.

Parameters:

• cpu - possible values: all (default) or percpu (the total load divided by online CPU count);
• mode - possible values: avg1 (one-minute average, default), avg5, or avg15.

The percpu parameter is not supported on Tru64.

Example:

system.cpu.load[,avg5]

system.cpu.num[<type>]

The number of CPUs.
Return value: Integer.
Supported platforms: Linux, FreeBSD, Solaris, HP-UX, AIX, MacOS X, OpenBSD, NetBSD.

Parameter:

• type - possible values: online (default) or max

The max type parameter is supported only on Linux, FreeBSD, Solaris, MacOS X.

Example:

system.cpu.num

system.cpu.switches

The count of context switches.
Return value: Integer.
Supported platforms: Linux, FreeBSD, Solaris, AIX, OpenBSD, NetBSD.

system.cpu.util[<cpu>,<type>,<mode>,<logical or physical>]

The CPU utilization percentage.
Return value: Float.
Supported platforms: Linux, FreeBSD, Solaris, HP-UX, AIX, Tru64, OpenBSD, NetBSD.

Parameters:

• cpu - <CPU number> or all (default);
• type - possible values: user (default), idle, nice, system, iowait, interrupt, softirq, steal, guest (on Linux kernels 2.6.24 and above), or guest_nice (on Linux kernels 2.6.33 and above);
• mode - possible values: avg1 (one-minute average, default), avg5, or avg15;
• logical or physical - possible values: logical (default) or physical. This parameter is supported on AIX only.

Comments:

• The nice type parameter is supported only on Linux, FreeBSD, HP-UX, Tru64, OpenBSD, NetBSD.
• The iowait type parameter is supported only on Linux 2.6 and later, Solaris, AIX.
• The interrupt type parameter is supported only on Linux 2.6 and later, FreeBSD, OpenBSD.
• The softirq, steal, guest, guest_nice type parameters are supported only on Linux 2.6 and later.
• The avg5 and avg15 mode parameters are supported on Linux, FreeBSD, Solaris, HP-UX, AIX, OpenBSD, NetBSD.

Example:

system.cpu.util[0,user,avg5]

system.hostname[<type>,<transform>]

The system host name.
Return value: String.
See supported platforms.

Parameters:

• type - possible values: netbios (default on Windows), host (default on Linux) or shorthost (since version 5.4.7; returns part of the hostname before the first dot, a full string for names without dots);
• transform - possible values: none (default) or lower (convert to lowercase).

The value is acquired by taking nodename from the uname() system API output.

Examples of returned values:

system.hostname → linux-w7x1
       system.hostname → example.com
       system.hostname[shorthost] → example

system.hw.chassis[<info>]

The chassis information.
Return value: String.
Supported platforms: Linux.

Parameter:

• info - possible values: full (default), model, serial, type, or vendor

Comments:

• This item key depends on the availability of the SMBIOS table;
• It will try to read the DMI table from sysfs, if sysfs access fails then try reading directly from memory;
• Root permissions are required because the value is acquired by reading from sysfs or memory.

Example:

system.hw.chassis[full] → Hewlett-Packard HP Pro 3010 Small Form Factor PC CZXXXXXXXX Desktop

system.hw.cpu[<cpu>,<info>]

The CPU information.
Return value: String or Integer.
Supported platforms: Linux.

Parameters:

• cpu - <CPU number> or all (default);
• info - possible values: full (default), curfreq, maxfreq, model or vendor.

Comments:

• Gathers info from /proc/cpuinfo and /sys/devices/system/cpu/[cpunum]/cpufreq/cpuinfo_max_freq;
• If a CPU number and curfreq or maxfreq is specified, a numeric value is returned (Hz).

Example:

system.hw.cpu[0,vendor] → AuthenticAMD

system.hw.devices[<type>]

The listing of PCI or USB devices.
Return value: Text.
Supported platforms: Linux.

Parameter:

• type - pci (default) or usb

Returns the output of either the lspci or lsusb utility (executed without any parameters).

Example:

system.hw.devices → 00:00.0 Host bridge: Advanced Micro Devices [AMD] RS780 Host Bridge

system.hw.macaddr[<interface>,<format>]

The listing of MAC addresses.
Return value: String.
Supported platforms: Linux.

Parameters:

• interface - all (default) or a regular expression;
• format - full (default) or short

Comments:

• Lists MAC addresses of the interfaces whose name matches the given interface regular expression (all lists for all interfaces);
• If format is specified as short, interface names and identical MAC addresses are not listed.

Example:

system.hw.macaddr["eth0$",full] → [eth0] 00:11:22:33:44:55

system.localtime[<type>]

The system time.
Return value: Integer - with type as utc; String - with type as local.
See supported platforms.

Parameters:

• type - possible values: utc - (default) the time since the Epoch (00:00:00 UTC, January 1, 1970), measured in seconds or local - the time in the ‘yyyy-mm-dd,hh:mm:ss.nnn,+hh:mm’ format

Must be used as a passive check only.

Example:

system.localtime[local] #create an item using this key and then use it to display the host time in the *Clock* dashboard widget.

system.run[command,<mode>]

Run the specified command on the host.
Return value: Text result of the command or 1 - with mode as nowait (regardless of the command result).
See supported platforms.

Parameters:

• command - command for execution;

• mode - possible values: wait - wait end of execution (default) or nowait - do not wait.

Comments:

• This item is disabled by default. Learn how to enable them;
• Up to 512KB of data can be returned, including the trailing whitespace that is truncated;
• To be processed correctly, the output of the command must be text;
• The return value of the item is standard output together with standard error produced by command. The exit code is not checked. Empty result is allowed.
• See also: Command execution.

Example:

system.run[ls -l /] #return a detailed file list of the root directory

system.stat[resource,<type>]

The system statistics.
Return value: Integer or float.
Supported platforms: AIX.

Parameters:

• ent - the number of processor units this partition is entitled to receive (float);
• kthr,<type> - information about kernel thread states:
  r - average number of runnable kernel threads (float)
  b - average number of kernel threads placed in the Virtual Memory Manager wait queue (float)
• memory,<type> - information about the usage of virtual and real memory:
  avm - active virtual pages (integer)
  fre - size of the free list (integer)
• page,<type> - information about page faults and paging activity:
  fi - file page-ins per second (float)
  fo - file page-outs per second (float)
  pi - pages paged in from paging space (float)
  po - pages paged out to paging space (float)
  fr - pages freed (page replacement) (float)
  sr - pages scanned by page-replacement algorithm (float)
• faults,<type> - trap and interrupt rate:
  in - device interrupts (float)
  sy - system calls (float)
  cs - kernel thread context switches (float)
• cpu,<type> - breakdown of percentage usage of processor time:
  us - user time (float)
  sy - system time (float)
  id - idle time (float)
  wa - idle time during which the system had outstanding disk/NFS I/O request(s) (float)
  pc - number of physical processors consumed (float)
  ec - the percentage of entitled capacity consumed (float)
  lbusy - indicates the percentage of logical processor(s) utilization that occurred while executing at the user and system level (float)
  app - indicates the available physical processors in the shared pool (float)
• disk,<type> - disk statistics:
  bps - indicates the amount of data transferred (read or written) to the drive in bytes per second (integer)
  tps - indicates the number of transfers per second that were issued to the physical disk/tape (float)|

Comments:

• Take note of the following limitations in these items:
  system.stat[cpu,app] - supported only on AIX LPAR of type “Shared”
  system.stat[cpu,ec] - supported on AIX LPAR of type “Shared” and “Dedicated” (“Dedicated” always returns 100 (percent))
  system.stat[cpu,lbusy] - supported only on AIX LPAR of type “Shared”
  system.stat[cpu,pc] - supported on AIX LPAR of type “Shared” and “Dedicated”
  system.stat[ent] - supported on AIX LPAR of type “Shared” and “Dedicated”

system.sw.arch

The software architecture information.
Return value: String.
See supported platforms.

The info is acquired from the uname() function.

Example:

system.sw.arch → i686

system.sw.os[<info>]

The operating system information.
Return value: String.
Supported platforms: Linux, Windows. Supported on Windows since Zabbix 6.4.

Parameter:

• info - possible values: full (default), short, or name

The info is acquired from (note that not all files and options are present in all distributions):

• /proc/version (full) on Linux;
• /proc/version_signature (short) on Linux;
• the PRETTY_NAME parameter from /etc/os-release on Linux-systems supporting it or /etc/issue.net (name);
• the HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion registry key on Windows.

Examples:

system.sw.os[short] → Ubuntu 2.6.35-28.50-generic 2.6.35.11
       system.sw.os[full] → [s|Windows 10 Enterprise 22621.1.amd64fre.ni_release.220506-1250 Build 22621.963]

system.sw.os.get

Detailed information about the operating system (version, type, distribution name, minor and major version, etc).
Return value: JSON object.
Supported platforms: Linux, Windows. Supported since Zabbix 6.4.

system.sw.packages[<regexp>,<manager>,<format>]

The listing of installed packages.
Return value: Text.
Supported platforms: Linux.

Parameters:

• regexp - all (default) or a regular expression;
• manager - all (default) or a package manager;
• format - full (default) or short.

Comments:

• Lists (alphabetically) installed packages whose name matches the given regular expression (all lists them all);
• Supported package managers (executed command):
  dpkg (dpkg —get-selections)
  pkgtool (ls /var/log/packages)
  rpm (rpm -qa)
  pacman (pacman -Q)
• If format is specified as full, packages are grouped by package managers (each manager on a separate line beginning with its name in square brackets);
• If format is specified as short, packages are not grouped and are listed on a single line.

Example:

system.sw.packages[mini,dpkg,short] → python-minimal, python2.6-minimal, ubuntu-minimal

system.sw.packages.get[<regexp>,<manager>]

A detailed listing of installed packages.
Return value: JSON object.
Supported platforms: Linux. Supported since Zabbix 6.4.

Parameters:

• regexp - all (default) or a regular expression;
• manager - all (default) or a package manager (possible values: rpm, dpkg, pkgtool, or pacman).

Comments:

• Returns unformatted JSON with the installed packages whose name matches the given regular expression;
• The output is an array of objects each containing the following keys: name, manager, version, size, architecture, buildtime and installtime (see more details).

system.swap.in[<device>,<type>]

The swap-in (from device into memory) statistics.
Return value: Integer.
Supported platforms: Linux, FreeBSD, OpenBSD.

Parameters:

• device - specify the device used for swapping (Linux only) or all (default);
• type - possible values: count (number of swapins, default on non-Linux platforms), sectors (sectors swapped in), or pages (pages swapped in, default on Linux).

Comments:

• The source of this information is:
  /proc/swaps, /proc/partitions, /proc/stat (Linux 2.4)
  /proc/swaps, /proc/diskstats, /proc/vmstat (Linux 2.6)
• Note that pages will only work if device was not specified;
• The sectors type parameter is supported only on Linux.

Example:

system.swap.in[,pages]

system.swap.out[<device>,<type>]

The swap-out (from memory onto device) statistics.
Return value: Integer.
Supported platforms: Linux, FreeBSD, OpenBSD.

Parameters:

• device - specify the device used for swapping (Linux only) or all (default);
• type - possible values: count (number of swapouts, default on non-Linux platforms), sectors (sectors swapped out), or pages (pages swapped out, default on Linux).

Comments:

• The source of this information is:
  /proc/swaps, /proc/partitions, /proc/stat (Linux 2.4)
  /proc/swaps, /proc/diskstats, /proc/vmstat (Linux 2.6)
• Note that pages will only work if device was not specified;
• The sectors type parameter is supported only on Linux.

Example:

system.swap.out[,pages]

system.swap.size[<device>,<type>]

The swap space size in bytes or in percentage from total.
Return value: Integer - for bytes; Float - for percentage.
Supported platforms: Linux, FreeBSD, Solaris, AIX, Tru64, OpenBSD.

Parameters:

• device - specify the device used for swapping (FreeBSD only) or all (default);
• type - possible values: free (free swap space, default), pfree (free swap space, in percent), pused (used swap space, in percent), total (total swap space), or used (used swap space).

Comments:

• Note that pfree, pused are not supported on Windows if swap size is 0;
• If device is not specified Zabbix agent will only take into account swap devices (files), the physical memory will be ignored. For example, on Solaris systems the swap -s command includes a portion of physical memory and swap devices (unlike swap -l).

Example:

system.swap.size[,pfree] → free swap space percentage

system.uname

Identification of the system.
Return value: String.
See supported platforms.

Comments:

• On UNIX the value for this item is obtained with the uname() system call;
• On Windows the item returns the OS architecture, whereas on UNIX it returns the CPU architecture.|

Example (UNIX):

 system.uname → FreeBSD localhost 4.2-RELEASE FreeBSD 4.2-RELEASE #0: Mon Nov i386

system.uptime

The system uptime in seconds.
Return value: Integer.
Supported platforms: Linux, FreeBSD, Solaris, AIX, MacOS X, OpenBSD, NetBSD. The support on Tru64 is unknown.

In item configuration, use s or uptime units to get readable values.|

system.users.num

The number of users logged in.
Return value: Integer.
See supported platforms.

The who command is used on the agent side to obtain the value.

vfs.dev.discovery

The list of block devices and their type. Used for low-level discovery.
Return value: JSON object.
Supported platforms: Linux.

vfs.dev.read[<device>,<type>,<mode>]

The disk read statistics.
Return value: Integer - with type in sectors, operations, bytes; Float - with type in sps, ops, bps.
Supported platforms: Linux, FreeBSD, Solaris, AIX, OpenBSD.

Parameters:

• device - disk device (default is all 3);
• type - possible values: sectors, operations, bytes, sps, ops, or bps (sps, ops, bps stand for: sectors, operations, bytes per second, respectively);
• mode - possible values: avg1 (one-minute average, default), avg5, or avg15. This parameter is supported only with type in: sps, ops, bps.

Comments:

• If using an update interval of three hours or more2, this item will always return ‘0’;
• The sectors and sps type parameters are supported only on Linux;
• The ops type parameter is supported only on Linux and FreeBSD;
• The bps type parameter is supported only on FreeBSD;
• The bytes type parameter is supported only on FreeBSD, Solaris, AIX, OpenBSD;
• The mode parameter is supported only on Linux, FreeBSD;
• You may use relative device names (for example, sda) as well as an optional /dev/ prefix (for example, /dev/sda);
• LVM logical volumes are supported;
• The default values of ‘type’ parameter for different OSes:
  AIX - operations
  FreeBSD - bps
  Linux - sps
  OpenBSD - operations
  Solaris - bytes
• sps, ops and bps on supported platforms is limited to 1024 devices (1023 individual and one for all).

Example:

vfs.dev.read[,operations]

vfs.dev.write[<device>,<type>,<mode>]

The disk write statistics.
Return value: Integer - with type in sectors, operations, bytes; Float - with type in sps, ops, bps.
Supported platforms: Linux, FreeBSD, Solaris, AIX, OpenBSD.

Parameters:

• device - disk device (default is all 3);
• type - possible values: sectors, operations, bytes, sps, ops, or bps (sps, ops, bps stand for: sectors, operations, bytes per second, respectively);
• mode - possible values: avg1 (one-minute average, default), avg5, or avg15. This parameter is supported only with type in: sps, ops, bps.

Comments:

• If using an update interval of three hours or more2, this item will always return ‘0’;
• The sectors and sps type parameters are supported only on Linux;
• The ops type parameter is supported only on Linux and FreeBSD;
• The bps type parameter is supported only on FreeBSD;
• The bytes type parameter is supported only on FreeBSD, Solaris, AIX, OpenBSD;
• The mode parameter is supported only on Linux, FreeBSD;
• You may use relative device names (for example, sda) as well as an optional /dev/ prefix (for example, /dev/sda);
• LVM logical volumes are supported;
• The default values of ‘type’ parameter for different OSes:
  AIX - operations
  FreeBSD - bps
  Linux - sps
  OpenBSD - operations
  Solaris - bytes
• sps, ops and bps on supported platforms is limited to 1024 devices (1023 individual and one for all).

Example:

vfs.dev.write[,operations]

vfs.dir.count[dir,<regex incl>,<regex excl>,<types incl>,<types excl>,<max depth>,<min size>,<max size>,<min age>,<max age>,<regex excl dir>]

The directory entry count.
Return value: Integer.
See supported platforms.

Parameters:

• dir - the absolute path to directory;
• regex incl - a regular expression describing the name pattern of the entity (file, directory, symbolic link) to include; include all if empty (default value);
• regex excl - a regular expression describing the name pattern of the entity (file, directory, symbolic link) to exclude; don’t exclude any if empty (default value);
• types incl - directory entry types to count, possible values: file - regular file, dir - subdirectory, sym - symbolic link, sock - socket, bdev - block device, cdev - character device, fifo - FIFO, dev - synonymous with “bdev,cdev”, all - all types (default), i.e. “file,dir,sym,sock,bdev,cdev,fifo”. Multiple types must be separated with comma and quoted.
• types excl - directory entry types (see types incl) to NOT count. If some entry type is in both types incl and types excl, directory entries of this type are NOT counted.
• max depth - the maximum depth of subdirectories to traverse:
  -1 (default) - unlimited,
  0 - no descending into subdirectories.
• min size - the minimum size (in bytes) for file to be counted. Smaller files will not be counted. Memory suffixes can be used.
• max size - the maximum size (in bytes) for file to be counted. Larger files will not be counted. Memory suffixes can be used.
• min age - the minimum age (in seconds) of directory entry to be counted. More recent entries will not be counted. Time suffixes can be used.
• max age - the maximum age (in seconds) of directory entry to be counted. Entries so old and older will not be counted (modification time). Time suffixes can be used.
• regex excl dir - a regular expression describing the name pattern of the directory to exclude. All content of the directory will be excluded (in contrast to regex_excl)

Comments:

• Environment variables, e.g. %APP_HOME%, $HOME and %TEMP% are not supported;
• Pseudo-directories “.” and “..” are never counted;
• Symbolic links are never followed for directory traversal;
• Both regex incl and regex excl are being applied to files and directories when calculating the entry count, but are ignored when picking subdirectories to traverse (if regex incl is “(?i)^.+\.zip$” and max depth is not set, then all subdirectories will be traversed, but only the files of type zip will be counted).
• The execution time is limited by the timeout value in agent configuration (3 sec). Since large directory traversal may take longer than that, no data will be returned and the item will turn unsupported. Partial count will not be returned.
• When filtering by size, only regular files have meaningful sizes. Under Linux and BSD, directories also have non-zero sizes (a few Kb typically). Devices have zero sizes, e.g. the size of /dev/sda1 does not reflect the respective partition size. Therefore, when using <min_size> and <max_size>, it is advisable to specify <types_incl> as “file“, to avoid surprises.

Examples:

vfs.dir.count[/dev] #monitors the number of devices in /dev (Linux)

vfs.dir.get[dir,<regex incl>,<regex excl>,<types incl>,<types excl>,<max depth>,<min size>,<max size>,<min age>,<max age>,<regex excl dir>]

The directory entry list.
Return value: JSON object.
See supported platforms.

Parameters:

• dir - the absolute path to directory;
• regex incl - a regular expression describing the name pattern of the entity (file, directory, symbolic link) to include; include all if empty (default value);
• regex excl - a regular expression describing the name pattern of the entity (file, directory, symbolic link) to exclude; don’t exclude any if empty (default value);
• types incl - directory entry types to list, possible values: file - regular file, dir - subdirectory, sym - symbolic link, sock - socket, bdev - block device, cdev - character device, fifo - FIFO, dev - synonymous with “bdev,cdev”, all - all types (default), i.e. “file,dir,sym,sock,bdev,cdev,fifo”. Multiple types must be separated with comma and quoted.
• types excl - directory entry types (see types incl) to NOT list. If some entry type is in both types incl and types excl, directory entries of this type are NOT listed.
• max depth - the maximum depth of subdirectories to traverse:
  -1 (default) - unlimited,
  0 - no descending into subdirectories.
• min size - the minimum size (in bytes) for file to be listed. Smaller files will not be listed. Memory suffixes can be used.
• max size - the maximum size (in bytes) for file to be listed. Larger files will not be listed. Memory suffixes can be used.
• min age - the minimum age (in seconds) of directory entry to be listed. More recent entries will not be listed. Time suffixes can be used.
• max age - the maximum age (in seconds) of directory entry to be listed. Entries so old and older will not be listed (modification time). Time suffixes can be used.
• regex excl dir - a regular expression describing the name pattern of the directory to exclude. All content of the directory will be excluded (in contrast to regex excl)

Comments:

• Environment variables, e.g. %APP_HOME%, $HOME and %TEMP% are not supported;
• Pseudo-directories “.” and “..” are never listed;
• Symbolic links are never followed for directory traversal;
• Both regex incl and regex excl are being applied to files and directories when generating the entry list, but are ignored when picking subdirectories to traverse (if regex incl is “(?i)^.+\.zip$” and max depth is not set, then all subdirectories will be traversed, but only the files of type zip will be counted).
• The execution time is limited by the timeout value in agent configuration. Since large directory traversal may take longer than that, no data will be returned and the item will turn unsupported. Partial list will not be returned.
• When filtering by size, only regular files have meaningful sizes. Under Linux and BSD, directories also have non-zero sizes (a few Kb typically). Devices have zero sizes, e.g. the size of /dev/sda1 does not reflect the respective partition size. Therefore, when using min size and max size, it is advisable to specify types incl as “file“, to avoid surprises.

Examples:

vfs.dir.get[/dev] #retrieves the device list in /dev (Linux)

vfs.dir.size[dir,<regex incl>,<regex excl>,<mode>,<max depth>,<regex excl dir>]

The directory size (in bytes).
Return value: Integer.
Supported platforms: Linux. The item may work on other UNIX-like platforms.

Parameters:

• dir - the absolute path to directory;
• regex incl - a regular expression describing the name pattern of the entity (file, directory, symbolic link) to include; include all if empty (default value);
• regex excl - a regular expression describing the name pattern of the entity (file, directory, symbolic link) to exclude; don’t exclude any if empty (default value);
• mode - possible values: apparent (default) - gets apparent file sizes rather than disk usage (acts as du -sb dir), disk - gets disk usage (acts as du -s -B1 dir). Unlike the du command, the vfs.dir.size item takes hidden files in account when calculating the directory size (acts as du -sb .[^.]* * within dir).
• max depth - the maximum depth of subdirectories to traverse: -1 (default) - unlimited, 0 - no descending into subdirectories.
• regex excl dir - a regular expression describing the name pattern of the directory to exclude. All content of the directory will be excluded (in contrast to regex excl)

Comments:

• Only directories with at least the read permission for zabbix user are calculated. For directories with read permission only, the size of the directory itself is calculated. Directories with read & execute permissions are calculated including contents.
• With large directories or slow drives this item may time out due to the Timeout setting in agent and server/proxy configuration files. Increase the timeout values as necessary.
• The file size limit depends on large file support.

Examples:

vfs.dir.size[/tmp,log] #calculates the size of all files in /tmp containing 'log' in their names
       vfs.dir.size[/tmp,log,^.+\.old$] #calculates the size of all files in /tmp containing 'log' in their names, excluding files with names ending with '.old'

vfs.file.cksum[file,<mode>]

The file checksum, calculated by the UNIX cksum algorithm.
Return value: Integer - with mode as crc32, String - with mode as md5, sha256.
See #supported platforms.

Parameters:

• file - the full path to file;
• mode - crc32 (default), md5, or sha256.

The file size limit depends on large file support.

Example:

vfs.file.cksum[/etc/passwd]

Example of returned values (crc32/md5/sha256 respectively):

675436101
       9845acf68b73991eb7fd7ee0ded23c44
       ae67546e4aac995e5c921042d0cf0f1f7147703aa42bfbfb65404b30f238f2dc

vfs.file.contents[file,<encoding>]

Retrieving the contents of a file7.
Return value: Text.
See supported platforms.

Parameters:

• file - the full path to file;
• encoding - the code page identifier.

Comments:

• This item is limited to files no larger than 64KB;
• An empty string is returned if the file is empty or contains LF/CR characters only;
• The byte order mark (BOM) is excluded from the output.

Example:

vfs.file.contents[/etc/passwd]

vfs.file.exists[file,<types incl>,<types excl>]

Checks if the file exists.
Return value: 0 - not found; 1 - file of the specified type exists.
See supported platforms.

Parameters:

• file - the full path to file;
• types incl - the list of file types to include, possible values: file (regular file, default (if types_excl is not set)), dir (directory), sym (symbolic link), sock (socket), bdev (block device), cdev (character device), fifo (FIFO), dev (synonymous with “bdev,cdev”), all (all mentioned types, default if types_excl is set).
• types excl - the list of file types to exclude, see types_incl for possible values (by default no types are excluded)

Comments:

• Multiple types must be separated with a comma and the entire set enclosed in quotes “”;
• If the same type is in both <types_incl> and <types_excl>, files of this type are excluded;
• The file size limit depends on large file support.

Examples:

vfs.file.exists[/tmp/application.pid]
       vfs.file.exists[/tmp/application.pid,"file,dir,sym"]
       vfs.file.exists[/tmp/application_dir,dir]

vfs.file.get[file]

Returns information about a file.
Return value: JSON object.
See supported platforms.

Parameter:

• file - the full path to file

Supported file types on UNIX-like systems: regular file, directory, symbolic link, socket, block device, character device, FIFO.

Example:

vfs.file.get[/etc/passwd] #return a JSON with information about the /etc/passwd file (type, user, permissions, SID, uid etc)

vfs.file.md5sum[file]

The MD5 checksum of file.
Return value: Character string (MD5 hash of the file).
See supported platforms.

Parameter:

• file - the full path to file

The file size limit depends on large file support.

Example:

vfs.file.md5sum[/usr/local/etc/zabbix_agentd.conf]

Example of returned value:

b5052decb577e0fffd622d6ddc017e82

vfs.file.owner[file,<ownertype>,<resulttype>]

Retrieves the owner of a file.
Return value: String.
See supported platforms.

Parameters:

• file - the full path to file;
• ownertype - user (default) or group (Unix only);
• resulttype - name (default) or id; for id - return uid/gid on Unix, SID on Windows.

Example:

vfs.file.owner[/tmp/zabbix_server.log] #return the file owner of /tmp/zabbix_server.log
       vfs.file.owner[/tmp/zabbix_server.log,,id] #return the file owner ID of /tmp/zabbix_server.log

vfs.file.permissions[file]

Return a 4-digit string containing the octal number with UNIX permissions.
Return value: String.
Supported platforms: Linux. The item may work on other UNIX-like platforms.

Parameters:

• file - the full path to file

Example:

vfs.file.permissions[/etc/passwd] #return permissions of /etc/passwd, for example, '0644'

vfs.file.regexp[file,regexp,<encoding>,<start line>,<end line>,<output>]

Retrieve a string in the file7.
Return value: The line containing the matched string, or as specified by the optional output parameter.
See supported platforms.

Parameters:

• file - the full path to file;
• regexp - a regular expression describing the required pattern;
• encoding - the code page identifier;
• start line - the number of the first line to search (first line of file by default);
• end line - the number of the last line to search (last line of file by default);
• output - an optional output formatting template. The \0 escape sequence is replaced with the matched part of text (from the first character where match begins until the character where match ends) while an \N (where N=1…9) escape sequence is replaced with Nth matched group (or an empty string if the N exceeds the number of captured groups).

Comments:

• Only the first matching line is returned;
• An empty string is returned if no line matched the expression;
• The byte order mark (BOM) is excluded from the output;
• Content extraction using the output parameter takes place on the agent.

Examples:

vfs.file.regexp[/etc/passwd,zabbix]
       vfs.file.regexp[/path/to/some/file,"([0-9]+)$",,3,5,\1]
       vfs.file.regexp[/etc/passwd,"^zabbix:.:([0-9]+)",,,,\1] → getting the ID of user *zabbix*

vfs.file.regmatch[file,regexp,<encoding>,<start line>,<end line>]

Find a string in the file7.
Return values: 0 - match not found; 1 - found.
See supported platforms.

Parameters:

• file - the full path to file;
• regexp - a regular expression describing the required pattern;
• encoding - the code page identifier;
• start line - the number of the first line to search (first line of file by default);
• end line - the number of the last line to search (last line of file by default).

Comments:

• The byte order mark (BOM) is ignored.

Example:

vfs.file.regmatch[/var/log/app.log,error]

vfs.file.size[file,<mode>]

The file size (in bytes).
Return value: Integer.
See supported platforms.

Parameters:

• file - the full path to file;
• mode - possible values: bytes (default) or lines (empty lines are counted, too).

Comments:

• The file must have read permissions for user zabbix;
• The file size limit depends on large file support.

Example:

vfs.file.size[/var/log/syslog]

vfs.file.time[file,<mode>]

The file time information.
Return value: Integer (Unix timestamp).
See supported platforms.

Parameters:

• file - the full path to file;
• mode - possible values:
  modify (default) - the last time of modifying file content,
  access - the last time of reading file,
  change - the last time of changing file properties

The file size limit depends on large file support.

Example:

vfs.file.time[/etc/passwd,modify]

vfs.fs.discovery

The list of mounted filesystems with their type and mount options. Used for low-level discovery.
Return value: JSON object.
Supported platforms: Linux, FreeBSD, Solaris, HP-UX, AIX, MacOS X, OpenBSD, NetBSD.

vfs.fs.get

The list of mounted filesystems with their type, available disk space, inode statistics and mount options. Can be used for low-level discovery.
Return value: JSON object.
Supported platforms: Linux, FreeBSD, Solaris, HP-UX, AIX, MacOS X, OpenBSD, NetBSD.

Comments:

• File systems with the inode count equal to zero, which can be the case for file systems with dynamic inodes (e.g. btrfs), are also reported;
• See also: Discovery of mounted filesystems.

vfs.fs.inode[fs,<mode>]

The number or percentage of inodes.
Return value: Integer - for number; Float - for percentage.
See supported platforms.

Parameters:

• fs - the filesystem;
• mode - possible values: total (default), free, used, pfree (free, percentage), or pused (used, percentage).

If the inode count equals zero, which can be the case for file systems with dynamic inodes (e.g. btrfs), the pfree/pused values will be reported as “100” and “0” respectively.

Example:

vfs.fs.inode[/,pfree]

vfs.fs.size[fs,<mode>]

The disk space in bytes or in percentage from total.
Return value: Integer - for bytes; Float - for percentage.
See supported platforms.

Parameters:

• fs - the filesystem;
• mode - possible values: total (default), free, used, pfree (free, percentage), or pused (used, percentage).

Comments:

• If the filesystem is not mounted, returns the size of a local filesystem where the mount point is located;
• The reserved space of a file system is taken into account and not included when using the free mode.

Example:

vfs.fs.size[/tmp,free]

vm.memory.size[<mode>]

The memory size in bytes or in percentage from total.
Return value: Integer - for bytes; Float - for percentage.
See supported platforms.

Parameter:

• mode - possible values: total (default), active, anon, buffers, cached, exec, file, free, inactive, pinned, shared, slab, wired, used, pused (used, percentage), available, or pavailable (available, percentage).

Comments:

• This item accepts three categories of parameters:
  1) total - total amount of memory
  2) platform-specific memory types: active, anon, buffers, cached, exec, file, free, inactive, pinned, shared, slab, wired
  3) user-level estimates on how much memory is used and available: used, pused, available, pavailable
• The active mode parameter is supported only on FreeBSD, HP-UX, MacOS X, OpenBSD, NetBSD;
• The anon, exec, file mode parameters are supported only on NetBSD;
• The buffers mode parameter is supported only on Linux, FreeBSD, OpenBSD, NetBSD;
• The cached mode parameter is supported only on Linux, FreeBSD, AIX, OpenBSD, NetBSD;
• The inactive, wired mode parameters are supported only on FreeBSD, MacOS X, OpenBSD, NetBSD;
• The pinned mode parameter is supported only on AIX;
• The shared mode parameter is supported only on Linux 2.4, FreeBSD, OpenBSD, NetBSD;
• See also additional details for this item.

Example:

vm.memory.size[pavailable]

web.page.get[host,<path>,<port>]

Get the content of a web page.
Return value: Web page source as text (including headers).
See supported platforms.

Parameters:

• host - the hostname or URL (as scheme://host:port/path, where only host is mandatory). Allowed URL schemes: http, https4. A missing scheme will be treated as http. If a URL is specified path and port must be empty. Specifying user name/password when connecting to servers that require authentication, for example: http://user:[[email protected]](https://www.zabbix.com/cdn-cgi/l/email-protection) is only possible with cURL support 4. Punycode is supported in hostnames.
• path - the path to an HTML document (default is /);
• port - the port number (default is 80 for HTTP)

Comments:

• This item turns unsupported if the resource specified in host does not exist or is unavailable;
• host can be a hostname, domain name, IPv4 or IPv6 address. But for IPv6 address Zabbix agent must be compiled with IPv6 support enabled.

Example:

web.page.get[www.example.com,index.php,80]
       web.page.get[https://www.example.com]
       web.page.get[https://blog.example.com/?s=zabbix]
       web.page.get[localhost:80]
       web.page.get["[::1]/server-status"]

web.page.perf[host,<path>,<port>]

The loading time of a full web page (in seconds).
Return value: Float.
See supported platforms.

Parameters:

• host - the hostname or URL (as scheme://host:port/path, where only host is mandatory). Allowed URL schemes: http, https4. A missing scheme will be treated as http. If a URL is specified path and port must be empty. Specifying user name/password when connecting to servers that require authentication, for example: http://user:[[email protected]](https://www.zabbix.com/cdn-cgi/l/email-protection) is only possible with cURL support 4. Punycode is supported in hostnames.
• path - the path to an HTML document (default is /);
• port - the port number (default is 80 for HTTP)

Comments:

• This item turns unsupported if the resource specified in host does not exist or is unavailable;
• host can be a hostname, domain name, IPv4 or IPv6 address. But for IPv6 address Zabbix agent must be compiled with IPv6 support enabled.

Example:

web.page.perf[www.example.com,index.php,80]
       web.page.perf[https://www.example.com]

web.page.regexp[host,<path>,<port>,regexp,<length>,<output>]

Find a string on the web page.
Return value: The matched string, or as specified by the optional output parameter.
See supported platforms.

Parameters:

• host - the hostname or URL (as scheme://host:port/path, where only host is mandatory). Allowed URL schemes: http, https4. A missing scheme will be treated as http. If a URL is specified path and port must be empty. Specifying user name/password when connecting to servers that require authentication, for example: http://user:[[email protected]](https://www.zabbix.com/cdn-cgi/l/email-protection) is only possible with cURL support 4. Punycode is supported in hostnames.
• path - the path to an HTML document (default is /);
• port - the port number (default is 80 for HTTP)
• regexp - a regular expression describing the required pattern;
• length - the maximum number of characters to return;
• output - an optional output formatting template. The \0 escape sequence is replaced with the matched part of text (from the first character where match begins until the character where match ends) while an \N (where N=1…9) escape sequence is replaced with Nth matched group (or an empty string if the N exceeds the number of captured groups).

Comments:

• This item turns unsupported if the resource specified in host does not exist or is unavailable;
• host can be a hostname, domain name, IPv4 or IPv6 address. But for IPv6 address Zabbix agent must be compiled with IPv6 support enabled.
• Content extraction using the output parameter takes place on the agent.

Example:

web.page.regexp[www.example.com,index.php,80,OK,2]
       web.page.regexp[https://www.example.com,,,OK,2]|

agent.hostmetadata

The agent host metadata.
Return value: String.
See supported platforms.

Returns the value of HostMetadata or HostMetadataItem parameters, or empty string if none are defined.

agent.hostname

The agent host name.
Return value: String.
See supported platforms.

Returns:

• As passive check - the name of the first host listed in the Hostname parameter of the agent configuration file;
• As active check - the name of the current hostname.

agent.ping

The agent availability check.
Return value: Nothing - unavailable; 1 - available.
See supported platforms.

Use the nodata() trigger function to check for host unavailability.

agent.variant

The variant of Zabbix agent (Zabbix agent or Zabbix agent 2).
Return value: 1 - Zabbix agent; 2 - Zabbix agent 2.
See supported platforms.

agent.version

The version of Zabbix agent.
Return value: String.
See supported platforms.

Example of returned value:

6.0.3

zabbix.stats[<ip>,<port>]

Returns a set of Zabbix server or proxy internal metrics remotely.
Return value: JSON object.
See supported platforms.

Parameters:

• ip - the IP/DNS/network mask list of servers/proxies to be remotely queried (default is 127.0.0.1);
• port - the port of server/proxy to be remotely queried (default is 10051)

Comments:

• A selected set of internal metrics is returned by this item. For details, see Remote monitoring of Zabbix stats;
• Note that the stats request will only be accepted from the addresses listed in the ‘StatsAllowedIP’ server/proxy parameter on the target instance.

zabbix.stats[<ip>,<port>,queue,<from>,<to>]

Returns the number of monitored items in the queue which are delayed on Zabbix server or proxy remotely.
Return value: JSON object.
See supported platforms.

Parameters:

• ip - the IP/DNS/network mask list of servers/proxies to be remotely queried (default is 127.0.0.1);
• port - the port of server/proxy to be remotely queried (default is 10051)
• queue - constant (to be used as is)
• from - delayed by at least (default is 6 seconds)
• to - delayed by at most (default is infinity)

Note that the stats request will only be accepted from the addresses listed in the ‘StatsAllowedIP’ server/proxy parameter on the target instance.

Footnotes

1A Linux-specific note. Zabbix agent must have read-only access to filesystem /proc. Kernel patches from www.grsecurity.org limit access rights of non-privileged users.

2 vfs.dev.read[], vfs.dev.write[]: Zabbix agent will terminate “stale” device connections if the item values are not accessed for more than 3 hours. This may happen if a system has devices with dynamically changing paths or if a device gets manually removed. Note also that these items, if using an update interval of 3 hours or more, will always return ‘0’.

3 vfs.dev.read[], vfs.dev.write[]: If default all is used for the first parameter then the key will return summary statistics, including all block devices like sda, sdb, and their partitions (sda1, sda2, sdb3…) and multiple devices (MD raid) based on those block devices/partitions and logical volumes (LVM) based on those block devices/partitions. In such cases returned values should be considered only as relative value (dynamic in time) but not as absolute values.

4 SSL (HTTPS) is supported only if agent is compiled with cURL support. Otherwise the item will turn unsupported.

5 The bytes and errors values are not supported for loopback interfaces on Solaris systems up to and including Solaris 10 6/06 as byte, error and utilization statistics are not stored and/or reported by the kernel. However, if you’re monitoring a Solaris system via net-snmp, values may be returned as net-snmp carries legacy code from the cmu-snmp dated as old as 1997 that, upon failing to read byte values from the interface statistics returns the packet counter (which does exist on loopback interfaces) multiplied by an arbitrary value of 308. This makes the assumption that the average length of a packet is 308 octets, which is a very rough estimation as the MTU limit on Solaris systems for loopback interfaces is 8892 bytes. These values should not be assumed to be correct or even closely accurate. They are guestimates. The Zabbix agent does not do any guess work, but net-snmp will return a value for these fields.

6 The command line on Solaris, obtained from /proc/pid/psinfo, is limited to 80 bytes and contains the command line as it was when the process was started.

7 vfs.file.contents[], vfs.file.regexp[], vfs.file.regmatch[] items can be used for retrieving file contents. If you want to restrict access to specific files with sensitive information, run Zabbix agent under a user that has no access permissions to viewing these files.

Usage with command-line utilities

Note that when testing or using item keys with zabbix_agentd or zabbix_get from the command line you should consider shell syntax too.

For example, if a certain parameter of the key has to be enclosed in double quotes you have to explicitly escape double quotes, otherwise they will be trimmed by the shell as special characters and will not be passed to the Zabbix utility.

Examples:

$ zabbix_agentd -t 'vfs.dir.count[/var/log,,,"file,dir",,0]'
       $ zabbix_agentd -t vfs.dir.count[/var/log,,,\"file,dir\",,0]

Encoding settings

To make sure that the acquired data are not corrupted you may specify the correct encoding for processing the check (e.g. ‘vfs.file.contents’) in the encoding parameter. The list of supported encodings (code page identifiers) may be found in documentation for libiconv (GNU Project) or in Microsoft Windows SDK documentation for “Code Page Identifiers”.

If no encoding is specified in the encoding parameter the following resolution strategies are applied:

• If encoding is not specified (or is an empty string) it is assumed to be UTF-8, the data is processed “as-is”;
• BOM analysis - applicable for items ‘vfs.file.contents’, ‘vfs.file.regexp’, ‘vfs.file.regmatch’. An attempt is made to determine the correct encoding by using the byte order mark (BOM) at the beginning of the file. If BOM is not present - standard resolution (see above) is applied instead.

Troubleshooting agent items

• If used with the passive agent, Timeout value in server configuration may need to be higher than Timeout in the agent configuration file. Otherwise the item may not get any value because the server request to agent timed out first.