1 Zabbix agent

概述

这些检查与Zabbix agent进行通信，实现数据的采集

有 被动和主动两种 agent 检查模式 ， 在配置监控项时，你可以选择所需的类型:

  • Zabbix agent - 被动检查
  • Zabbix agent(主动) - 主动检查

Supported platforms

Except where specified differently in the item comments, 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:

  1. log[/var/log/syslog]
  2.        log[/var/log/syslog,error]
  3.        log[/home/zabbix/logs/logfile,,,100]

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

  1. 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:

  1. 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:

  1. logrt["/home/zabbix/logs/^logfile[0-9]{1,3}$",,,100] #this item will match a file like "logfile1" (will not match ".logfile1")
  2.        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:

  1. 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:

  1. 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:

  1. 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:

  1. 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 transmitted or 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:

  1. net.if.in[eth0]
  2.        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:

  1. net.if.out[eth0]
  2.        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:

  1. net.if.total[eth0]
  2.        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:

  1. 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:

  1. 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 (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);
  • See also known issues of checking the HTTPS service.

Example:

  1. 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: 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 (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);
  • See also known issues of checking the HTTPS service.

Example:

  1. 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:

  1. net.tcp.socket.count[,80,,,established] #check if the local TCP port 80 is in "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:

  1. 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 (default is 127.0.0.1);
  • port - the port number (by default the standard service port number is used).

Example:

  1. 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: 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 (default is 127.0.0.1);
  • port - the port number (by default the standard service port number is used).

Example:

  1. 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:

  1. net.udp.socket.count[,,,,listening] → check if any UDP socket is in "listening" 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:

  1. proc.cpu.util[,root] #CPU utilization of all processes running under the "root" user
  2.        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:

  1. proc.get[zabbix,,,process] #list of all Zabbix processes, returns one entry per PID
  2.        proc.get[java,,,thread] #list of all Java processes, returns one entry per thread
  3.        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:

  1. proc.mem[,root] #the memory used by all processes running under the "root" user
  2.        proc.mem[zabbix_server,zabbix] #the memory used by all zabbix_server processes running under the zabbix user
  3.        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:

  1. proc.num[,mysql] #the number of processes running under the mysql user
  2.        proc.num[apache2,www-data] #the number of apache2 processes running under the www-data user
  3.        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;
  • sensor - the sensor name;
  • 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:

  1. sensor[w83781d-i2c-0-2d,temp1]
  2.        sensor[cpu0,temp0] #the temperature of one CPU
  3.        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:

  1. 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:

  1. 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:

  1. 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:

  1. system.hostname → linux-w7x1
  2.        system.hostname → example.com
  3.        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:

  1. 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:

  1. 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:

  1. 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:

  1. 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:

  1. 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:

  1. 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:

  1. 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:

  1. system.sw.os[short] → Ubuntu 2.6.35-28.50-generic 2.6.35.11
  2.        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:

  1. 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:

  1. 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:

  1. 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:

  1. 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):

  1.  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:

  1. 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:

  1. 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 size, 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 default 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:

  1. 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 calculating the entry size, 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 default 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 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:

  1. 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:

  1. vfs.dir.size[/tmp,log] #calculates the size of all files in /tmp which contain 'log'
  2.        vfs.dir.size[/tmp,log,^.+\.old$] #calculates the size of all files in /tmp which contain 'log', excluding files containing '.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:

  1. vfs.file.cksum[/etc/passwd]

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

  1. 675436101
  2.        9845acf68b73991eb7fd7ee0ded23c44
  3.        ae67546e4aac995e5c921042d0cf0f1f7147703aa42bfbfb65404b30f238f2dc
vfs.file.contents[file,<encoding>]

Retrieving the contents of a file.
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:

  1. 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:

  1. vfs.file.exists[/tmp/application.pid]
  2.        vfs.file.exists[/tmp/application.pid,"file,dir,sym"]
  3.        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:

  1. 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:

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

Example of returned value:

  1. 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:

  1. vfs.file.owner[/tmp/zabbix_server.log] #return the file owner of /tmp/zabbix_server.log
  2.        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:

  1. 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 file.
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:

  1. vfs.file.regexp[/etc/passwd,zabbix]
  2.        vfs.file.regexp[/path/to/some/file,"([0-9]+)$",,3,5,\1]
  3.        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 file.
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:

  1. 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:

  1. 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:

  1. 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:

  1. 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:

  • In case of a mounted volume, the disk space for local file system is returned;
  • The reserved space of a file system is taken into account and not included when using the free mode.

Example:

  1. 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:

  1. 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:passwor[[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:

  1. web.page.get[www.example.com,index.php,80]
  2.        web.page.get[https://www.example.com]
  3.        web.page.get[https://blog.example.com/?s=zabbix]
  4.        web.page.get[localhost:80]
  5.        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:

  1. web.page.perf[www.example.com,index.php,80]
  2.        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:

  1. web.page.regexp[www.example.com,index.php,80,OK,2]
  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:

  1. 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.

Paramaters:

  • 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.

支持的监控项

下表提供了可用的Zabbix agent监控项键值的详细信息。

另请参阅

脚注

1Linux相关。Zabbix agent 必须对文件系统/proc有只读权限。www.grsecurity.org的内核补丁限制了未授权用户的访问权限。

2 vfs.dev.read[], vfs.dev.write[]: 如果监控项值超过3小时无法获取，Zabbix agent 会终止”过时”的设备连接。这可能在系统设备动态变化或者手动移除时发生。请注意这些监控项的更新间隔在3小时以上时，会永远返回’0’。

3 vfs.dev.read[], vfs.dev.write[]: 如果将默认的all 作为第一个参数，此键会返回汇总统计数据，包括所有的块设备如sda，sbd及其分区（sda1, sda2, sdb3…）和基于这些块设备/分区的多个设备（MD raid）和基于这些块设备/分区的逻辑设备（LVM）。在这些情况下返回值应只考虑相对值（随时间动态变化）而不是绝对值。

4 SSL (HTTPS) 仅在agent在支持cURL的情况下编译时被支持。否则此监控项会返回不受支持。

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:

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

编码设置

要确保获取的数据不被损坏，你可能需要在 encoding参数中指定正确的编码来处理检查（例如 ‘vfs.file.contents’）。受支持的的编码（代码页标识符）可在libiconv (GNU 项目) 的文档查找，或在微软Windows SDK的文档查找”Code Page Identifiers”。

如果未在 encoding参数中指定编码，会应用以下解决方案策略：

  • 标准解决方案 - 在 Unix/Linux（默认在较新的发型版本) 使用UTF-8；在Windows使用系统扩展的ANSI；
  • BOM分析 - 在监控项 ‘vfs.file.contents’, ‘vfs.file.regexp’, ‘vfs.file.regmatch’可应用。尝试使用文件开头的字节顺序标记（BOM）来决定正确的编码。如果没有BOM - 改为应用标准解决方案（见上）。

agent监控项故障排除

  • 如果使用被动 agent，server 配置的Timeout值可能需要比 agent 配置的Timeout值高。 否则此监控项可能不会获取到任何值，因为 server 到 agent 的请求先超时了。