Zabbix - Monitoring A Debian 12 Host
About
This tutorial will show you how to install the Zabbix agent on Debian 12, and configure it with Zabbix either passively or actively. We will then step through adding it to our Zabbix server in order to pull the metrics and get monitoring!
Related Posts
Steps
Install Agent
Install the Zabbix Agent 2 package.
sudo apt-get install zabbix-agent2
Decide Between Active vs Passive Monitoring
The first thing we need to do before configuring monitoring is to decide between whether we are going to use "active" or "passive" monitoring.
In passive monitoring, the Zabbix server we configured reaches out to the host being monitored (on port 10050), and asks for the information. Thus the host being monitored needs to be network-reachable by your Zabbix server. This may be a good setup to use if your Zabbix server is behind a NAT, but the host being monitored isn't.
In active monitoring, the host to be monitored reaches out to the Zabbix server to ask what information it requires (on port 10051), before then providing it. This requires the Zabbix server to be network-reachable by your host being monitored. This may be a good setup to use if the host being monitored is behind a NAT, but your Zabbix server isn't.
Configure Zabbix Agent
Now that you have decided whether to use active or passive monitoring, edit your Zabbix agent configuration by using the command below, and
then replace it's contents with either the passive configuration template, or the active configuration template provided,
making sure to replace the xxx.xxx.xxx.xxx value with the IP address of your Zabbix server.
sudo editor /etc/zabbix/zabbix_agent2.conf
Passive Configuration Template
# This is a configuration file for Zabbix agent 2 (Unix)
# To get more information about Zabbix, visit http://www.zabbix.com
# Specify the name for this server. Thist must be unique against all the
# other hosts you are monitoring!
Hostname=Zabbix server
# List of comma delimited IP addresses, optionally in CIDR notation, or DNS names of Zabbix servers and Zabbix proxies.
Server=xxx.xxx.xxx.xxx
# Agent will listen on this port for connections from the server.
ListenPort=10050
# Perform log file rotation at the 1 MB point for the specified filepath.
LogFileSize=1
LogFile=/var/log/zabbix/zabbix_agent2.log
# Include other configuration files
Include=/etc/zabbix/zabbix_agent2.d/*.conf
Include=./zabbix_agent2.d/plugins.d/*.conf
# The control socket, used to send runtime commands with '-R' option.
ControlSocket=/tmp/agent.sock
Server.
Active Configuration Template
# This is a configuration file for Zabbix agent 2 (Unix)
# To get more information about Zabbix, visit http://www.zabbix.com
# Specify the name for this server. Thist must be unique against all the
# other hosts you are monitoring!
Hostname=myUniqueHostnameHere
# Specify the location of the Zabbix server host.
ServerActive=xxx.xxx.xxx.xxx
# How often list of active checks is refreshed, in seconds.
RefreshActiveChecks=60
# Refresh the active checks on start.
ForceActiveChecksOnStart=1
# Perform log file rotation at the 1 MB point for the specified filepath.
LogFileSize=1
LogFile=/var/log/zabbix/zabbix_agent2.log
# Include other configuration files
Include=/etc/zabbix/zabbix_agent2.d/*.conf
Include=./zabbix_agent2.d/plugins.d/*.conf
# The control socket, used to send runtime commands with '-R' option.
ControlSocket=/tmp/agent.sock
ServerActive, and set a unique value for Hostname.
Restart Zabbix Agent
After having changed the configuration file, restart the agent for the changes to take effect:
sudo service zabbix-agent2 restart
Add Host To Zabbix Server
Now that we have configured the host, we can add it to the Zabbix server.
Open Create Host Modal
Log into your Zabbix server and go to Monitoring > Hosts (1) and click the button in the top-right to Create host (2).
Fill In Basic Details
In the modal that appears, give your host a name, a display name and assign it the Linux by Zabbix agent template for a good set of metrics to monitor.
Passive Monitoring Only - Add Interface
Those setting up active monitoring can skip this step, but for those that are setting up passive monitoring, you now need to click the Add hyperlink (1) to add an interface to reach out on to pull metrics. Then select Agent (2) to let Zabbix know we are pulling metrics from connecting to an agent installed on the server.
Then specify the IP address (1), DNS (2), and port (4) for connecting to your server. The DNS/IP toggle (3) tells the zabbix server whether to use the DNS or IP address to connect to your server. I generally recommend using IP addresses as I have static IPs, but sometimes that is not always feasible depending on your setup. Then save.
See Host
The host should immediately appear in your list of hosts. However, you will have to wait a while (one or two minutes) for it to retrieve some data so be patient! If you configured passive monitoring, then a green ZBX should appear (1) when the host is reachable (1). If you set up active monitoring then this will be greyed out and just means that Zabbix cannot reach the host, as no interface has been configured.
You should be able to click Latest data (2) to retrieve the latest information about the host, such as how full the filesystems are, and how much RAM is being utilized. If you experience getting metrics/data from the host, please refer to the debugging section.
.
Conclusion
You've now been shown how to add the monitoring of a single Debian 12 instance to your Zabbix setup. We skipped over the finer details, such as configuring what metrics are monitored through templates etc, but we can cover that in other tutorials in the future.
If you think I got something wrong, or missed something important, please leave a comment down below.
Appendix
Pitfalls of Active Monitoring
With active monitoring you may likely not configure an interface for the host being monitored in your Zabbix server (as it may not be reachable). If an interface is not configured then Zabbix cannot perform its monitoring check that shows if the host is up. You will be purely reliant on Zabbix sending you an alert if it hasn't received information from the host in an expected time period.
Also, with active monitoring, the agent decides the host it applies to by the hostname configured in its configuration file. This can lead to the following confusion/issues:
- If the hostname doesnt exist on the Zabbix server, then nothing will be being reported, and you will be wondering what is going wrong.
- If two hosts are configured with the same hostname, then both will send their data to Zabbix, which will record both. This can be very confusing, and make it look like your memory is jumping all over the place etc. This was shown by Dmitry Lambert in this youtube video.
- If you clone a virtual machine that uses active monitoring, and simply forget to change this hostname field, you will get both issues 1 and 2 outlined above!
With passive monitoring, you configure the server to reach out to the host being monitored. This means means that accidentally getting data from two different hosts would not be possible, and it is much more straightforward configuring the IP of the host in the Zabbix server. This also means the active hosts feature will be working.
In conclusion, I would recommend always using passive monitoring whenever possible!
Debugging
View Agent Log File
If you aren't getting any data being reported on the Zabbix server and are using active monitoring, then I recommend you read the log file of your Zabbix agent (the host being monitored). I often find that it will tell me the host could not be found on the server, because I had a typo etc.
sudo tail -100f /var/log/zabbix/zabbix_agent2.log
No StartAgents Configuration
With Zabbix agent 2, compared to the original Zabbix agent, there is no longer a StartAgents configuration option to set. In fact, setting it will stop the service from starting.
Default Zabbix Agent Configuration
Below is the default configuration that is provided to you after having just installed Zabbix Agent 2.
# This is a configuration file for Zabbix agent 2 (Unix)
# To get more information about Zabbix, visit http://www.zabbix.com
############ GENERAL PARAMETERS #################
### Option: PidFile
# Name of PID file.
#
# Mandatory: no
# Default:
# PidFile=/tmp/zabbix_agent2.pid
### Option: LogType
# Specifies where log messages are written to:
# system - syslog
# file - file specified with LogFile parameter
# console - standard output
#
# Mandatory: no
# Default:
# LogType=file
### Option: LogFile
# Log file name for LogType 'file' parameter.
#
# Mandatory: yes, if LogType is set to file, otherwise no
# Default:
# LogFile=/tmp/zabbix_agent2.log
LogFile=/var/log/zabbix/zabbix_agent2.log
### Option: LogFileSize
# Maximum size of log file in MB.
# 0 - disable automatic log rotation.
#
# Mandatory: no
# Range: 0-1024
# Default:
# LogFileSize=1
LogFileSize=0
### Option: DebugLevel
# Specifies debug level:
# 0 - basic information about starting and stopping of Zabbix processes
# 1 - critical information
# 2 - error information
# 3 - warnings
# 4 - for debugging (produces lots of information)
# 5 - extended debugging (produces even more information)
#
# Mandatory: no
# Range: 0-5
# Default:
# DebugLevel=3
### Option: SourceIP
# Source IP address for outgoing connections.
#
# Mandatory: no
# Default:
# SourceIP=
##### Passive checks related
### Option: Server
# List of comma delimited IP addresses, optionally in CIDR notation, or DNS names of Zabbix servers and Zabbix proxies.
# Incoming connections will be accepted only from the hosts listed here.
# If IPv6 support is enabled then '127.0.0.1', '::127.0.0.1', '::ffff:127.0.0.1' are treated equally
# and '::/0' will allow any IPv4 or IPv6 address.
# '0.0.0.0/0' can be used to allow any IPv4 address.
# Example: Server=127.0.0.1,192.168.1.0/24,::1,2001:db8::/32,zabbix.example.com
#
# Mandatory: yes, if StartAgents is not explicitly set to 0
# Default:
# Server=
Server=127.0.0.1
### Option: ListenPort
# Agent will listen on this port for connections from the server.
#
# Mandatory: no
# Range: 1024-32767
# Default:
# ListenPort=10050
### Option: ListenIP
# List of comma delimited IP addresses that the agent should listen on.
# First IP address is sent to Zabbix server if connecting to it to retrieve list of active checks.
#
# Mandatory: no
# Default:
# ListenIP=0.0.0.0
### Option: StatusPort
# Agent will listen on this port for HTTP status requests.
#
# Mandatory: no
# Range: 1024-32767
# Default:
# StatusPort=
##### Active checks related
### Option: ServerActive
# Zabbix server/proxy address or cluster configuration to get active checks from.
# Server/proxy address is IP address or DNS name and optional port separated by colon.
# Cluster configuration is one or more server addresses separated by semicolon.
# Multiple Zabbix servers/clusters and Zabbix proxies can be specified, separated by comma.
# More than one Zabbix proxy should not be specified from each Zabbix server/cluster.
# If Zabbix proxy is specified then Zabbix server/cluster for that proxy should not be specified.
# Multiple comma-delimited addresses can be provided to use several independent Zabbix servers in parallel. Spaces are allowed.
# If port is not specified, default port is used.
# IPv6 addresses must be enclosed in square brackets if port for that host is specified.
# If port is not specified, square brackets for IPv6 addresses are optional.
# If this parameter is not specified, active checks are disabled.
# Example for Zabbix proxy:
# ServerActive=127.0.0.1:10051
# Example for multiple servers:
# ServerActive=127.0.0.1:20051,zabbix.domain,[::1]:30051,::1,[12fc::1]
# Example for high availability:
# ServerActive=zabbix.cluster.node1;zabbix.cluster.node2:20051;zabbix.cluster.node3
# Example for high availability with two clusters and one server:
# ServerActive=zabbix.cluster.node1;zabbix.cluster.node2:20051,zabbix.cluster2.node1;zabbix.cluster2.node2,zabbix.domain
#
# Mandatory: no
# Default:
# ServerActive=
ServerActive=127.0.0.1
### Option: Hostname
# List of comma delimited unique, case sensitive hostnames.
# Required for active checks and must match hostnames as configured on the server.
# Value is acquired from HostnameItem if undefined.
#
# Mandatory: no
# Default:
# Hostname=
Hostname=Zabbix server
### Option: HostnameItem
# Item used for generating Hostname if it is undefined. Ignored if Hostname is defined.
# Does not support UserParameters or aliases.
#
# Mandatory: no
# Default:
# HostnameItem=system.hostname
### Option: HostMetadata
# Optional parameter that defines host metadata.
# Host metadata is used at host auto-registration process.
# An agent will issue an error and not start if the value is over limit of 255 characters.
# If not defined, value will be acquired from HostMetadataItem.
#
# Mandatory: no
# Range: 0-255 characters
# Default:
# HostMetadata=
### Option: HostMetadataItem
# Optional parameter that defines an item used for getting host metadata.
# Host metadata is used at host auto-registration process.
# During an auto-registration request an agent will log a warning message if
# the value returned by specified item is over limit of 255 characters.
# This option is only used when HostMetadata is not defined.
#
# Mandatory: no
# Default:
# HostMetadataItem=
### Option: HostInterface
# Optional parameter that defines host interface.
# Host interface is used at host auto-registration process.
# An agent will issue an error and not start if the value is over limit of 255 characters.
# If not defined, value will be acquired from HostInterfaceItem.
#
# Mandatory: no
# Range: 0-255 characters
# Default:
# HostInterface=
### Option: HostInterfaceItem
# Optional parameter that defines an item used for getting host interface.
# Host interface is used at host auto-registration process.
# During an auto-registration request an agent will log a warning message if
# the value returned by specified item is over limit of 255 characters.
# This option is only used when HostInterface is not defined.
#
# Mandatory: no
# Default:
# HostInterfaceItem=
### Option: RefreshActiveChecks
# How often list of active checks is refreshed, in seconds.
#
# Mandatory: no
# Range: 60-3600
# Default:
# RefreshActiveChecks=120
### Option: BufferSend
# Do not keep data longer than N seconds in buffer.
#
# Mandatory: no
# Range: 1-3600
# Default:
# BufferSend=5
### Option: BufferSize
# Maximum number of values in a memory buffer. The agent will send
# all collected data to Zabbix Server or Proxy if the buffer is full.
# Option is not valid if EnablePersistentBuffer=1
#
# Mandatory: no
# Range: 2-65535
# Default:
# BufferSize=100
### Option: EnablePersistentBuffer
# Enable usage of local persistent storage for active items.
# 0 - disabled, in-memory buffer is used (default); 1 - use persistent buffer
# Mandatory: no
# Range: 0-1
# Default:
# EnablePersistentBuffer=0
### Option: PersistentBufferPeriod
# Zabbix Agent2 will keep data for this time period in case of no
# connectivity with Zabbix server or proxy. Older data will be lost. Log data will be preserved.
# Option is valid if EnablePersistentBuffer=1
#
# Mandatory: no
# Range: 1m-365d
# Default:
# PersistentBufferPeriod=1h
### Option: PersistentBufferFile
# Full filename. Zabbix Agent2 will keep SQLite database in this file.
# Option is valid if EnablePersistentBuffer=1
#
# Mandatory: no
# Default:
# PersistentBufferFile=
############ ADVANCED PARAMETERS #################
### Option: Alias
# Sets an alias for an item key. It can be used to substitute long and complex item key with a smaller and simpler one.
# Multiple Alias parameters may be present. Multiple parameters with the same Alias key are not allowed.
# Different Alias keys may reference the same item key.
# For example, to retrieve the ID of user 'zabbix':
# Alias=zabbix.userid:vfs.file.regexp[/etc/passwd,^zabbix:.:([0-9]+),,,,\1]
# Now shorthand key zabbix.userid may be used to retrieve data.
# Aliases can be used in HostMetadataItem but not in HostnameItem parameters.
#
# Mandatory: no
# Range:
# Default:
### Option: Timeout
# Spend no more than Timeout seconds on processing
#
# Mandatory: no
# Range: 1-30
# Default:
# Timeout=3
### Option: Include
# You may include individual files or all files in a directory in the configuration file.
# Installing Zabbix will create include directory in /usr/local/etc, unless modified during the compile time.
#
# Mandatory: no
# Default:
# Include=
Include=/etc/zabbix/zabbix_agent2.d/*.conf
# Include=/usr/local/etc/zabbix_agent2.userparams.conf
# Include=/usr/local/etc/zabbix_agent2.conf.d/
# Include=/usr/local/etc/zabbix_agent2.conf.d/*.conf
### Option:PluginTimeout
# Timeout for connections with external plugins.
#
# Mandatory: no
# Range: 1-30
# Default: <Global timeout>
# PluginTimeout=
### Option:PluginSocket
# Path to unix socket for external plugin communications.
#
# Mandatory: no
# Default:/tmp/agent.plugin.sock
# PluginSocket=
####### USER-DEFINED MONITORED PARAMETERS #######
### Option: UnsafeUserParameters
# Allow all characters to be passed in arguments to user-defined parameters.
# The following characters are not allowed:
# \ ' " ` * ? [ ] { } ~ $ ! & ; ( ) < > | # @
# Additionally, newline characters are not allowed.
# 0 - do not allow
# 1 - allow
#
# Mandatory: no
# Range: 0-1
# Default:
# UnsafeUserParameters=0
### Option: UserParameter
# User-defined parameter to monitor. There can be several user-defined parameters.
# Format: UserParameter=<key>,<shell command>
# See 'zabbix_agentd' directory for examples.
#
# Mandatory: no
# Default:
# UserParameter=
### Option: UserParameterDir
# Directory to execute UserParameter commands from. Only one entry is allowed.
# When executing UserParameter commands the agent will change the working directory to the one
# specified in the UserParameterDir option.
# This way UserParameter commands can be specified using the relative ./ prefix.
#
# Mandatory: no
# Default:
# UserParameterDir=
### Option: ControlSocket
# The control socket, used to send runtime commands with '-R' option.
#
# Mandatory: no
# Default:
# ControlSocket=
ControlSocket=/tmp/agent.sock
####### TLS-RELATED PARAMETERS #######
### Option: TLSConnect
# How the agent should connect to server or proxy. Used for active checks.
# Only one value can be specified:
# unencrypted - connect without encryption
# psk - connect using TLS and a pre-shared key
# cert - connect using TLS and a certificate
#
# Mandatory: yes, if TLS certificate or PSK parameters are defined (even for 'unencrypted' connection)
# Default:
# TLSConnect=unencrypted
### Option: TLSAccept
# What incoming connections to accept.
# Multiple values can be specified, separated by comma:
# unencrypted - accept connections without encryption
# psk - accept connections secured with TLS and a pre-shared key
# cert - accept connections secured with TLS and a certificate
#
# Mandatory: yes, if TLS certificate or PSK parameters are defined (even for 'unencrypted' connection)
# Default:
# TLSAccept=unencrypted
### Option: TLSCAFile
# Full pathname of a file containing the top-level CA(s) certificates for
# peer certificate verification.
#
# Mandatory: no
# Default:
# TLSCAFile=
### Option: TLSCRLFile
# Full pathname of a file containing revoked certificates.
#
# Mandatory: no
# Default:
# TLSCRLFile=
### Option: TLSServerCertIssuer
# Allowed server certificate issuer.
#
# Mandatory: no
# Default:
# TLSServerCertIssuer=
### Option: TLSServerCertSubject
# Allowed server certificate subject.
#
# Mandatory: no
# Default:
# TLSServerCertSubject=
### Option: TLSCertFile
# Full pathname of a file containing the agent certificate or certificate chain.
#
# Mandatory: no
# Default:
# TLSCertFile=
### Option: TLSKeyFile
# Full pathname of a file containing the agent private key.
#
# Mandatory: no
# Default:
# TLSKeyFile=
### Option: TLSPSKIdentity
# Unique, case sensitive string used to identify the pre-shared key.
#
# Mandatory: no
# Default:
# TLSPSKIdentity=
### Option: TLSPSKFile
# Full pathname of a file containing the pre-shared key.
#
# Mandatory: no
# Default:
# TLSPSKFile=
####### PLUGIN-SPECIFIC PARAMETERS #######
### Option: Plugins
# A plugin can have one or more plugin specific configuration parameters in format:
# Plugins.<PluginName>.<Parameter1>=<value1>
# Plugins.<PluginName>.<Parameter2>=<value2>
#
# Mandatory: no
# Range:
# Default:
### Option: Plugins.Log.MaxLinesPerSecond
# Maximum number of new lines the agent will send per second to Zabbix Server
# or Proxy processing 'log' and 'logrt' active checks.
# The provided value will be overridden by the parameter 'maxlines',
# provided in 'log' or 'logrt' item keys.
#
# Mandatory: no
# Range: 1-1000
# Default:
# Plugins.Log.MaxLinesPerSecond=20
### Option: AllowKey
# Allow execution of item keys matching pattern.
# Multiple keys matching rules may be defined in combination with DenyKey.
# Key pattern is wildcard expression, which support "*" character to match any number of any characters in certain position. It might be used in both key name and key arguments.
# Parameters are processed one by one according their appearance order.
# If no AllowKey or DenyKey rules defined, all keys are allowed.
#
# Mandatory: no
### Option: DenyKey
# Deny execution of items keys matching pattern.
# Multiple keys matching rules may be defined in combination with AllowKey.
# Key pattern is wildcard expression, which support "*" character to match any number of any characters in certain position. It might be used in both key name and key arguments.
# Parameters are processed one by one according their appearance order.
# If no AllowKey or DenyKey rules defined, all keys are allowed.
# Unless another system.run[*] rule is specified DenyKey=system.run[*] is added by default.
#
# Mandatory: no
# Default:
# DenyKey=system.run[*]
### Option: Plugins.SystemRun.LogRemoteCommands
# Enable logging of executed shell commands as warnings.
# 0 - disabled
# 1 - enabled
#
# Mandatory: no
# Default:
# Plugins.SystemRun.LogRemoteCommands=0
### Option: ForceActiveChecksOnStart
# Perform active checks immediately after restart for first received configuration.
# Also available as per plugin configuration, example: Plugins.Uptime.System.ForceActiveChecksOnStart=1
#
# Mandatory: no
# Range: 0-1
# Default:
# ForceActiveChecksOnStart=0
# Include configuration files for plugins
Include=./zabbix_agent2.d/plugins.d/*.conf
References
First published: 12th July 2023
