Configuration of the agent

Advanced configuration of the monitoring agent called "cagent".

The agent is configured via its configuration file /etc/cagent/cagent.conf or C:\Program Files\cagent\cagent.conf.

You can use any text editor to open and edit this file.

Use notepad++ or notepad on modern windows. Do not use Word or any other text formatting software.

The option you can use vary from version to version. To get an overview of all possible option execute cagent -p on the command line. This print the current running configuration with all possible options.

Copy the options you want to change and insert it to the cagent.conf file.

Cagent version 1.6.0 supports the following options.

# operation_mode, possible values:
# "full": perform all checks unless disabled individually through other config option. Default.
# "minimal": perform just the checks for CPU utilization, CPU Load, Memory Usage, and Disk fill levels.
# "heartbeat": Just send the heartbeat according to the heartbeat interval.
# Applies only to io_mode = http, ignored on the command line.
operation_mode = "full"
# interval to push metrics to the HUB
interval = 90.0
# send a heartbeat without metrics to the HUB every X seconds
heartbeat = 15.0
# pid file location
pid = ""
# log file location
log = "/var/log/cagent/cagent.log"
# "local" for local unix socket or URL e.g. "udp://localhost:514" for remote syslog server
log_syslog = ""
# "debug", "info", "error" verbose level; can be overridden with -v flag
log_level = "error"
io_mode = "http"
hub_url = ""
hub_user = "xxxxx"
hub_password = "yyyy"
# enable gzip when sending results to the HUB
hub_gzip = true
# time limit in seconds for requests made to Hub.
# The timeout includes connection time, any redirects, and reading the response body.
# Min: 1, Max: 600. default: 30
hub_request_timeout = 30
hub_proxy = ""
hub_proxy_user = ""
hub_proxy_password = ""
# default ['avg1']
cpu_load_data_gathering_mode = ["avg1"]
# default ['avg1']
cpu_utilisation_gathering_mode = ["avg1"]
# default ['user','system','idle','iowait']
cpu_utilisation_types = ["user", "system", "idle", "iowait"]
# default ['ext3','ext4','xfs','jfs','ntfs','btrfs','hfs','apfs','fat32','smbfs','nfs']
fs_type_include = ["ext3", "ext4", "xfs", "jfs", "ntfs", "btrfs", "hfs", "apfs", "fat32", "smbfs", "nfs"]
# Exclude file systems by name, disabled by default
fs_path_exclude = []
# Having fs_path_exclude_recurse = false the specified path must match a mountpoint or it will be ignored
# Having fs_path_exclude_recurse = true the specified path can be any folder and all mountpoints underneath will be excluded
fs_path_exclude_recurse = false
# default ['free_B', 'free_percent', 'total_B', 'read_B_per_s', 'write_B_per_s', 'read_ops_per_s', 'write_ops_per_s', 'inodes_used_percent']
fs_metrics = ["free_B", "free_percent", "total_B", "read_B_per_s", "write_B_per_s", "read_ops_per_s", "write_ops_per_s", "inodes_used_percent"]
# To avoid monitoring of so-called mount binds mount points are identified by the path and device name.
# Mountpoints pointing to the same device are ignored. What appears first in /proc/self/mountinfo is considered as the original.
# Applies only to Linux
fs_identify_mountpoints_by_device = true
net_interface_exclude = []
# default ["^vnet(.*)$", "^virbr(.*)$", "^vmnet(.*)$", "^vEthernet(.*)$"]. On Windows, also "Pseudo-Interface" is added to list
net_interface_exclude_regex = ["^vnet(.*)$", "^virbr(.*)$", "^vmnet(.*)$", "^vEthernet(.*)$"]
# default true
net_interface_exclude_disconnected = true
# default true
net_interface_exclude_loopback = true
# default ['in_B_per_s','out_B_per_s','total_out_B_per_s','total_in_B_per_s']
net_metrics = ["in_B_per_s", "out_B_per_s", "total_out_B_per_s", "total_in_B_per_s"]
# If the value is not specified, cagent will try to query the maximum speed of the network cards to calculate the bandwidth usage (default)
# Depending on the network card type this is not always reliable.
# Some virtual network cards, for example, report a maximum speed lower than the real speed.
# You can set a fixed value by using <number of Bytes per second> + <K, M or G as a quantifier>.
# Examples: "125M" (equals 1 GigaBit), "12.5M" (equals 100 MegaBits), "12.5G" (equals 100 GigaBit)
net_interface_max_speed = ""
# default ['uname','os_kernel','os_family','os_arch','cpu_model','fqdn','memory_total_B']
system_fields = ["uname", "os_kernel", "os_family", "os_arch", "cpu_model", "fqdn", "memory_total_B"]
# default true
hardware_inventory = true
# default true
discover_autostarting_services_only = true
# default true
temperature_monitoring = true
# Software raid monitoring
# Auto-detect software raids by reading /proc/mdstat and monitor them
# default true
software_raid_monitoring = true
# Enable S.M.A.R.T monitoring of hard disks
# default false
smart_monitoring = false
# Path to a smartctl binary (smartctl.exe on windows, path must be escaped) version >= 7
# See
# smartctl = "C:\\Program Files\\smartmontools\\bin\\smartctl.exe"
# smartctl = "/usr/local/bin/smartctl"
smartctl = ""
# target value to start the analysis
threshold = 10.0
# threshold compare function, possible values: 'lt', 'lte', 'gt', 'gte'
function = "lt"
metric = "idle"
# should be one of values of cpu_utilisation_gathering_mode
gathering_mode = "avg1"
# number of processes to return
report_processes = 5
# how much time analysis will continue to perform after the CPU utilisation returns to the normal value
trailing_process_analysis_minutes = 5
# Enable monitoring of hardware health for MegaRaids
# reported by the storcli command-line tool
# Refer to
# On Linux make sure a sudo rule exists. The storcli command is always executed via sudo. Example:
# cagent ALL= NOPASSWD: /opt/MegaRAID/storcli/storcli64 /call show all J
# Enable on Windows:
# binary = 'C:\Program Files\storcli\storcli64.exe'
# Enable on Linux:
# binary = '/opt/storcli/sbin/storcli64'
binary = ""
# Settings for the jobmon wrapper for the job monitoring
# Path to spool dir
spool_dir = "/var/lib/cagent/jobmon"
# Record the last 4 KB of the error output. Default: true
record_stderr = true
# Record the last 4 KB of the standard output. Default: false
record_stdout = false
# Failed jobs will be processed as alerts. Possible values alert, warning or none. Default: alert
severity = "alert"
# Monitor the available updates using the operating system updates service
# Uses apt-get, apt-check or yum, Requires sudo rules. DEB and RPM packages install them automatically.
# On Windows, it requires windows updates to be switched on, ignored if windows updates are switched off
# Set 'false' to disable checking available updates
enabled = true
# Maximum time the package manager is allowed to spend fetching available updates, ignored on windows
fetch_timeout = 30
# Check for available updates every N seconds. Minimum is 300 seconds
check_interval = 14400
# Monitor the basic performance metrics of a MySQL or MariaDB database
# ** Do not use in production environments **
# Set 'false' to disable checking available updates
enabled = false
# Use or the path to the mysql.socket, connecting to remote databases is not supported
connect = ""
# Create a user with minimal rights
# mysql > GRANT USAGE ON *.* TO [email protected] IDENTIFIED BY '<password>';
user = ""
# Maximum time the package manager is allowed to spend fetching available updates
password = ""
# Maximum time to wait for mysql server to connect using provided credentials
connect_timeout = 0.0
# Cagent monitors all running processes and reports them for further processing to the Hub.
# On heavy loaded systems or if you don't need process monitoring at all,
# you can change the following settings.
enabled = true
# Monitor kernel tasks identified by process group 0
# Ignored on Windows.
enable_kerneltask_monitoring = true
# The process list is sorted by PID descending. Only the top N processes are monitored.
max_number_monitored_processes = 500
# Control how cagent installs self-updates. Windows-only
# Set 'false' to disable self-updates
enabled = false
# URL for updates feed
url = ""
# Cagent will check for new versions every N seconds
check_interval = 21600
# Cagent monitors all running docker containers and reports them for further processing to the Hub.
# You can change the following settings.
# Set 'false' to disable docker monitoring'
enabled = true


Operation Mode: If you want to run the agent in the minimal operation mode, insert the following line to the cagent.conf file

operation_mode = "minimal"

Do not monitor software raids: On NAS for example Synology RAIDs are often created for all available bays even if they are empty. The monitoring will consider the raid as broken because devices are missing. To not get bothered by false alerts, switch of the RAID monitoring by adding this line to the cagent.conf file:

software_raid_monitoring = false

Exclude a filesystem (drive letter) from the monitoring: If you want to exclude a Window drive from being monitored, enter the following line to cagent.conf:

fs_path_exclude = ["D:"]

Restart the agent after any change

Any changes to the config file require a restart of the service. On Linux execute systemctl restart cagent. On Windows use the service control panel or execute on the command line.

Restart the agent
sc stop cagent
sc start cagent