Ubuntu Manpage: monitorix.conf - Configuration file for Monitorix.

NAME

       monitorix.conf - Configuration file for Monitorix.

DESCRIPTION

       Monitorix  is  a free, open source, lightweight system monitoring tool designed to monitor
       as many services and system resources as possible. It has  been  created  to  be  used  on
       production  Linux/UNIX  servers, but due to its simplicity and small size may also be used
       to monitor embedded devices as well.

       It consists mainly of two programs: a collector, called monitorix, which is a Perl  daemon
       that  is  started  automatically  like  any  other system service, and a CGI script called
       monitorix.cgi. Since 3.0 version Monitorix includes its own HTTP server built in,  so  you
       don't need to install any web server to use it.

       Every time monitorix is started it reads the configuration file from the path specified in
       the command line (using the -c option), and once checked, it creates the  index.html  file
       that will act as the Monitorix main page.

       It  also  creates  a  file  called  <base_dir>/cgi/monitorix.conf.path  that  includes the
       absolute path of the configuration file. This  file  will  be  read  by  monitorix.cgi  to
       determine the exact location of the configuration file.

CONFIGURATION OPTIONS

IMPORTANT NOTE: these options have default values that might vary depending on your
operating system. Please check the configuration files in /etc/monitorix/conf.d/.

Blank lines are ignored, and whitespace before and after a token or value is ignored as
well as tabulators, although a value can contain whitespace within. Lines which begin with
a # are considered comments and ignored.

If you want to comment out a large block you can use C-style comments. A /* signals the
begin of a comment block and the */ signals the end of the comment block.

If an option has multiple values their must be separated by comma.

title
A free description of the server; where it is located, the Company name, etc.

Default value: Place a Title Here

hostname
The name of the host.

Default value:

theme_color
RRDtool comes with a default white theme, and since Monitorix introduces its own
black theme, you have two predefined themes to choose from.

Default value: black

refresh_rate
The refresh rate (in seconds) of the statistics web page displayed in your browser.
If set to 0, page refreshing is disabled.

Default value: 150

iface_mode
The interface mode defines the manner in which data is shown in the browser. Since
version 1.4.0 it has been possible to display the graphic data using plain text
tables. This allows Monitorix to be used by those running screen reader software,
and also simplifies automatic data processing through scripts.

The possible values are:
graph for rendered graphs.
text for plain text representation.

Default value: graph

enable_zoom
Zoom allows double clicking any graph in order to see a larger version (zoomed in).
This is especially useful for seeing additional detail.

Default value: y

netstats_in_bps
This option toggles network values between bits (bps) and Bytes (Bps) per second.
By default the values will be shown in Bytes per second (Bps).

Default value: n

netstats_mode
This option toggles network visualization mode between overlapped (input and output
values appear one in front the other) and separated (input values appear on top and
output values below, in negative).

Default value: overlapped

disable_javascript_void
This option enables or disables the use of javascript:void-URLs when opening
windows with zoomed graphs. Some people likes to open links in the background by
pressing the middle mouse button in Firefox, and with the default javascript:void-
URLs the only they get is an empty window with nothing in it.

Default value: n

temperature_scale
This option toggles between values in Celsius or in Fahrenheit in those graphs that
represent temperatures.

The possible values are:
c for Celsius.
f for Fahrenheit.

Default value: c

show_gaps
This option, when enabled, shows the gaps (missing data) in the graphs. This is
specially useful to detect if the server or Monitorix were stopped for a while, or
any other unavailability.

In order to be able to locate those gaps easily in each graph, it uses the white
color in the default black theme and the black color in the white theme. These
default colors are defined in monitorix.conf so they can be changed as any other
option.

Default value: n

global_zoom
This option zooms all the graphs (including the legend's font size) by the given
amount. The factor must be greater than 0 and it accepts decimal values.

This is specially useful for people with big screens that either want to avoid
using the browser feature to zoom the contents of the window and for those that
watch the graphs from certain distance.

Keep in mind that the contents of the graphs remains with the same detail level all
the time, and that it doesn't affects to the standard zoomed graph that appears
when clicking in the picture.

Default value: 1

max_historic_years
This option defines the maximum number of years of historical data in all graphs.

WARNING: Every time this value is extended Monitorix will resize every .rrd file
accordingly, removing all historical data.

There is no longer any upper limit for this value.

Default value: 1

accept_selfsigned_certs
This option forces to accept self-signed certificates when collecting values
remotely using HTTPS protocol.

Default value: y

priority
Sometimes when a server is under heavy use, Monitorix might be unable to collect
some statistical data due to its normal priority (0 by default). This makes
monitoring useless because graphs are empty during that hard period of time.

In order to mitigate this situation this option sets the priority in which
Monitorix will be scheduled by the kernel. The accepted range of values is the same
as in the setpriority() system call: that is, from -20 (maximum priority) to 19
(lowest priority).

Default value: 0

image_format
This is the format of each generated graph. There are only two possible values: PNG
and SVG.

Default value: PNG

enable_parallelizing
This option will fork an independent process for each graph in order to speed up
graph generation in multi-core systems. It's best to keep it disabled on unicore
processors.

Default value: y

enable_rrd_lock
This option will synchronise the rrd file access by creating the file
/tmp/monitorix.lock and use it via flock. The read lock during the cgi call can be
disabled on a per call basis via setting the environment variable INHIBIT_LOCKING.
This is useful for modules that call the cgi function internally.

Default value: n

enable_relative_urls
This option will change all URLs in the graphs to relative, instead of absolute
URLs.

Default value: n

include_dir
The main configuration file is usually called monitorix.conf and its location is
provided as part of the command line arguments. In addition, other configuration
files may be loaded placing them in the directory pointed by this option. The names
must end with .conf to be included.

This option is mainly intended to include third-party modules with their own
configuration files without having to modify any file from your Monitorix
installation. All modules are located in /usr/lib/monitorix (in some operating
systems that path can change).

All the configuration files in there will be loaded in alphabetic order, so the
last file loaded will overwrite any previous option.

Default value: /etc/monitorix/conf.d

additional_graph_name
This is an optional configuration option for configuration files in include_dir. It
takes a comma separated list of additional modules that is appended to the
graph_name option. This enables you to add custom modules without changing the
monitorix.conf or copy all names from graph_name to your config file.

Default value: None

ip_default_table
This option will define in which table Monitorix will put all iptables rules for
network traffic accounting monitoring. It only works on Linux.

Although this is a global option, only the graphs port, nginx and traffacct are
affected by it.

Default value: filter

ipv6_disabled
This option enables or disables the use of the ip6tables command. It only works on
Linux.

Although this is a global option, only the graph port is currently affected by it.

Default value: n

url_prefix_proxy
This option forces monitorix.cgi to bypass the URL building. This is specially
useful when Monitorix is used behind a reverse proxy.

An example would be: http://myexternalwebsite.com

Default value:

enable_hourly_view
This option enables or disables the ability to select the hourly view in the main
page.

No .rrd file will change by selecting this option and the historical data won't be
affected.

Default value: n

user_agent_id
This option defines the string to be used to identify Monitorix in the HTTP
requests. Its value will be sent as the "User-Agent" header.

The default value will depend on the current Perl version in your system. An
example would be libwww-perl/5.833.

enable_back_button
This option enables or disables the ability to go back to the main page from the
graphs page without using the browser's back button.

It will show a back arrow in the upper-left corner and it is specially useful for
people using the browser in full-screen mode.

Default value: n

rrdtool_extra_options
This option permits create a comma-separated list of RRDtool options that will be
included in all graphs. This is specially useful if you want to take advantage of
an specific RRDtool graphics option.

An example would be:

rrdtool_extra_options = "--grid-dash=1:0, --no-legend"

use_external_firewall
By default, Monitorix creates a set of iptables rules to collect the amount of
network activity that some graphs (port.pm and nginx.pm) need. This might be a
problem for people using an external firewall that could eventually remove such
iptables rules created by Monitorix. In these cases, you may want to set this
option as y to tell Monitorix to not create such iptables rules, but expect that
they will be already created by an external software.

Keep in mind that the rule names created in your firewall must coincide with the
names that Monitorix expects to find for each case. Familiarize yourself with the
iptables rules created automatically by Monitorix before enabling this option.

Default value: n

base_dir
This is the absolute path to the directory where all the web elements are located:

cgi/ directory where resides monitorix.cgi.
imgs/ directory for the .png graph images.
index.html Monitorix main page.
logo_bot.png Monitorix bottom logo.
logo_top.png Monitorix top logo.
monitorixico.png Monitorix favicon logo.

Default value: /var/lib/monitorix/www/
(depends on the operating system)

base_lib
This is the absolute path to the directory where all of the monthly reports, daily
traffic usage, and RRD files are located:

reports/ monthly reports localization directory.
usage/ daily traffic usage data directory.
*.rrd RRD files.

Default value: /var/lib/monitorix/
(depends on the operating system)

base_url
This is the URL prefix that Monitorix utilizes when referring to its own pages and
files.

Default value: /monitorix

base_cgi
This is the URL prefix that Monitorix utilizes when referring to monitorix.cgi.

Default value: /monitorix-cgi

HTTP built-in server
enabled
This enables or disables the HTTP server that Monitorix has built-in. This is
specially useful for system administrators that don't want to install a web server
(Apache, Lighttpd, Nginx, etc.) to see the Monitorix graphs.

Default value: y

host
This option takes an optional host address for this server to bind to. If none is
specified (default) it will bind to all interfaces.

Default value:

port
This is the network port from where the HTTP server will listen on.

Default value: 8080

user/group
This sets the user and group that the HTTP server will run as.

Default value for user: nobody
Default value for group: nobody

log_file
This is the path to the HTTP server log file.

If you leave this option blank or undefined Monitorix will log using the standard
file descriptors. This is specially useful on systemd-based systems, you'll need to
use the command journalctl -u monitorix to see the logs.

Default value: /var/log/monitorix-httpd

hosts_deny
This is a comma delimited set of IP addresses which are not permitted to access
Monitorix graphs. There is the special keyword called all that can be used to deny
all IP addresses.

The access control uses the same approach as in the TCP-Wrappers; the search stops
at the first match:

- Access will be granted when an IP address matches an entry in the
hosts_allow list.
- Otherwise, access will be denied when an IP address matches an entry in the
hosts_deny list.
- Otherwise, access will be granted.

Default value:

hosts_allow
This is the opposite of hosts_deny option. IP addresses listed here are permitted
to access Monitorix graphs. There is also the special keyword called all that can
be used to allow access to all IP addresses.

Default value:

https_url
This will force to use the prefix https:// in all links. This is special useful if
you plan to use a reverse-proxy HTTPS server in front of the Monitorix HTTP built-
in server.

Default value: n

autocheck_responsiveness
There is a well known problem with the HTTP built-in server that Monitorix
implements using the Perl module 'HTTP::Server::Simple'. It looks like it's pretty
weak to the common attacks that any web server receives every day. As a consequence
of that, it just hangs, and when you want to see the stats of your server, you just
see your browser waiting for a response that never comes, which ends up with a
timeout. In these cases, you are forced to login to your server and restart
Monitorix, in order to refresh the HTTP built-in server.

So in order to mitigate (hopefully) all this annoying hangups, this options acts
like an autocheck to control the responsiveness of the HTTP server on every minute,
and in case of no response then it will be restarted automatically.

Default value: y

HTTP built-in server with access authentication
enabled
This enables or disables the authentication mechanism to control access to pages
and other resources. The only allowed mechanism is Basic and uses the 401 status
code and the WWW-Authenticate response header.

It's highly recommended to set this option according your needs before start
Monitorix.

For more information about the Basic access authentication mechanism and its
security implications, please refer to
http://en.wikipedia.org/wiki/Basic_access_authentication.

Default value: n

msg
This option sets the Realm to be used in the authentication. That message should
appear in the client dialog box to help user to identify the secure area.

Default value: Monitorix: Restricted access

htpasswd
This option sets the path to the password file that was created with the help of
the htpasswd.pl script. That script encrypts and validates passwords using the
system's crypt() routine. If your Monitorix package doesn't come with that script,
you may use the similar htpasswd(1) program provided with the Apache web server.

The format of the password file consist of one or more lines with a username and
password separated by a colon.

The following is an example of a password file:

paul:oGkEsQK6RYIII
peter:HF1r7qRL4Kg6E

Since the script uses the crypt() algorithm, only the first 8 characters of the
password are used to form the password. If the supplied password is longer, the
extra characters will be silently discarded.

WARNING: don't use the character colon ':' as part of your name or password since
this character is used as field separator.

Default value: /var/lib/monitorix/htpasswd

hosts_deny
This is a comma delimited set of IP addresses which will be forced to do
authentication. There is the special keyword called all that can be used to deny
all IP addresses.

The access control uses a similar approach as in the TCP-Wrappers; the search stops
at the first match:

Default value: all

hosts_allow
This is the opposite of hosts_deny option. IP addresses listed here will bypass the
authentication mechanism (even when it is enabled). It helps in specific cases like
to avoid to have to include the auth credentials in the url_prefix of the
emailreports module. There is also the special keyword called all that can be used
to allow access to all IP addresses.

Default value:

Log files pathnames
log_file
This is the path of the Monitorix log file. Please check this file periodically and
especially after every update to confirm proper operation.

Default value: /var/log/monitorix

secure_log
This is the path to the system log (also known as auth.log, etc.) Monitorix uses
this file to report SSH, POP3, FTP and Telnet successful logins.

Default value: /var/log/secure

mail_log
This is the path to the mail log file. Monitorix uses this file to report messages
sent (supporting Sendmail and Postfix formats), and the MailScanner log format for
spam-mail and virus-mail alerts.

Default value: /var/log/maillog

milter_gl
This is the path to the dump file of milter-greylist.

Default value: /var/milter-greylist/greylist.db

imap_log
This is the path to the IMAP (Dovecot or UW-IMAP) log file. Monitorix uses this
file to report IMAP and POP3 successful logins.

Default value: /var/log/imap

hylafax_log
This is the path to the Hylafax log file. Monitorix uses this file to report
successful FAX dispatches.

Default value: /var/spool/hylafax/etc/xferfaxlog

cups_log
This is the path to the CUPS page log file. Monitorix uses this file to report on
print jobs.

Default value: /var/log/cups/page_log

ftp_log
This is the path to the FTP server (ProFTPD, vsftpd or Pure-FTPd) log. Monitorix
uses this file to report FTP successful logins and other FTP-related information.

Default value: /var/log/proftpd/access.log

fail2ban_log
This is the path to the Fail2ban log file. Monitorix uses this file only if the
option graph_mode has the value rate.

Default value: /var/log/fail2ban.log

spamassassin_log
This is the path to the Spamassassin log file. Monitorix uses this file to report
spam-mail alerts.

Default value: /var/log/maillog

clamav_log
This is the path to the Clamav log file. Monitorix uses this file to report virus-
mail alerts.

Default value: /var/log/clamav/clamav.log

cg_logdir
This is the path to the CommuniGate logs directory. Monitorix uses these files to
report the number of mail messages successfully received and sent, and to report
IMAP and POP3 successful logins.

Default value: /var/CommuniGate/SystemLogs/

squid_log
This is the path to the Squid log file. Monitorix uses this file to report on Squid
Proxy requests.

Default value: /var/log/squid/access.log

imap_log_date_format
This is the Dovecot date format as it appears in the imap_log file.

Default value: %b %d

secure_log_date_format
This is secure_log date format.

Default value: %b %e

Piwik tracking code
enabled
This enables the inclusion of the Piwik tracking code in the main index.html file.
Please refer to http://piwik.org/docs/tracking-api/ for more information on how to
fill these fields.

Default value: n

Enable or disable graphs
graph_enable
This enables or disables the monitoring of each graph. Placing a y on a desired
graph and restarting Monitorix will automatically create the RRD file for that
graph and start gathering information according to its settings.

System load average and usage (system.pm)
This graph shows information about system load average (classical UNIX triplet), memory
allocation, active processes (on Linux brought directly from the /proc directory), entropy
and the system uptime.

loadavg_enabled
This section enables or disables the alert capabilities for this graph. Only the
alert for the average CPU load is currently implemented. It works as follows:

This alert uses the minimum value between the second and the third load averages
(those that represent the last 5 and 15 minutes), and if it reaches the
loadavg_threshold value for the interval of time defined in loadavg_timeintvl,
Monitorix will execute the external alert script defined in loadavg_script.

The idea to use min(load5, load15) is to obtain a more symmetric curve and a sooner
cancellation of the alert.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

loadavg_timeintvl
This is the period of time (in seconds) that the threshold needs to be exceeded
before the external alert script is executed.

Default value: 3600

loadavg_threshold
This is the value that needs to be reached or exceeded within the specified time
period in loadavg_timeintvl to trigger the mechanism for a particular action, which
in this case is the execution of an external alert script.

The value of this option is compared against the last 15 minutes of CPU load
average.

Default value: 5.0

loadavg_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in loadavg_timeintvl.
2nd - the value currently defined in loadavg_threshold.
3rd - the current 15min CPU load average.

Default value: /path/to/script.sh

time_unit
This is the unit in which will appear the values in the uptime graph. Possible
values are: minute, hour or day. It will default to day even if none is specified.

Global kernel usage (kern.pm)
Note that the VFS graph is just informative of how the kernel is balancing its tables.
graph_mode
This changes the layout of the kernel usage graph, the possible values are r for a
real graph, or s for a stacked graph (every line or area is stacked on top of the
previous element).

Default value: r

list
This is the list of values offered in modern Linux kernels. Older Linux kernels or
other Operating Systems may not have all of them. Placing a y or an n will enable
or disable the value in the graph.

Kernel usage per processor (proc.pm)
max
This is the number of processors or cores that your system has. There is no limit,
however keep in mind that every time this number is changed Monitorix will resize
the proc.rrd file accordingly, removing all historical data.

Default value: 4

graphs_per_row
This is the number of processor graphs that will be put in a row. Consider the
interaction of this parameter with the size and data options (below) in order to
adjust the size and number of graphs in relation to your horizontal screen size.

Default value: 2

size
This option sets the size of all processors graphs.

The possible values are:
large for 750x180 graphs.
main for 450x150 graphs.
medium for 325x150 graphs.
medium2 for 325x70 graphs.
small for 200x66 graphs.
mini for 183x66 graphs.
tiny for 110x40 graphs.

Default value: medium

DATA
This option will completely enable or disable the legend in the processor graphs.

Default value: y

AMD power consumption (amdenergy.pm)
This graph is able to monitor the power draw of an unlimited number of AMD CPUs if the
amd_energy driver and sensors is available. I will show power draw of the cores and the
socket and the non-core part of the power draw. It is calculated by subtracting the sum of
the core power draw from the socket power draw.

list
This is a list of groups of CPU sensors you want to monitor with the same names as
they appear in your sensors(1) command. Each group will become a plot and there may
be an unlimited number of groups. You can define device names like amd_energy-
isa-0000.

WARNING: Every time the number of groups or the size of the groups in this option
changes, Monitorix will resize the amdenergy.rrd file accordingly, removing all
historical data.

To collect the CPU power usage the energy counters from the sensors command via the
amd_energy driver is used and a power consumption in the monitoring time interval
calculated.

It is recommended that you first check if the sensors output is able to provide
energy counters (EcoreXXX and EsocketX) from the CPU(s) that you plan to monitor.
For example check sensors for available sensors. You may test this with the
following command (root privileges might be needed to access the energy counters):

# sensors amd_energy-isa-0000
amd_energy-isa-0000
Adapter: ISA adapter
Ecore000: 31.81 kJ
Ecore001: 27.54 kJ
Ecore002: 25.44 kJ
Ecore003: 27.08 kJ
Ecore004: 48.45 kJ
Ecore005: 41.39 kJ
Ecore006: 42.49 kJ
Ecore007: 39.88 kJ
Ecore008: 109.67 kJ
Ecore009: 107.59 kJ
Ecore010: 115.21 kJ
Ecore011: 168.80 kJ
Ecore012: 61.64 kJ
Ecore013: 49.86 kJ
Ecore014: 42.20 kJ
Ecore015: 51.55 kJ
Ecore016: 35.41 kJ
Ecore017: 35.87 kJ
Ecore018: 33.91 kJ
Ecore019: 34.40 kJ
Ecore020: 102.11 kJ
Ecore021: 238.25 kJ
Ecore022: 86.68 kJ
Ecore023: 99.13 kJ
Ecore024: 23.79 kJ
Ecore025: 23.30 kJ
Ecore026: 23.48 kJ
Ecore027: 23.63 kJ
Ecore028: 23.53 kJ
Ecore029: 22.10 kJ
Ecore030: 20.83 kJ
Ecore031: 19.45 kJ
Esocket0: 21.12 MJ

If you see good results as above, you can add it to the group 0 like this:

<list>
0 = amd_energy-isa-0000
1 = amd_energy-isa-0001
</list>

number_of_cores
This list sets the number of cores for the CPUs specified in the list option. It is
required to specify the number of cores is for each CPU in list

<number_of_cores>
amd_energy-isa-0000 = 64
amd_energy-isa-0001 = 32
</number_of_cores>

map
This list complements the list option. It basically allows you to change the CPU
name that will appear in the graph, hiding the sensor name. If no association is
defined, then Monitorix will display the name of the CPU device as it is specified
in the config file.

<map>
amd_energy-isa-0000 = AMD CPU 1
amd_energy-isa-0001 = AMD CPU 2
</map>

desc
This list complements the list option. It allows you to include a title for every
group of CPUs. The title will appear in the title above the plot.

<desc>
0 = Socket 1 power distribution
1 = Socket 2 power distribution
</desc>

socketpower_enabled
This section enables or disables the alert capabilities for this graph; the alert
for the socket power draw. It works as follows:

If the socket power draw of any of the specified CPU device reaches or succeeds the
socketpower_threshold (the interval of time is not used here), Monitorix will
execute the external alert script defined in socketpower_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

socketpower_timeintvl
Not used in this alert.

Default value: None

socketpower_threshold
This is the value that needs to be reached or succeeded to trigger the mechanism
for a particular action, which in this case is the execution of an external alert
script.

Default value: None

socketpower_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in socketpower_timeintvl.
2nd - the value currently defined in socketpower_threshold.
3rd - the current socket power draw.

Default value: /path/to/script.sh

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

gap_on_all_nan
This option, when enabled via y, combined with the show_gaps option shows gaps only
if all data points are nan instead of requiring only one to be nan for a gap. This
can be useful if not all sensor data are required for normal operation.

Default value: n

Intel RAPL power consumption (intelrapl.pm)
This graph is able to monitor the power draw of an unlimited number of Intel RAPL
supporting devices like Intel CPU packages. For example it can (if the device RAPL data is
available) show power draw of the cores, integrated GPU, package, DRAM and the non-core
part of the power draw. The non-core power draw composition can be specified by setting
which parts will be subtracted from the package power draw.

list
This is a list of groups of CPU sensors you want to monitor with an arbitrary name.
Each group will become a plot and there may be an unlimited number of groups. You
can define sensor names like ore and ackage.

WARNING: Every time the number of groups or the size of the groups in this option
changes, Monitorix will resize the intelrapl.rrd file accordingly, removing all
historical data.

To collect the CPU power usage the energy counters from the intel-rapl framework
are used and a power consumption in the monitored time interval calculated.

It is recommended that you first check if the intel-rapl class tree and collect
your desired energy counters from the devices that you plan to monitor. For example
check tree /sys/class/powercap/intel-rapl for available energy_uj energy counters.
The corresponding name files helps identifying the sensors.

You can add it to the group 0 like this:

<list>
0 = core, uncore, package, dram
1 = dram
</list>

list_item_names
This list complements the list option. It allows you to change the group name that
will appear in the graph, hiding the sensor name. If no association is defined,
then Monitorix will display the name of the device as it is specified in the config
file.

<list_item_names>
0 = CPU 1
1 = DRAM modules
</list_item_names>

sensors
This list sets the energy counter files for the devices specified in the list
option.

<sensors>
core = /sys/class/powercap/intel-rapl:0:0/energy_uj
uncore = /sys/class/powercap/intel-rapl:0:1/energy_uj
package = /sys/class/powercap/intel-rapl:0/energy_uj
dram = /sys/class/powercap/intel-rapl:0:2/energy_uj
</sensors>

sensor_names
This list complements the sensors option. It allows you to change the device name
that will appear in the graph, hiding the device name. If no association is
defined, then Monitorix will display the name of the device as it is specified in
the config file.

<sensor_names>
package = Package
core = Cores
uncore = IGP
dram = DRAM
</sensor_names>

package_sensors
This list allows you to set a device name for the package device. This specified
device is used as total power draw to calculate the non-core power draw by
subtracting the power draw of the devices specified for the same group in
ackage_sensors. Non-core power draw will not be shown if no package sensor is
specified for a certain group.

<package_sensors>
0 = package
</package_sensors>

package_content
This list complements the package_sensors option. It allows specify the devices
that are contained in the total package power draw. This information is needed if
you want to visualize non-core power draw. Non-core power draw will be calculated
by subtracting the sum power draw of a package content group from the package
power draw.

<package_content>
0 = core, uncore
</package_content>

noncore_names
This list allows you to change the non-core name for a certain group that will
appear in the graph legend.

<noncore_names>
0 = Non-Core
</noncore_names>

desc
This list complements the list option. It allows you to include a title for every
group of devicess. The title will appear in the title above the plot.

<desc>
0 = CPU power distribution
1 = Memory power distribution
</desc>

sum
This list allows you to add a specific sum of devices to the plot of a certain
group. No sum will be shown if not specified for the group.

<sum>
0 = package, dram
</sum>

sum_names
This list complements the seum option. It allows specify the name of the sum if
desired.

<sum_names>
0 = Package + DRAM
</sum_names>

packagepower_enabled
This section enables or disables the alert capabilities for this graph; the alert
for the package power draw. It works as follows:

If the package power draw specified by package_sensors of any of the specified
device reaches or succeeds the packagepower_threshold (the interval of time is not
used here), Monitorix will execute the external alert script defined in
packagepower_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

packagepower_timeintvl
Not used in this alert.

Default value: None

packagepower_threshold
This is the value that needs to be reached or succeeded to trigger the mechanism
for a particular action, which in this case is the execution of an external alert
script.

Default value: None

packagepower_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in packagepower_timeintvl.
2nd - the value currently defined in packagepower_threshold.
3rd - the current package power draw.

Default value: /path/to/script.sh

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

show_noncore_info
This option, when enabled via y, enable showing description string in the legend
how the non-core part is calculated.

Default value: n

max_number_of_values_per_group
This option sets the maximum number of devices per group if more values are
required.

WARNING: Every time the max_number_of_values_per_group value changes, Monitorix
will resize the intelrapl.rrd file accordingly, removing all historical data.

Default value: 10

HP ProLiant System Health (hptemp.pm)
list
This list will hold the defined temperature sensors for each graph. You must have
installed the command hplog that comes with HP ProLiant System Health Application
and Command Line Utilities.

Each graph has a limited number of IDs:

graph_0 up to 8 IDs.
graph_1 up to 6 IDs.
graph_2 up to 6 IDs.

The following is a configuration example of selected IDs:

# hplog -t
ID TYPE LOCATION STATUS CURRENT THRESHOLD
1 Basic Sensor Ambient Normal 75F/ 24C 107F/ 42C
2 Basic Sensor CPU (1) Normal 104F/ 40C 179F/ 82C
3 Basic Sensor CPU (2) Normal ---F/---C 179F/ 82C
4 Basic Sensor Memory Board Normal ---F/---C 188F/ 87C
5 Basic Sensor Memory Board Normal 82F/ 28C 188F/ 87C
6 Basic Sensor Memory Board Normal ---F/---C 188F/ 87C
7 Basic Sensor System Board Normal 89F/ 32C 192F/ 89C
8 Basic Sensor System Board Normal ---F/---C 192F/ 89C
9 Basic Sensor System Board Normal 84F/ 29C 192F/ 89C
10 Basic Sensor System Board Normal 118F/ 48C 230F/110C
11 Basic Sensor System Board Normal 96F/ 36C 192F/ 89C
12 Basic Sensor System Board Normal 84F/ 29C 154F/ 68C
13 Basic Sensor System Board Normal 87F/ 31C 154F/ 68C
14 Basic Sensor System Board Normal 89F/ 32C 156F/ 69C
15 Basic Sensor System Board Normal 93F/ 34C 161F/ 72C
16 Basic Sensor Ambient Normal ---F/---C 192F/ 89C
17 Basic Sensor System Board Normal ---F/---C 192F/ 89C
18 Basic Sensor SCSI Backplane Normal 32F/ 0C 140F/ 60C

<list>
graph_0 = 2, 3
graph_1 = 1, 5, 18
graph_2 = 7, 9, 10, 11, 12, 13
</list>

alerts
This optional list enables the alert capabilities for this graph and complements
with the list option. Each alert has three fields separated by comma: the time
interval, the threshold and the path to the script to be executed.

The time interval is the period of time (in seconds) that the threshold needs to be
exceeded before the external script is executed.

The threshold is the temperature that needs to be reached or exceeded within the
specified time in time interval to execute the external script.

The script is the full path name of the script that will be executed by this alert.

Each defined sensor has its own alert.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

The following is an example of an alert defined for the first temperature sensor:

<alerts>
2 = 3600, 40, /path/to/script.sh
</alerts>

Such alert means that if the value of the sensor number 2 reaches or exceeds 40
during at least one hour (3600 seconds) the script in /path/to/script.sh will be
executed.

The external script will receive the following arguments:

1st - the value defined as time interval.
2nd - the value defined as threshold.
3rd - the value of the sensor.

LM-Sensors and GPU temperatures (lmsens.pm)
list
In this list you may specify the sensors you want to monitor with the same names as
they appear in your sensors(1) command.

For example, imagine a sensors(1) output like this:

# sensors
coretemp-isa-0000
Adapter: ISA adapter
Core 0: +51.0°C (high = +78.0°C, crit = +100.0°C)

coretemp-isa-0001
Adapter: ISA adapter
Core 1: +49.0°C (high = +78.0°C, crit = +100.0°C)

f71882fg-isa-0a00
Adapter: ISA adapter
3.3V: +3.30 V
Vcore: +1.21 V (max = +2.04 V)
Vdimm: +1.82 V
Vchip: +1.38 V
+5V: +5.00 V
12V: +14.37 V
5VSB: +4.33 V
3VSB: +3.30 V
Battery: +3.22 V
CPU: 2035 RPM
System: 1765 RPM ALARM
Power: 2110 RPM ALARM
Aux: 2080 RPM ALARM
M/B Temp: +36.00 C
CPU Temp: +29.00 C

Then you may want to configure that list as:

<list>
core0 = Core 0
core1 = Core 1
mb0 = M/B Temp
cpu0 = CPU Temp
fan0 = CPU
fan1 = System
fan2 = Power
fan3 = Aux
volt0 = 3.3V
volt1 = VCore
volt2 = Vdimm
volt3 = Vchip
volt4 = \+5V
volt5 = 12V
volt6 = 5VSB
volt7 = 3VSB
volt8 = Battery
gpu0 = nvidia
</list>

Note that you need to escape the plus and minus signs in the voltage labels. It
also recommended to enclose the values using double quotes.

The Fan values can be prefixed with the words rpm: (optional) or percent:. This
will tell to Monitorix how to treat these values in the graph and in the case of
the later it will add the percentage symbol (%) right after the value. Just like
this:

<list>
fan0 = percent:Power
</LIST>

The last one, gpu0, is set here just in case you have a supported graphics card and
want to monitor its temperature. Currently only NVIDIA and ATI graphic cards are
supported; with the values nvidia and ati respectively, and it requires the
official NVIDIA or ATI drivers.

If the temperature of your graphical card appears in the output of lm_sensors, then
you can tell Monitorix to use it instead of using the official NVIDIA or ATI
drivers. In that case, you need to prefix with lmsensors: the name of the
temperature value. Just like this:

<list>
gpu0 = lmsensors:edge
</list>

This list has the following maximums allowed:

Up to 16 core keys (from core0 to core15).
Up to 2 mb keys (mb0 and mb1).
Up to 4 cpu keys (from cpu0 to cpu3).
Up to 9 fan keys (from fan0 to fan8).
Up to 12 volt keys (from volt0 to volt11).
Up to 9 gpu keys (from gpu0 to gpu8).

IMPORTANT NOTE: Sometimes the output of lm_sensors shows the same exact names for
different temperature values and so Monitorix is unable to differentiate them. If
you are under this situation please check the issue #131
(https://github.com/mikaku/Monitorix/issues/131) to solve this situation.

desc
This list complements the list option. It basically allows you to change the name
that will appear in the graph, hiding the real name of the sensor. If no
association is defined, then Monitorix will display the name of the key (left side)
in the desc option (in uppercase in some graphs).

<desc>
mb0 = M/B
fan0 = CPUFan
gpu0 = ATI
</desc>

Please note that in the default graph all names are limited to 5 characters in
order to fit up to 9 different values. In the zoomed graphs the limit is 8
characters.

The time interval is the period of time (in seconds) that the threshold needs to be
exceeded before the external script is executed.

The threshold is the temperature or volts, or whatever that needs to be reached or
exceeded within the specified time in time interval to execute the external script.

The script is the full path name of the script that will be executed by this alert.

Each defined sensor has its own alert.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

The following is an example of an alert defined for the first temperature sensor:

<alerts>
core0 = 3600, 40, /path/to/script.sh
</alerts>

Such alert means that if the value of the sensor core0 reaches or exceeds 40 during
at least one hour (3600 seconds) the script in /path/to/script.sh will be executed.

The external script will receive the following arguments:

1st - the value defined as time interval.
2nd - the value defined as threshold.
3rd - the value of the sensor.

cmd
This is the command that will be used to gather statistics. This option may also be
used to add new sensors values not covered by LM-Sensors by referencing an external
script which executes the command sensors and others.

Default value: sensors

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead
of 0. This is useful when 0 could be mistaken for valid data.

Default value: n

gap_on_all_nan
This option, when enabled via y, combined with the show_gaps option shows
gaps only if all data points are nan instead of requiring only one to be nan
for a gap. This can be useful if not all sensor data are required for normal
operation.

Default value: n

Generic sensors statistics (gensens.pm)
This graph helps to monitor up to three (so far) different sensors: temperatures, CPU
frequencies and battery status which, depending of your machine, they should appear in the
/sys directory.

list
This is a list of an unlimited number of groups to define the sensors to monitor.
Each group is numbered starting from 0, and each one can hold up to 9 different
entries separated by comma which corresponds to the names of the sensors present in
your computer that you want to monitor. This module is capable to identify the type
of the group by searching the substrings temp, cpu, bat, pwr, fan, pct and byt, so
it will put automatically the vertical label in the graph accordingly (Celsius or
Fahrenheit, Hz, Charge, Watts, RPM, Percent (%) and bytes respectively). Of course,
it cannot supports mixed sensors in a same group. For example, if you need to
monitor more than 9 temperature sensors just create a new group in list.

An example would be:

<list>
0 = temp0, temp1
1 = cpu0, cpu1, cpu2, cpu3
2 = bat0
</list>
title
In this option you must associate a title with the group number specified in list.
This is the title that will appear as the name of the graph. Following the settings
in the example above:

<title>
0 = Temperatures
1 = CPU frequency
2 = Battery status
</title>
desc
In this option you must associate the complete pathname of the file from where to
get the value of each entry defined in the list option. Following the settings in
the example above:

<desc>
temp0 = /sys/devices/virtual/thermal/thermal_zone0/temp
temp1 = /sys/devices/virtual/thermal/thermal_zone1/temp
cpu0 = /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq
cpu1 = /sys/devices/system/cpu/cpu1/cpufreq/scaling_cur_freq
cpu2 = /sys/devices/system/cpu/cpu2/cpufreq/scaling_cur_freq
cpu3 = /sys/devices/system/cpu/cpu3/cpufreq/scaling_cur_freq
bat0 = /sys/class/power_supply/BAT0/capacity
</desc>
unit
With this option you can define the order of magnitude associated to a specific
value. The value collected will be divided by the value defined here. For instance,
the temperature sensors tend to give the value in 1000ths of degrees Celsius,
something like 28300, which will need to be divided by 1000 to get the real
temperature of 28.3. In the case of CPU frequencies the values come in Mhz which
means that they need to be converted to Hz by dividing them by 0.001. Since the
battery value represents a percentage, it doesn't need any special calculation.
Therefore you can define something like this:

<unit>
temp0 = 1000
temp1 = 1000
cpu0 = 0.001
cpu1 = 0.001
cpu2 = 0.001
cpu3 = 0.001
bat0 = 1
</unit>
map
With this option you can optionally rename any of the sensor names defined in the
list option. Following the above example:

<map>
temp0 = Temperature Zone 0
temp1 = Temperature Zone 1
cpu0 = CPU0 frequency
cpu1 = CPU1 frequency
cpu2 = CPU2 frequency
cpu3 = CPU3 frequency
bat0 = Battery 0
</map>

All names are limited to 20 characters.

alerts
This optional list enables the alert capabilities for this graph and complements
with the list option. Each alert has four fields separated by comma: the time
interval, the threshold, the path to the script to be executed and when the alert
must be triggered. the last field is optional.

The time interval is the period of time (in seconds) that the threshold needs to be
exceeded before the external script is executed.

The threshold is the value (temperature, Hz or battery charge) that needs to be
reached or exceeded within the specified time in time interval to execute the
external script. It can be specified as a unique value or as a range of two values
separated by a dash.

The script is the full path name of the script that will be executed by this alert.

The when value specifies when the alert must be triggered (above or below) the
threshold, being above the default value when it's not specified. This forth
parameter is only relevant when the threshold value is not a range.

Each defined sensor has its own alert.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

The following is an example of an alert defined for the first temperature sensor:

<alerts>
temp0 = 3600, 40, /path/to/script.sh, above
temp1 = 3600, 10, /path/to/script.sh, below
temp2 = 3600, 40-60, /path/to/script.sh
</alerts>

The first alert means that if the value of the sensor temp0 exceeds above 40 during
at least one hour (3600 seconds) the script in /path/to/script.sh will be executed.

The second alert means that if the value of the sensor temp1 exceeds below 10
during at least one hour (3600 seconds) the script in /path/to/script.sh will be
executed.

The third alert means that if the value of the sensor temp2 exceeds either below 40
or above of 60 during at least one hour (3600 seconds) the script in
/path/to/script.sh will be executed.

The external script will receive the following arguments:

1st - the value defined as time interval.
2nd - the value defined as threshold.
3rd - the value of the sensor.
4th - the direction or when that alert was triggered by (above or below).

IPMI sensor statistics (ipmi.pm)
This graph is able to monitor an unlimited number of IPMI sensors (temperatures, fans and
voltages).

list
This is a comma-separated list that describes the groups of sensors in desc. Put
one description for each group. For every group specified you need to specify its
sensors in the desc option.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the ipmi.rrd file accordingly, removing all historical data.

An example would be:

list = Temperatures, Fans, Voltages

desc
This is a list of sensors per group defined.

<desc>
0 = CPU Temp, System Temp
1 = FAN 1
2 = Vcore, 3.3VCC, 12V, VDIMM, 5VCC, CPU VTT, VBAT, VSB, AVCC
</desc>

The maximum number of sensors allowed for each group is 9.

units
This is the type of sensor in each group. It's important to not mix different type
of sensors in a same group. This value is informative only, it's mostly used as a
title for the y-axis in the graphs and should match with the output of the ipmitool
command.

map
This list complements the desc option. It basically allows you to change the name
that will appear in the graph, hiding the real name of the sensor. If no
association is defined, then Monitorix will display the name specified in the desc
option. Note, this only works in names that don't include whitespaces unless you
use the whitespace_key_support option and replace whitespaces with underscores in
the key.

alerts
This optional list enables the alert capabilities for this graph and complements
with the desc option. Each alert has three fields separated by comma: the time
interval, the threshold and the path to the script to be executed.

The time interval is the period of time (in seconds) that the threshold needs to be
exceeded before the external script is executed.

The threshold is the temperature that needs to be reached or exceeded within the
specified time in time interval to execute the external script.

The script is the full path name of the script that will be executed by this alert.

Each defined sensor has its own alert.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

The following is an example of an alert defined for the first temperature sensor:

<alerts>
CPU_Temp = 3600, 40, /path/to/script.sh
</alerts>

Notice that the spaces in the sensor's name must be converted to
underscores, since a variable can hold spaces in its name.

Such alert means that if the value of the sensor CPU_Temp reaches or exceeds 40
during at least one hour (3600 seconds) the script in /path/to/script.sh will be
executed.

The external script will receive the following arguments:

1st - the value defined as time interval.
2nd - the value defined as threshold.
3rd - the value of the sensor.

whitespace_key_support
This list complements the map option. It changes the handling of the key names.
Without this option enabled you can't rename keys with whitespaces using the map
option. When enabled, whitespaces in the map key will be replaced by underscores(_)
and enables you to specify the key names this way.

Default value: n
graphs_per_row
This is the number of graphs that will be put in a row.

Default value: 2
use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n
gap_on_all_nan
This option, when enabled via y, combined with the show_gaps option shows gaps only
if all data points are nan instead of requiring only one to be nan for a gap. This
can be useful if not all sensor data are required for normal operation.

Default value: n
extra_args
This option includes any extra argument to the ipmitool command executed by
Monitorix, which is "ipmitool <extra_args> sdr". This is specially useful if you
need to monitor a remote server. An example would be:

extra_args = -H <remote_ip> -U root -P <password>

Default value: none

Ambient sensor statistics (ambsens.pm)
This graph is able to monitor an unlimited number of ambient sensors (temperatures,
humidity, barometer, etc.).

list
This is a comma-separated list that describes the type of sensors in desc. Put one
description for each type. For every type specified you need to specify its sensors
in the desc option. Each one most be referenced as a numeric value starting from
zero in the desc option. There you will define all the sensors than come with that
type of sensor.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the ambsens.rrd file accordingly, removing all historical data.

An example would be:

list = Ambient temperature, Humidity

desc
This is a list of sensors per type defined. The name is irrelevant.

The maximum number of sensors allowed for each type is 9.

units
This is the class of sensor for each type. It's important to not mix different type
of sensors in a same group. This value is informative only, it's mostly used as a
title for the y-axis in the graphs.

cmd
This list complements the desc option. It basically allows you to associate a
script or program (which may include arguments) that will be executed to retrieve
the value for each sensor.

The time interval is the period of time (in seconds) that the threshold needs to be
exceeded before the external script is executed.

The threshold is the value (temperature, etc.) that needs to be reached or exceeded
within the specified time in time interval to execute the external script. It can
be specified as a unique value or as a range of two values separated by a dash.

The script is the full path name of the script that will be executed by this alert.

Each defined sensor has its own alert.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

The following is an example of an alert defined for the first temperature sensor:

<alerts>
temp0 = 3600, 40, /path/to/script.sh, above
temp1 = 3600, 10, /path/to/script.sh, below
temp2 = 3600, 40-60, /path/to/script.sh
</alerts>

The first alert means that if the value of the sensor temp0 exceeds above 40 during
at least one hour (3600 seconds) the script in /path/to/script.sh will be executed.

The second alert means that if the value of the sensor temp1 exceeds below 10
during at least one hour (3600 seconds) the script in /path/to/script.sh will be
executed.

The third alert means that if the value of the sensor temp2 either exceeds below 40
or above of 60 during at least one hour (3600 seconds) the script in
/path/to/script.sh will be executed.

The external script will receive the following arguments:

1st - the value defined as time interval.
2nd - the value defined as threshold.
3rd - the value of the sensor.
4th - the direction or when that alert was triggered by (above or below).

graphs_per_row
This is the number of graphs that will be put in a row.

Default value: 2
scientific_notation
This is an option to enable scientific notation for the current value in the
legend.

Default value: n
show_average
This is an option to show also average, minimum and maximum values in the legend

Default value: n

AMD GPU temperatures and usage (amdgpu.pm)
This graph is able to monitor an unlimited number of AMD GPUs as long as the driver
provides a hwmon interface. Usually it is not guaranteed to always get the same hwmon path
so it is advised to assign fixed links via udev rules.

list
This is a list of groups of GPUs that you want to monitor. Each group will become a
graph and there may be an unlimited number of groups. You can define device names
like amd-w6800.

WARNING: Every time the number of groups in this option changes, Monitorix will
resize the amdgpu.rrd file accordingly, removing all historical data.

To collect the GPU temperatures and usage data the hwmon subsystem is used.

It is recommended that you first check if the hwmon subsystem is able to provide
data from the GPU(s) that you plan to monitor. For example check
/sys/class/hwmon/hwmon1 for available sensors.

You can add it to the group 0 like this:

The maximum number of GPUs allowed per group is 8.

sensors
This list specifies the sensor locations in absolute paths. If a certain card does
not have a specific sensor you leave the entry empty instead (/path/sensor_file1, ,
/path/sensor_file2). The order has to be: GPU busy percent, memory busy percent,
GPU clock, memory clock, memory used, power consumption, power limit, fan pwm
value, GPU temperature, junction temperature, memory temperature. Power consumption
and limit will be shown in one plot.

<sensors>
amd-rx6900 = /dev/amd-rx6900/device/gpu_busy_percent, /dev/amd-
rx6900/device/mem_busy_percent, /dev/amd-rx6900/freq1_input, /dev/amd-
rx6900/freq2_input, /dev/amd-rx6900/device/mem_info_vram_used, /dev/amd-
rx6900/power1_average, /dev/amd-rx6900/power1_cap, /dev/amd-rx6900/pwm1,
/dev/amd-rx6900/temp1_input, /dev/amd-rx6900/temp2_input, /dev/amd-
rx6900/temp3_input
amd-wx5100 = /dev/amd-wx5100/device/gpu_busy_percent, /dev/amd-
wx5100/device/mem_busy_percent, /dev/amd-wx5100/freq1_input, /dev/amd-
wx5100/freq2_input, /dev/amd-wx5100/device/mem_info_vram_used, /dev/amd-
wx5100/power1_average, /dev/amd-wx5100/power1_cap, /dev/amd-wx5100/pwm1,
/dev/amd-wx5100/temp1_input, ,
</sensors>

map
This list complements the list option. It basically allows you to change the GPU
name that will appear in the graph, hiding the real device name. If no association
is defined, then Monitorix will display the name of the GPU device as it is.

desc
This list complements the list option. It basically allows you to include a title
for every group of GPUs. The title will appear in the title of the graph.

<desc>
0 = Host
1 = Virtual
</desc>

coretemp_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the core temperature. It works as follows:

If the core temperature of any of the specified GPU device names reaches or
subceeds the coretemp_threshold (the interval of time is not used here), Monitorix
will execute the external alert script defined in coretemp_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

coretemp_timeintvl
Not used in this alert.

Default value: 0

coretemp_threshold
This is the value that needs to be reached or subceeded to trigger the mechanism
for a particular action, which in this case is the execution of an external alert
script.

Default value: 10

coretemp_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in coretemp_timeintvl.
2nd - the value currently defined in coretemp_threshold.
3rd - the current core temperature.

Default value: /path/to/script.sh

memorytemp_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the memory temperature. It works as follows:

If the memory temperature of any of the specified GPU names reaches or exceeds the
memorytemp_threshold (the interval of time is not used here), Monitorix will
execute the external alert script defined in memorytemp_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

memorytemp_timeintvl
Not used in this alert.

Default value: 0

memorytemp_threshold
This is the value that needs to be reached or exceeded to trigger the mechanism for
a particular action, which in this case is the execution of an external alert
script.

Default value: 90

memorytemp_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in memorytemp_timeintvl.
2nd - the value currently defined in memorytemp_threshold.
3rd - the current memory temperature.

Default value: /path/to/script.sh

accept_invalid_amdgpu
During the init stage this graph verifies that every defined device name does exist
in the system. If not, then the graph disables itself.

This option changes this behaviour and permits one to continue working even if the
device names defined doesn't exist. Keep in mind that you will continue seeing
error messages in the logfile.

Default value: n

show_current_values

Print current values in the legend of the small righthand plots.

Default value: n

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

respect_power_state
This option, when enabled via y, will respect the AMD GPU D3 power state. Monitorix
won't wake up a GPU in D3 power state to check the sensors values but skip it. The
power state sensor has to be specified via the ower_states option for each GPU that
should be respected.

Default value: n

power_states
This list complements the respect_power_state option. You can specify the
power_state sensor for each GPU that should not be woken up if in D3.

<power_states>
amd-w6800 = /dev/hwmon-w6800/device/power_state
amd-rx6900 = /dev/hwmon-rx6900/device/power_state
</power_states>

NVIDIA GPU temperatures and usage (nvidiagpu.pm)
This graph is able to monitor an unlimited number of Nvidia GPUs via nvidia-smi.

list
This is a list of groups of GPUs that you want to monitor. Each group will become a
graph and there may be an unlimited number of groups.

WARNING: Every time the number of groups in this option changes, Monitorix will
resize the nvidiagpu.rrd file accordingly, removing all historical data.

As identifier you can either use the GPU ID or the GPU UUID found via nvidia-smi
--list-gpus. You can add it to the group 0 like this:

The maximum number of GPUs allowed per group is 8.

desc
This list complements the list option. It basically allows you to include a title
for every group of GPUs. The title will appear in the title of the graph.

<desc>
0 = Host
1 = Virtual
</desc>

coretemp_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the core temperature. It works as follows:

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

coretemp_timeintvl
Not used in this alert.

Default value: 0

coretemp_threshold
This is the value that needs to be reached or subceeded to trigger the mechanism
for a particular action, which in this case is the execution of an external alert
script.

Default value: 10

coretemp_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in coretemp_timeintvl.
2nd - the value currently defined in coretemp_threshold.
3rd - the current core temperature.

Default value: /path/to/script.sh

memorytemp_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the memory temperature. It works as follows:

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

memorytemp_timeintvl
Not used in this alert.

Default value: 0

memorytemp_threshold
This is the value that needs to be reached or exceeded to trigger the mechanism for
a particular action, which in this case is the execution of an external alert
script.

Default value: 90

memorytemp_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in memorytemp_timeintvl.
2nd - the value currently defined in memorytemp_threshold.
3rd - the current memory temperature.

Default value: /path/to/script.sh

show_current_values

Print current values in the legend of the small righthand plots.

Default value: n

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

NVIDIA temperatures and usage (nvidia.pm)
This graph requires to have installed the official NVIDIA drivers.

max
This is the number of NVIDIA cards currently plugged in your system.

The maximum allowed is 9.

Default value: 1

Disk drive temperatures and health (disk.pm)
This graph is able to monitor an unlimited number of disk drives.

list
This is a list of groups of disk drives that you want to monitor. Each group will
become a graph and there may be an unlimited number of groups. You can define
device names or paths to devices like /dev/disk/by-
path/pci-0000:00:11.0-scsi-0:0:0:0.

WARNING: Every time the number of groups in this option changes, Monitorix will
resize the disk.rrd file accordingly, removing all historical data.

To collect the disk drive temperatures and health the smartmontools or the hddtemp
command are required. Depending on the disk model reading smart values will wake up
the disk and reset the sleep timer. To avoid waking them up set respect_standby = y
but they still won't got to sleep automatically.

It is recommended that you first check if either smartctl(8) or hddtemp are able to
collect data from the disk drive(s) that you plan to monitor. You may test this
with the following command:

# hddtemp /dev/sda
/dev/sda: WDC WD1600AABS-00M1A0: 48°C

If you see good results as above, you can add it to the group 0 like this:

The maximum number of disk device names allowed per group is 8.

map
This list complements the list option. It basically allows you to change the disk
name that will appear in the graph, hiding the real device name. If no association
is defined, then Monitorix will display the name of the disk as it is.

<map>
/dev/sda = "system disk"
pci-0000:00:11.0-scsi-0:0:0:0 = "data disk"
</map>

desc
This list complements the list option. It basically allows you to include a title
for every group of disk drives. The title will appear in the bottom of the graph.

<desc>
0 = Local disks
1 = Remote disks
</desc>

realloc_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the number of reallocated sectors in disk. It works as follows:

If the number of reallocated sectors in any of the specified disk device names
reaches the realloc_threshold (the interval of time is not used here), Monitorix
will execute the external alert script defined in realloc_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

realloc_timeintvl
Not used in this alert.

Default value: 0

realloc_threshold
This is the value that needs to be reached or exceeded to trigger the mechanism for
a particular action, which in this case is the execution of an external alert
script.

Default value: 1

realloc_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in realloc_timeintvl.
2nd - the value currently defined in realloc_threshold.
3rd - the current number of reallocated sectors.

Default value: /path/to/script.sh

pendsect_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the number of current pending sectors (or bad sectors) in disk. It works
as follows:

If the number of current pending sectors in any of the specified disk device names
reaches the pendsect_threshold (the interval of time is not used here), Monitorix
will execute the external alert script defined in pendsect_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

pendsect_timeintvl
Not used in this alert.

Default value: 0

pendsect_threshold
This is the value that needs to be reached or exceeded to trigger the mechanism for
a particular action, which in this case is the execution of an external alert
script.

Default value: 1

pendsect_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in pendsect_timeintvl.
2nd - the value currently defined in pendsect_threshold.
3rd - the current number of pending sectors.

Default value: /path/to/script.sh

accept_invalid_disk
During the init stage this graph verifies that every defined device name does exist
in the system. If not, then the graph disables itself.

This option changes this behavior and permits one to continue working even if the
device names defined doesn't exist. Keep in mind that you will continue seeing
error messages in the logfile.

Default value: n

respect_standby
This option, when enabled via y, won't wake up disks if they are already in standby
but also won't report new smart during standby.

Default value: n

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

NVME drive temperatures and health (nvme.pm)
This graph is able to monitor an unlimited number of nvme drives.

list
This is a list of groups of nvme drives that you want to monitor. Each group will
become a graph and there may be an unlimited number of groups. You can define
device names or paths to devices like /dev/nvme0.

WARNING: Every time the number of groups in this option changes, Monitorix will
resize the nvme.rrd file accordingly, removing all historical data.

To collect the nvme drive temperatures and health the smartmontools command are
required.

It is recommended that you first check if smartctl(8) is able to collect data from
the nvme drive(s) that you plan to monitor. You may test this with the following
command:

# smartctl -A /dev/nvme0
=== START OF SMART DATA SECTION ===
SMART/Health Information (NVMe Log 0x02)
Critical Warning: 0x00
Temperature: 32 Celsius
Available Spare: 100%
Available Spare Threshold: 10%
Percentage Used: 0%
Data Units Read: 15,134,801 [7.74 TB]
Data Units Written: 11,639,110 [5.95 TB]
Host Read Commands: 108,213,874
Host Write Commands: 84,023,019
Controller Busy Time: 819
Power Cycles: 94
Power On Hours: 701
Unsafe Shutdowns: 15
Media and Data Integrity Errors: 0
Error Information Log Entries: 0
Warning Comp. Temperature Time: 0
Critical Comp. Temperature Time: 0
Temperature Sensor 1: 32 Celsius
Temperature Sensor 2: 35 Celsius

If you see good results as above, you can add it to the group 0 like this:

The maximum number of nvme device names allowed per group is 8.

map
This list complements the list option. It basically allows you to change the nvme
drive name that will appear in the graph, hiding the real device name. If no
association is defined, then Monitorix will display the name of the nvme drive as
it is.

<map>
/dev/nvme = "system disk"
pci-0000:00:11.0-scsi-0:0:0:0 = "data disk"
</map>

desc
This list complements the list option. It basically allows you to include a title
for every group of nvme drives. The title will appear in the bottom of the graph.

<desc>
0 = Individual drives
1 = RAID
</desc>

availspare_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the normalized percentage (0 to 100%) of the remaining spare capacity
available. It works as follows:

If the percentage of available spare space in any of the specified nvme device
names reaches or subceeds the availspare_threshold (the interval of time is not
used here), Monitorix will execute the external alert script defined in
availspare_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

availspare_timeintvl
Not used in this alert.

Default value: 0

availspare_threshold
This is the value that needs to be reached or subceeded to trigger the mechanism
for a particular action, which in this case is the execution of an external alert
script.

Default value: 10

availspare_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in availspare_timeintvl.
2nd - the value currently defined in availspare_threshold.
3rd - the current percentage number of available spare space.

Default value: /path/to/script.sh

percentused_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the the percentage of NVM subsystem life used based on the actual usage
and the manufacturer's prediction of NVM life. It works as follows:

If the life percentage used in any of the specified nvme device names reaches or
exceeds the percentused_threshold (the interval of time is not used here),
Monitorix will execute the external alert script defined in percentused_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

percentused_timeintvl
Not used in this alert.

Default value: 0

percentused_threshold
This is the value that needs to be reached or exceeded to trigger the mechanism for
a particular action, which in this case is the execution of an external alert
script.

Default value: 90

percentused_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in percentused_timeintvl.
2nd - the value currently defined in percentused_threshold.
3rd - the current number of life percentage used.

Default value: /path/to/script.sh

accept_invalid_nvme
During the init stage this graph verifies that every defined device name does exist
in the system. If not, then the graph disables itself.

This option changes this behavior and permits one to continue working even if the
device names defined doesn't exist. Keep in mind that you will continue seeing
error messages in the logfile.

Default value: n

show_extended_plots

Show additional plots for mean read and written bytes per second, total bytes read
and written, media errors and unsafe shutdowns

Default value: y

show_current_values

Print current values in the legend of the small righthand plots.

Default value: n

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

Filesystem usage and I/O activity (fs.pm)
This graph is able to monitor an unlimited number of filesystems.

list
This is a list of groups of mounted filesystems that you want to monitor. Each
group will become a graph and there may be an unlimited number of groups.

WARNING: Every time the number of groups in this option changes, Monitorix will
resize the fs.rrd file accordingly, removing all historical data.

Take special care to use the same name as appears in the output of the df(1)
command (the swap device is a special case). An example would be:

<list>
0 = /, swap, boot, home, /mnt/backup
</list>

The maximum number of filesystems allowed per group is 8.

desc
This list complements the list option. It basically allows you to change the name
that will appear in the graph, hiding the real name of the mount point. If no
association is defined, then Monitorix will display the name specified in the list
option.

<desc>
/ = Root FS
/home = My Home
/mnt/backup = Backups
</desc>

You can define as much entries as you want.

devmap
This optional list complements the list option. When Monitorix is started, and in
order to be able to show I/O activity, it attempts to detect the mapping of devices
specified in list, as defined in the df command output column "Mounted on". In the
event that devices are not detected by Monitorix, the devmap option shall be used
to manually define them, according to the underlying OS:

Linux (kernel > 2.4)
<devmap> device must match a device listed in the "/proc/diskstats"
file.

Linux (kernel <= 2.4)
<devmap> is not used, but because something is defined in <devmap>,
Monitorix will extract "disk_io" lines from the "/proc/stat" file.

FreeBSD
<devmap> device recognized by the output of "iostat -xI <dev>"
command.

OpenBSD and NetBSD
<devmap> is not used, but because something is defined in <devmap>,
Monitorix will use the output of "iostat -DI" command.

Just an example:
<devmap>
/mnt/home = dm-1
/mnt/backup = cciss/c0d2p6
</devmap>

You can define as much entries as you want.

The time interval is the period of time (in seconds) that the threshold needs to be
exceeded before the external script is executed.

The threshold is the percentage of disk space used in the file system that needs to
be reached or exceeded within the specified time in time interval to execute the
external script.

The script is the full path name of the script that will be executed by this alert.

Each defined filesystem has its own alert.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

The following is an example of an alert defined for the root filesystem:

<alerts>
/ = 3600, 98, /path/to/script.sh
</alerts>

Such alert means that if the percentage of disk space used in the root filesystem
reaches or exceeds 98 (more than 98) during at least one hour (3600 seconds) the
script in /path/to/script.sh will be executed.

The external script will receive the following arguments:

1st - the value defined as time interval.
2nd - the value defined as threshold.
3rd - the filesystem disk usage.

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

has_removable_devices
This option, when enabled via y, solves the problem with those hotpluggable devices
that were offline when Monitorix was started, and later when they went online
Monitorix don't know their device names and do not appear in the I/O statistics
graphs, unless you restart Monitorix. So, when this option is enabled Monitorix
will re-check the devices on every update.

Default value: n

ZFS statistics (zfs.pm)
This graph is able to monitor an unlimited number of pools.

max_pools
This is the maximum number of pools that you can define in list. There is no limit
to the number of pools monitored, but keep in mind that every time this number
changes, Monitorix will resize the zfs.rrd file accordingly, removing all
historical data.

Default value: 5

list
This is a comma-separated list of pool names. The number of pool names defined here
can't be greater than the number defined in max_pools.

Directory usage statistics (du.pm)
This graph is able to monitor the usage of an unlimited number of directories.

IMPORTANT NOTE: The du command makes intensive disk I/O access that might slow down the
whole system. Moreover, continued executions of this command will affect the buffer cache
mechanism and this will also increase the system response time. To reduce executions
refresh_interval can be specified in seconds (Use 0 for default refresh interval).

list
This is a comma-separated list that describes the groups of directories in desc.
Put one description for each group. For every group specified you need to specify
its directories in the desc option.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the du.rrd file accordingly, removing all historical data.

An example would be:

list = System, Users

desc
This is a list of directories per group defined.

<desc>
0 = /var/spool/mail, /var/spool/mqueue, /etc, /var/ftp, /tmp
1 = /home/ace, /home/gene, /home/paul, /home/peter
</desc>

The maximum number of directories allowed for each group is 9.

type
This specifies the information that will be presented for each directory specified
in each list. It accepts two possible values:

size for the directory size (which is the default option).
files for the number of files inside the directory.

An example would be:

<type>
0 = size
1 = files
</type>

dirmap
This list complements the desc option. It basically allows you to change the name
that will appear in the graph, hiding the real name of the directory. If no
association is defined, then Monitorix will display the name specified in the desc
option.

graphs_per_row
This is the number of graphs that will be put in a row.

Default value: 2

extra_args
This option includes any extra argument to the du command executed by Monitorix,
which is "du -ks". This is specially useful if you want to skip directories on
different file systems, in this case just define this option like this:

extra_args = "-x"

IMPORTANT NOTICE: Keep in mind that including certain flags like '-h' (which gives
results in human readable format) could make Monitorix unable to interpret the
results.

refresh_interval
Refresh interval in seconds. This is an option to reduce the execution of the du
command and undesired side effects caused by this. Default value 0 means normal
refresh with all other plots. Besides the default meaningful values are from 60 to
86400. Keep in mind that changing the refresh_interval is possible without loosing
history but changing the interval to a smaller one will introduce gaps in the data
at the transition point.

Default value: 0

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

Network traffic and usage (net.pm)
max
This is the maximum number of network interfaces that you can define in list. There
is no limit, but keep in mind that every time this number changes, Monitorix will
resize the net.rrd file accordingly, removing all historical data.

Default value: 10

list
This is a comma-separated list of network interfaces that you may want to monitor.
An example would be:

list = eth0, eth1

desc
This is the option where each network interface specified in list is described.
Each definition consists of three parameters separated by comma: the description of
the interface and the rigid and limit values.

Put one description for each interface listed. An example would be:

<desc>
eth0 = FastEthernet LAN, 0, 1000
eth1 = ADSL 10Mbs Internet, 0, 1000
</desc>

gateway
This is where the network interface that acts as the gateway for this server is
defined. This is mainly used if you plan to monitor network traffic usage of your
devices/networks using the traffacct graph below.

Netstat statistics (netstat.pm)
This graph shows the state of the all IPv4 and IPv6 network connections.

Only the command to be used can be set here, besides the limit and rigid values.

cmd
This is the command that will be used to gather statistics. There are two possible
values:

ss
netstat

Default value: ss

Tinyproxy statistics (tinyproxy.pm)
This graph is able to monitor an unlimited number of Tinyproxy installations.

list
This is a comma-separated list of URLs of Tinyproxys.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the tinyproxy.rrd file accordingly, removing all historical data.

Default value: http://your.proxy.com/

desc
This list complements the list option, it defines the URL from where Monitorix must
gather the statistics for each Tinyproxy defined.

An example of this option would be:

<desc>
http://your.proxy.com = http://tinyproxy.stats
</desc>

show_url
If set to y Monitorix will show the original URL of each Tinyproxy at the bottom of
the graph. For security reasons you may want to hide this information.

Default value: y

Traffic Control statistics (tc.pm)
This graph is able to monitor an unlimited number of network interfaces managed by the tc
command.

list
This is a comma-separated list of network interfaces that you may want to monitor.
An example would be:

list = eth0, eth1

desc
This is the option where you define the queue disciplines you want to monitor for
each network interface specified in list.

An example would be:

<desc>
eth0 = cbq 1, sfq 10, sfq 20, sfq 30, ingress ffff
eth1 = htb 1, pfifo 20, pfifo 21, pfifo 22
</desc>

The maximum number of qdiscs allowed is 9.

map
This option complements the desc option. It basically allows you to change the name
of the qdiscs that will appear in the graphs. If no association is defined, then
Monitorix will show the name as specified in the desc option.

Since the qdisc names have the space character in their names, they can't be used
as the key in the association, instead you must the use their position number
(starting by 0) in the desc option.

An example would be:

<map>
<eth0>
0 = Class Based Queueing
1 = Stochastic Fairness Queueing 10
</eth0>
<eth1>
0 = Hierarchical Token Bucket
</eth1>
</map>

Libvirt statistics (libvirt.pm)
This graph is able to monitor an unlimited number of virtual machines managed by Libvirt.

cmd
This is the command that will be used to gather statistics from each virtual
machine listed in list.

Default value: virsh

An example would be:

cmd = virsh -r -c qemu:///session

list
This is a list of groups of virtual machines that you want to monitor. Each group
will become a graph and there may be an unlimited number of groups.

WARNING: Every time the number of groups in this option changes, Monitorix will
resize the libvirt.rrd file accordingly, removing all historical data.

An example would be:

<list>
0 = centos6, winxp
</list>

The maximum number of virtual machines allowed per group is 8.

desc
This list complements the list option and is mandatory for every virtual machine
listed. You must define the virtual block device and the MAC address of the virtual
network device that you want to monitor for every virtual machine. Just like this:

<desc>
centos6 = CentOS 6, vda, 52:54:00:45:d0:e7
winxp = MS Windows XP, hda, 52:54:00:97:1c:e5
</desc>

You might also define this list using sections for each virtual machine, this way
you'll be able to define multiple disks and multiple network interfaces for each
virtual machine. Just like this:

<desc>
<centos6>
desc = "CentOS 6"
disk = vda, vdb, vdc
net = 52:54:00:45:d0:e7, 52:54:00:45:d0:e8
</centos6>
</desc>

To obtain all these values you might want to use the following commands:

# virsh domblklist centos6
Target Source
------------------------------------------------
vda /home/jordi/kvm/centos6.img
hdc -

# virsh domiflist centos6
Interface Type Source Model MAC
-------------------------------------------------------
vnet3 network default virtio 52:54:00:45:d0:e7

This option also allows you to change the name that will appear in the graph,
hiding the real name of the virtual machine. If no association is defined, then
Monitorix will display the name specified in the list option.

Process statistics (process.pm)
This graph is able to monitor an unlimited number of processes. This graph requires a
Linux kernel version 2.6.20 at least to support process I/O accounting. Some systems with
older kernels might also have been ported it though.

list
This is a list of groups of processes that you want to monitor. Each group will
become a graph and there may be an unlimited number of groups.

WARNING: Every time the number of groups in this option changes, Monitorix will
resize the process.rrd file accordingly, removing all historical data.

Monitorix uses the following command to find the processes listed in this option:

# ps -eo pid,comm,command

Therefore names in the process list can be either exactly to the process name as it
appears in the comm columns, or just a substring of the process name that appears
in the command column.

An example of this option would be:

<list>
0 = httpd, sshd, ntpd, mysqld, proftpd, clamd, imap, sendmail, named,
bash
</list>

The maximum number of processes allowed per group is 10.

desc
This list complements the list option. It basically allows you to change the name
that will appear in the graph, hiding the real name of the process. If no
association is defined, then Monitorix will display the name specified in the list
option.

<desc>
httpd = Apache
imap = Dovecot
named = Bind
</desc>

You can define as much entries as you want.

time_unit
This is the unit in which will appear the values in the uptime graph. Possible
values are: minute, hour or day. It will default to day even if none is specified.

System services demand (serv.pm)
This graph is able to monitor an unlimited number of system services or any application
that has a log file.

list
This is a list of groups of services that you plan to monitor. Each group will
become a graph and there may be an unlimited number of groups.

WARNING: Every time the number of groups in this option changes, Monitorix will
resize the serv.rrd file accordingly, removing all historical data.

An example of this option would be:

<list>
Default = SSH, FTP, TELNET, IMAP, Samba, Fax, CUPS, POP3, SMTP, Spam,
Virus, Fail2ban
</list>

The maximum number of services allowed per group is 16.

desc
This list complements the list option. It basically allows you to define how
Monitorix will monitor such service.

You must use the same name of service that you defined in list followed by an equal
sign and a number of values. The first value indicates if this will be a C
(counter) or a G (gauge). Counters are perfect for values that accumulate on every
sample (match lines in logfiles), Gauges are for values that can change on every
new sample (disk usage, Samba users, etc). The second value indicates the logfile
from where Monitorix will extract the information. It must be prefixed with file:
to indicate that it's a file. If you need to use the output of a program instead,
then you can prefix it with exec: and Monitorix will run this script and will use
its output as if it was the logfile.

The third value is the first regular expression that Monitorix will use to match
lines. It's normally used as the date that appears in the log file.

The forth and last value is a group of regular expressions separated by a plus
sign. You can prefix a regular expression with i: in order to note that it must be
insensitive case.

You can create multiple definitions of the same service with different values, so
you are able to combine similar services into one single metric.

<desc>
SSH = C, file:/var/log/secure, "^%b %e", "sshd\[.*\]: Accepted "
Spam = C, file:/var/log/maillog, "^%b %e", "MailScanner.*Spam
Checks:.*Found.*spam messages" + "amavis\[.* SPAM"
Spam = C, file:/var/log/sa-update.log, "^%b %e", "spamd: identified
spam"
SMTP = C, file:/var/log/maillog, "^%b %e", i:"to=.*stat(us)?=sent"
IMAP = C, file:/var/log/uwimap, "%b %d", " imapd\[.* Login user="
IMAP = C, file:/var/log/dovecot, "%b %d", " imap-login: .* Login: "
Samba = G, exec:/usr/local/bin/samba.sh, "", ""
POP3 = C, file:/var/log/uwimap, "%b %d", " ipop3d\[.* Login user="
POP3 = C, file:/var/log/dovecot, "%b %d", " pop3-login: .* Login: "
</desc>

You can define as much entries as you want.

mode
This option toggles the way the System Services Demand data is represented in the
graph. There are two possible values:

i for incremental style.
l for load (peaks) style.

Default value: i

graphs_per_row
This is the number of graphs that will be put in a row.

Default value: 2

Mail statistics (mail.pm)
This graph requires either MailScanner or amavisd-new mail scanners in order to account
spam and virus emails. Spamassassin and Clamav antivirus are also used for spam and virus
email accounting.

mta
This option specifies the MTA that Monitorix will use to collect mail statistics.
The currently supported MTAs are:
Sendmail
Postfix
Exim

NOTE: the pflogsumm utility is required when using the Postfix MTA.

Default value: sendmail

greylist
This option specifies the Greylisting implementation that Monitorix will use to
collect statistical information.

The currently supported Greylisting software is:
milter-greylist
postgrey

In the case of milter-greylist, Monitorix shows the same data that appears at the
end of the file greylist.db.

In the case of Postgrey, Monitorix reads the mail_log file and searches for a
specific type of lines. Lines of type "action=greylist, reason=new" appear as
Greylisted in the graph. Lines of type "action=greylist, reason=early-retry" appear
as Delayed in the graph. Lines of type "action=pass, reason=triplet found" appear
as Passed in the graph. And finally, lines of type "action=pass, reason=client
whitelist" appear as Whitelisted in the graph.

Default value: milter-greylist

stats_rate
This option only affects the Mail Statistics and the Greylisting graphs, and it
specifies the rate in which the values are saved and shown. This option has two
possible values:
real
per_second

If it's set to its default value (real), it will show the messages as in a 'per
minute' rate. Since Monitorix collects data on every minute, this should be the
preferred way to see the results.

In the other hand, and in order to keep backwards compatibility, if this option is
missing in the configuration file, it will act as if it was set up as per_second,
which means that the number of messages collected in each minute will be divided by
60.

Default value: real

delvd_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the number of delivered messages. It works as follows:

If the number of delivered messages reaches the delvd_threshold value for the
interval of time defined in delvd_timeintvl, Monitorix will execute the external
alert script defined in delvd_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

delvd_timeintvl
This is the period of time (in seconds) that the threshold needs to be exceeded
before the external alert script is executed.

Default value: 60

delvd_threshold
This is the value that needs to be reached or exceeded within the specified time
period in delvd_timeintvl to trigger the mechanism for a particular action, which
in this case is the execution of an external alert script.

The value of this option is compared against the number of delivered messages since
the last delvd_timeintvl seconds.

Default value: 100

delvd_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in delvd_timeintvl.
2nd - the value currently defined in delvd_threshold.
3rd - the number of delivered messages.

Default value: /path/to/script.sh

mqueued_enabled
This section enables or disables one of the alert capabilities for this graph; the
alert for the number of queued messages. It works as follows:

If the number of queued messages reaches the mqueued_threshold value for the
interval of time defined in mqueued_timeintvl, Monitorix will execute the external
alert script defined in mqueued_script.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

Default value: n

mqueued_timeintvl
This is the period of time (in seconds) that the threshold needs to be exceeded
before the external alert script is executed.

Default value: 3600

mqueued_threshold
This is the value that needs to be reached or exceeded within the specified time
period in mqueued_timeintvl to trigger the mechanism for a particular action, which
in this case is the execution of an external alert script.

The value of this option is compared with the number of messages in the mail queue.

Default value: 100

mqueued_script
This is the full path name of the script that will be executed by this alert.

It will receive the following three parameters:

1st - the value currently defined in mqueued_timeintvl.
2nd - the value currently defined in mqueued_threshold.
3rd - the number of messages in the mail queue.

Default value: /path/to/script.sh

Network port traffic (port.pm)
This graph requires the iptables(8) command and optionally the ip6tables(8) command on
Linux systems and the ipfw command on *BSD systems.

max
This is the number of network ports that you want to monitor. There is no limit to
the number of ports monitored, but keep in mind that every time this number
changes, Monitorix will resize the port.rrd file accordingly, removing all
historical data.

Default value: 9

rule
This is the rule number that Monitorix will use when using the ipfw command to
manage network port activity on *BSD systems. Change it if you think it might
conflict with any other rule number.

Default value: 24000

list
You may define here up to max network port numbers. If you need to monitor the same
network port with TCP and UDP protocols, you can add your own suffix to the port
number (e.g: 443t and 443u) in order to distinguish it from the double definition
in the <desc> block. It also support port ranges (e.g: 49152:65534) to be able to
monitor the traffic of a number of consecutive ports summarized on a unique graph.

If you see a red color in the background of a network port graph, it means that
there is not a daemon listening on that port. This can be useful to know if some
service gone down unexpectedly. Of course, this is only valid on a single port, not
ranged ports.

desc
This is the option where each network port specified in list is described. Each
port definition consists of six parameters separated by comma:
- an small port description.
- the network protocol (tcp or udp).
- the connection type (in, out or in/out).
- the rigid value.
- the limit value.
- the L optional option which specifies that this port should be listening
and Monitorix will advice it, by changing the background color of the graph
to red, if finds it down. This option has no effect on ranged ports.

There is also support (Linux only) for IPv6 network ports activity by using
protocol names as tcp6 or udp6.

An example would be:
list = 25, 25ip6, 80, 53t, 53u, 49152:65534
<desc>
25 = SMTP, tcp, in/out, 0, 1000, L
25ip6 = SMTP, tcp6, in/out, 0, 1000, L
80 = HTTP, tcp, in, 0, 1000, L
53t = DNS, tcp, in, 0, 1000, L
53u = DNS, udp, in, 0, 1000, L
49152:65534 = FTP_PSV, tcp, in, 0, 1000
</desc>

As you can see, you cannot use the same port number twice. Instead, you must
distinguish it with some suffix. Monitorix will automatically extract all the first
numeric digits, and will use that value as the network port number.

graphs_per_row
This is the number of graphs that will be put in a row. Consider the interaction of
this parameter with the max option in order to adjust the size and number of graphs
in relation to your horizontal screen size.

Default value: 3

size
This is the size of the graphs of the ports. It currently accepts up to 8 different
size names: large, main, medium, medium2, small, mini, tiny, zoom and remote. You
can check the resolution of each size in the configuration file, inside the list
named graph_size.

Default value: mini

cmd
This option is used only under Linux systems. It is intended to define the command
(with or without its complete path) that will be used to test if the network port
is down (not listening). Currently there are only two possible values:

ss
netstat

Default value: ss

Users using the system (user.pm)
Only the limit and rigid values can be set here.

FTP statistics (ftp.pm)
This graph supports currently ProFTPD, vsftpd and Pure-FTPd log file formats.

For best results with the ProFTPD server I recommend to add the following line in its
configuration file:

ExtendedLog /var/log/proftpd/access.log AUTH,DIRS,READ,WRITE

For best results with the vsftpd server I recommend to setup the option xferlog_std_format
to NO, and the option ftp_log to /var/log/vsftpd.log.

Pure-FTPd users might want to consider using the system syslog logfile.

server
This option specifies the FTP server. The currently supported FTP servers are:
ProFTPD
vsftpd
Pure-FTPd

Default value: proftpd

anon_user
This option lists the different names (separated by comma) that can adopt the
Anonymous user in the FTP server defined in server.

Default value: anonymous, ftp

Apache statistics (apache.pm)
This graph requires that mod_status be loaded and ExtendedStatus option set to On in order
to collect full status information of the Apache web server.

This graph is able to monitor an unlimited number of local and remote Apache web servers.

list
This is a comma-separated list of URLs of the monitored Apache web servers.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the apache.rrd file accordingly, removing all historical data.

Default value: http://localhost/server-status?auto

The time interval is the period of time (in seconds) that the threshold needs to be
exceeded before the external script is executed.

The threshold is the number of remaining free slots that needs to be reached or
exceeded within the specified time in time interval to execute the external script.

The script is the full path name of the script that will be executed by this alert.

Each defined Apache has its own alert.

The default Monitorix installation includes an example of a shell-script alert
called monitorix-alert.sh which you can use as a base for your own script.

The following is an example of an alert defined for the local Apache:

<alerts>
http://localhost/server-status?auto = 3600, 5, /path/to/script.sh
</alerts>

Such alert means that if the remaining free slots reaches or exceeds 5 (less than
5) during at least one hour (3600 seconds) the script in /path/to/script.sh will be
executed.

The external script will receive the following arguments:

1st - the value defined as time interval.
2nd - the value defined as threshold.
3rd - the remaining free slots.

Nginx statistics (nginx.pm)
This graph may require adding some lines in the configuration file nginx.conf. Please see
the README.nginx file to determine the exact steps needed to configure Nginx to get status
information.

This graph requires the iptables(8) command on Linux systems, and the ipfw command on *BSD
systems.

url
This is the URL to be used to collect Nginx stats.

Default value: http://localhost/nginx_status

port
This is the network port the Nginx web server is listening on. It will be used for
traffic (with iptables), and for nginx_status if url is not specified. If port of
nginx_status is different from port then specify it in the url
(http://host:port/nginx_status)

Default value: 80

rule
This is the rule number that Monitorix will use when using the ipfw command to
manage Nginx network activity on *BSD systems. Change it if you think it might
conflict with any other rule number.

Default value: 24100

cmd
This is the command that will be used to test if the Nginx web server is down (not
listening). There are two possible values:

ss
netstat

Default value: ss

Lighttpd statistics (lighttpd.pm)
This graph requires that mod_status is loaded in order to collect status information from
the Lighttpd web server.

This graph is able to monitor an unlimited number of local and remote Lighttpd web
servers.

list
This is a comma-separated list of URLs of the monitored Lighttpd web servers.

WARNING: Every time the number of entries of this option changes, Monitorix will
resize the lighttpd.rrd file accordingly, removing all historical data.

Default value: http://localhost/server-status?auto

MySQL statistics (mysql.pm)
This graph requires that you create a password protected MySQL user that is NOT granted
privileges on any DB.

Example:

mysql> CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';
mysql> FLUSH PRIVILEGES;

where user is the new user name and password is the password that will be used for that
user.

This graph is able to monitor an unlimited number of local and remote MySQL web servers.

NOTE: It is strongly recommended that you restart the MySQL service in order to avoid high
peaks that could prevent correct display of the first plotted data.

conn_type
This option toggles the way how Monitorix establishes the connection with the MySQL
server. There are two possible values:

host using the network (hostname and IP address).
socket using a socket file.

Default value: host

list
This is a comma-separated list of hostnames or path to sockets of MySQL servers.

WARNING: Every time the number of entries of this option change Monitorix will
resize the mysql.rrd file accordingly, removing all historical data.

Default value: localhost

desc
This is the option where each entry specified in the list is described. Each
definition consists of three parameters separated by comma: the port, the username
and the password.

An example using the host type would be:
<desc>
localhost = 3306, user, secret
</desc>

When using the socket type the network port is, of course, irrelevant but its field
is still mandatory. This means that you must respect the three comma-separated
values.

Some of the values shown in the graphs are the result of a calculation of two
values from either SHOW [GLOBAL] STATUS or SHOW VARIABLES. The following is an
explanation of them:

Thread Cache Hit Rate
(1 - (Threads_created / Connections)) * 100
When an application connects to a MySQL database, the database has to create a
thread to manage the connection and the queries that will be sent in that
connection. The database instructs the kernel to create a new thread, and the
kernel allocates resources and creates the thread, then returns it to the MySQL
service. When the connection is terminated by the application, MySQL tells the
kernel to destroy the thread and free the resources. This create/destroy mechanism
causes considerable overhead if the MySQL server has many new connections per
second.
If MySQL doesn't destroy the thread when the connection is terminated, but reuses
it and assigns it to the next connection then this will decrease the kernel
overhead. This is why a high Thread Cache Hit Rate improves MySQL performance and
decreases the system's CPU usage.
Setting the parameter thread_cache_size in the my.cnf file accordingly will help to
correctly balance between having a great thread cache and keeping MySQL memory
consumption reasonable.
Higher is better.

Query Cache Hit Rate
Qcache_hits / (Qcache_hits + Com_select) * 100
Higher should be considered better.
A query cache size increase is recommended if the query cache usage is very close
to 100% and the query cache hit rate is far from 100%. But sometimes a size
increase will not lead to a better hit rate: this means that the increase was not
needed and that the application do not run enough cacheable SELECT queries.
This value should grow proportionally with the number of executed queries as long
as the query cache is performing well. Please also have a look at the Query cache
usage percentage to know if your query_cache configuration is appropriate.

For more information please refer to
http://www.databasejournal.com/features/mysql/article.php/3808841/Optimizing-the-
MySQL-Query-Cache.htm

Query Cache Usage
(1 - (Qcache_free_memory / query_cache_size)) * 100
This value should be reasonably far from 100%, otherwise consider incrementing the
query_cache_size parameter in my.cnf.

Connections Usage
(Max_used_connections / max_connections) * 100
This value should be reasonably far from 100%, otherwise consider incrementing the
max_connections parameter in my.cnf.

Key Buffer Usage
(Key_blocks_used / (Key_blocks_used + Key_blocks_unused)) * 100
This value should be reasonably far from 100%, otherwise consider incrementing the
key_buffer_size parameter in my.cnf.

InnoDB Buffer Pool Usage
(1 - (Innodb_buffer_pool_pages_free / Innodb_buffer_pool_pages_total)) * 100
This value should be reasonably far from 100%, otherwise consider incrementing the
innodb_buffer_pool_size parameter in my.cnf.

Temp. Tables To Disk
(Created_temp_disk_tables / Created_temp_disk_tables + Created_temp_tables)) * 100
During operation, MySQL has to create some temporary tables (that can be explicit,
so created by the web application, or implicit, so for example MySQL has to create
one when he runs some "SELECT DISTINCT", "UNION" or "VIEW" queries). MySQL will
prefer to save this tmp tables to memory, for a fast access. But if tmp_table_size
gets saturated, he has to write them on the disk instead, making the access slower.
Note that if you modify the value of tmp_table_size in the MySQL configuration
file, you should also modify the value of max_heap_table_size as well, since both
values should have the same value because MySQL uses the minimum of both, so
raising one of them is useless.
Therefore this value helps to know how many tmp tables go to the disk instead than
to the memory. Keep in mind that some large queries, involving TEXT and BLOB
columns, are directly written to the disk instead than to the memory, because they
would be too big. So you probably will want to avoid having a high % of tmp tables
written to the disk, but you will never reach 0% on a big site, and this is fine.
Lower is better ... but 0% is not reachable and you should not try to reach it,
usually.

PostgreSQL statistics (pgsql.pm)
This graph is able to monitor an unlimited number of PostgreSQL servers.

list
This is a comma-separated list of names of PostgreSQL servers.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the pgsql.rrd file accordingly, removing all historical data.

Default value: localhost

desc
This is a list of blocks of names specified in the list option.

<desc>
<localhost>
host = localhost
port = 5432
username = user
password = secret
db_list =
</localhost>
</desc>

host
This is the hostname or IP address of the PostgreSQL server name specified in its
block.

Default value: localhost

port
This is the port number of the PostgreSQL server name specified in its block.

Default value: 5432

username
This is the username for authentication of the PostgreSQL server name specified in
its block.

password
This is the password for authentication of the PostgreSQL server name specified in
its block.

db_list
This is a comma-separated list of up to 9 databases that will be monitored in the
PostgreSQL server name specified in its block.

MongoDB statistics (mongodb.pm)
This graph is able to monitor an unlimited number of MongoDB servers.

list
This is a comma-separated list of names of MongoDB servers.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the mongodb.rrd file accordingly, removing all historical data.

Default value: localhost

max_db
This is the maximum number of databases to be monitored in a MongoDB server. There
is no limitation, just specify here the number of entries of the db_list option
that has the most entries.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the mongodb.rrd file accordingly, removing all historical data.

Default value: 1

desc
This is a list of blocks of names specified in the list option.

host
This is the hostname or IP address of the MongoDB server specified in its block.

Default value: 127.0.0.1

port
This is the port number of the MongoDB server specified in its block.

Default value:

username
This is the username for authentication of the MongoDB server specified in its
block.

password
This is the password for authentication of the MongoDB server specified in its
block.

db_list
This is a comma-separated list of databases to be monitored of the MongoDB server
specified in its block.

Default value: mydb

Varnish cache statistics (varnish.pm)
This graph monitors a local installation of the Varnish HTTP accelerator.

Only the limit and rigid values can be set here.

PageSpeed Module statistics (pagespeed.pm)
This graph is able to monitor an unlimited number of PageSpeed installations.

list
This is a comma-separated list of URLs of PageSpeed status pages.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the pagespeed.rrd file accordingly, removing all historical data.

Default value: http://modpagespeed.com/mod_pagespeed_statistics

For more information please refer to https://developers.google.com/speed/pagespeed/module
and http://stackoverflow.com/questions/9115595/what-do-the-mod-pagespeed-statistics-mean

Squid Proxy Web Cache (squid.pm)
cmd
This command displays statistics about the Squid HTTP proxy process and is the main
command used to collect all data.

Default value: squidclient -h 127.0.0.1

graph_0
graph_1
These two lists hold the selected Squid result or status codes to be shown in each
graph. Feel free to mix result status and code status in any of the two options.

For more information about the list of all the result and status codes, please
refer to http://wiki.squid-cache.org/SquidFaq/SquidLogs.

Each graph has a limit number of 9 entries.

NFS server statistics (nfss.pm)
version
This option specifies which NFS server version is running in the system in order to
correctly gather the correct values.

The possible values are:
2 for NFS v2.
3 for NFS v3.
4 for NFS v4.

Default value: 3

graph_0
graph_1
graph_2
These three lists hold the defined NFS server activity statistics to be shown in
each graph. Put every statistic name exactly as they appear in the output of the
nfsstat(8) command.

Each graph has a limit number of 10 entries.

NFS client statistics (nfsc.pm)
version
This option specifies which NFS server version is running in the system in order to
correctly gather the correct values.

The possible values are:
2 for NFS v2.
3 for NFS v3.
4 for NFS v4.

Default value: 3

graph_1
graph_2
graph_3
graph_4
graph_5
These five lists hold the defined NFS client activity statistics to be shown in
each graph. Put every statistic name exactly as they appear in the output of the
nfsstat(8) command.

Each graph has the following limit number of entries:

graph_1 up to 10 entries.
graph_2 up to 10 entries.
graph_3 up to 4 entries.
graph_4 up to 4 entries.
graph_5 up to 4 entries.

BIND statistics (bind.pm)
This graph requires a BIND server with version 9.5 or higher, and in order to see all
statistics provided by BIND you must configure the statistics-channels option like this:

statistics-channels {
inet 127.0.0.1 port 8053;
};

This graph is able to monitor an unlimited number of BIND servers.

list
This is a comma-separated list of URLs of BIND servers status pages.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the bind.rrd file accordingly, removing all historical data.

Default value: http://localhost:8053/

in_queries_list
This is a comma-separated list of RR (Resource Records) types for each BIND server
specified in list option. The RR types defined here will appear in the Incoming
Queries graph which shows the number of incoming queries for each RR type.

For a complete list of RR types check the BIND 9 Administrator Reference Manual at
<http://ftp.isc.org/www/bind/arm95/Bv9ARM.html>.

<in_queries_list>
http://localhost:8053/ = A, AAAA, ANY, DS, MX, NS, PTR, SOA, SRV, TXT, NAPTR,
A6, CNAME, SPF, KEY, DNSKEY, HINFO, WKS, PX, NSAP
</in_queries_list>

The maximum number of RR types allowed for this graph is 20.

out_queries_list
This is a comma-separated list of RR (Resource Records) types for each BIND server.
The RR types defined here will appear in the Outgoing Queries graph (_default view)
which shows the number of outgoing queries sent by the DNS server resolver for each
RR type.

<out_queries_list>
http://localhost:8053/ = A, AAAA, ANY, DS, MX, NS, PTR, SOA, SRV, TXT, NAPTR,
A6, CNAME, SPF, KEY, DNSKEY, HINFO, WKS, PX, NSAP
</out_queries_list>

The maximum number of RR types allowed for this graph is 20.

server_stats_list
This is a comma-separated list of counters about incoming request processing. The
counters defined here will appear in the Server Statistics graph.

<server_stats_list>
http://localhost:8053/ = Requestv4, Requestv6, ReqEdns0, ReqBadEDNSVer,
ReqTSIG, ReqSIG0, ReqBadSIG, ReqTCP, Response, QrySuccess, QryAuthAns,
QryNoauthAns, QryReferral, QryNxrrset, QrySERVFAIL, QryNXDOMAIN, QryRecursion,
QryDuplicate, QryDropped, QryFailure
</server_stats_list>

The maximum number of counters allowed for this graph is 20.

resolver_stats_list
This is a comma-separated list of counters about name resolution performed in the
internal resolver. The counters defined here will appear in the Resolver Statistics
graph (_default view).

<resolver_stats_list>
http://localhost:8053/ = Queryv4, Queryv6, Responsev4, Responsev6, NXDOMAIN,
SERVFAIL, FORMERR, OtherError, EDNS0Fail, Truncated, Lame, Retry, QueryTimeout,
GlueFetchv4, GlueFetchv6, GlueFetchv4Fail, GlueFetchv6Fail, ValAttempt, ValOk,
ValNegOk
</resolver_stats_list>

The maximum number of counters allowed for this graph is 20.

cache_rrsets_list
This is a comma-separated list of RR (Resource Records) types for each BIND server.
The RR types defined here will appear in the Cache DB RRsets graph (_default view)
which shows the number of RRsets per RR type (positive or negative) and nonexistent
names stored in the cache database.

<cache_rrsets_list>
http://localhost:8053/ = A, !A, AAAA, !AAAA, DLV, !DLV, DS, !DS, MX, NS,
CNAME, !CNAME, SOA, !SOA, !ANY, PTR, RRSIG, NSEC, DNSKEY, NXDOMAIN
</cache_rrsets_list>

The maximum number of RR types allowed for this graph is 20.

Unbound statistics (unbound.pm)
This graph monitors a local installation of an Unbound name server. It requires you to
configure the options extended-statistics as yes and statistics-cumulative as no.

cmd
This is the command that will be used to gather statistics from Unbound.

Default value: unbound-control

queries_type
This is a comma-separated list of query types. The types defined here will appear
in the Queries by type graph.

Default value: queries_type = A, AAAA, ANY, DS, MX, NS, PTR, SOA, SRV, TXT, NAPTR,
A6, CNAME, SPF, KEY, DNSKEY, HINFO, WKS, PX, NSAP

The maximum number of types allowed for this graph is 20.

NTP statistics (ntp.pm)
This graph is able to monitor an unlimited number of NTP servers.

list
This is a comma-separated list of NTP servers.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the ntp.rrd file accordingly, removing all historical data.

Default value: localhost

desc
This is a list of groups of Reference Identifier and Kiss-o'-Death Codes for every
hostname specified in the list option.

For more information on these NTP codes:
<http://www.iana.org/assignments/ntp-parameters/ntp-parameters.xml>
<http://www.iana.org/go/rfc5905>

<desc>
localhost = AUTH, AUTO, CRYP, DENY, GPS, INIT, NKEY, RATE, RMOT, RSTR
</desc>

The maximum number of codes allowed for each hostname is 10.

extra_args
This option includes any extra argument to the NTP command executed by Monitorix,
which is "ntpq -pn". This is specially useful if you want to force using IPv4, in
this case just define this option like this:

extra_args = "-4"

Monitorix will add this extra argument to the NTP command which will become as
"ntpq -pn -4".

Chrony statistics (chrony.pm)
This graph is able to monitor an unlimited number of Chrony daemons.

list
This is a comma-separated list of hostnames with the network port running chronyd.
The format is <hostname>[:<port>] being the port part optional.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the chrony.rrd file accordingly, removing all historical data.

Default value: localhost

Fail2ban statistics (fail2ban.pm)
This graph is able to monitor an unlimited number of Fail2ban jails.

list
This is a comma-separated list that describes the groups of jails in desc. Put one
description for each group. For every group specified you need to specify its
description in the desc option.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the fail2ban.rrd file accordingly, removing all historical data.

An example would be:

list = Security, Overload / Abuse

desc
This is a list of jails per group defined in your Fail2ban configuration.

<desc>
0 = [apache], [apache-mod-security], [apache-overflows], [courierauth], [ssh],
[pam-generic], [php-url-fopen], [vsftpd]
1 = [apache-imdbphp], [apache-evasive], [apache-badbots], [apache-robots-txt],
[communigate], [named-refused-udp], [named-refused-tcp], [trac-ticketspam]
</desc>

The maximum number of jails allowed for each group is 9.

graphs_per_row
This is the number of fail2ban graphs that will be put in a row.

Default value: 2

graph_mode
This option changes how the values are represented in the graph. It has two
possible values: absolute which is the default, and rate. The former takes the
values directly from the command fail2ban-client status <JAIL> and so the values in
the graph will appear as absolute. The later option shows the values in a rating
format per minute.

Default value: absolute

Icecast Streaming Media Server (icecast.pm)
This graph is able to monitor an unlimited number of Icecast servers.

list
This is a list of URLs of Icecast server status pages.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the icecast.rrd file accordingly, removing all historical data.

Default value: http://localhost:8000/status.xsl

desc
This is a comma-separated list of Mount Points configured for every URL specified
in the list option. IMPORTANT: the Mount Points must be specified in the same order
that appears in the Icecast Server Status page.

<desc>
http://localhost:8000/status.xsl = stream1, stream2, stream3
</desc>

The maximum number of mountpoints allowed for each URL is 9.

graph_mode
This changes the layout of the listeners graph, the possible values are r for a
real graph, or s for a stacked graph (every line or area is stacked on top of the
previous element).

Default value: r

Raspberry Pi sensor statistics (raspberrypi.pm)
For more information please refer to http://elinux.org/RPI_vcgencmd_usage.

cmd
This is where the vcgencmd command is installed.

Default value: /usr/bin/vcgencmd

clocks
This is a comma-separated list of clock types that will be represented in the first
graph.

An example would be:

clocks = arm, core, h264, isp, v3d, uart, emmc, pixel, hdmi

The maximum number of clocks allowed is 9.

volts
This is a comma-separated list of voltage types that will be represented in the
third graph.

An example would be:

volts = core, sdram_c, sdram_i, sdram_p

The maximum number of clocks allowed is 6.

Alternative PHP Cache statistics (phpapc.pm)
This graph is able to monitor an unlimited number of PHP-APC installations.

list
This is a comma-separated list of URLs of PHP-APC status pages.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the phpapc.rrd file accordingly, removing all historical data.

Default value: http://localhost/apc.php?auto

Memcached statistics (memcached.pm)
This graph is able to monitor an unlimited number of Memcached installations.

list
This is a comma-separated list of hostnames with network port running Memcached.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the memcached.rrd file accordingly, removing all historical data.

Default value: localhost:11211

Redis statistics (redis.pm)
This graph is able to monitor an unlimited number of Redis installations.

list
This is a comma-separated list of hostnames with network port running Redis.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the redis.rrd file accordingly, removing all historical data.

Default value: localhost:6379

PHP-FPM statistics (phpfpm.pm)
This graph is able to monitor an unlimited number of PHP-FPM pools.

group
This is a list of names (separated by comma) of the groups of pools that you want
to monitor. The pools included in each group will be defined in the list option.
You can define unlimited number of groups.

WARNING: Every time the number of groups changes, Monitorix will resize the
phpfpm.rrd file accordingly, removing all historical data.

An example of this option would be:

<group>
0 = First group of domains
1 = Second group of domains
</group>

list
This is a list of pool names that you want to monitor for each group defined in
group.

An example of this option would be:

<list>
0 = example1, example2, example3
1 = example10, example11
</list>

The maximum number of pools allowed per group is 8.

desc
This list complements the list option, it defines where and how Monitorix must
gather the statistics for each pool defined.

An example of this option would be:

<desc>
example1 = http://www.example1.com/php_fpm_status
example2 = http://www.example2.com/php_fpm_status
example3 = http://www.example3.com/php_fpm_status
example10 = http://www.example10.com/php_fpm_status
example11 = http://www.example11.com/php_fpm_status
</desc>

map
This list also complements the list option. It basically allows you to change the
name that will appear in the graph, hiding the real name of the pool. If no
association is defined, then Monitorix will display the name specified in the list
option.

An example of this option would be:

<map>
example1 = DOMAIN4
example12 = DOMAIN55
</map>

APC UPS statistics (apcupsd.pm)
This graph is able to monitor an unlimited number of APC UPS (apcupsd) installations.

cmd
This is the command that will be used (with the values in list) to get the
statistics.

Default value: apcaccess

list
This is a comma-separated list of hostnames with the network port running apcupsd.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the apcupsd.rrd file accordingly, removing all historical data.

Default value: localhost:3551

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

skipscale_for_transfer_voltage
This option, when enabled via y, ignores the transfer voltage graph when scaling
the plot axis.

Default value: n

skipscale_for_shutdown_level
This option, when enabled via y, ignores the shutdown level graph when scaling the
plot axis.

Default value: n

alt_scaling_for_voltage
This option, when enabled via y, sets alternate plot axis scaling for the voltage
graph. This can be useful to improve the scaling in some cases.

Default value: n

alt_scaling_for_timeleft
This option, when enabled via y, sets alternate plot axis scaling for the time left
graph. This can be useful to improve the scaling in some cases.

Default value: n

alt_scaling_for_battery_voltage
This option, when enabled via y, sets alternate plot axis scaling for the battery
voltage graph. This can be useful to improve the scaling in some cases.

Default value: n

Network UPS Tools statistics (nut.pm)
This graph is able to monitor an unlimited number of Network UPS Tools (upsc)
installations.

list
This is a comma-separated list of UPS names with optionally the hostname and the
network port where it's running upsd. The format of each entry must be:

upsname[@hostname[:port]]

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the nut.rrd file accordingly, removing all historical data.

Default value: ups@localhost

use_nan_for_missing_data
This option, when enabled via y, shows nan values for missing data instead of 0.
This is useful when 0 could be mistaken for valid data.

Default value: n

ignore_error_output
This option, when enabled via y, suppresses error output from upsc.

Default value: n

skipscale_for_transfer_voltage
This option, when enabled via y, ignores the transfer voltage graph when scaling
the plot axis.

Default value: n

skipscale_for_shutdown_level
This option, when enabled via y, ignores the shutdown level graph when scaling the
plot axis.

Default value: n

alt_scaling_for_voltage
This option, when enabled via y, sets alternate plot axis scaling for the voltage
graph. This can be useful to improve the scaling in some cases.

Default value: n

alt_scaling_for_timeleft
This option, when enabled via y, sets alternate plot axis scaling for the time left
graph. This can be useful to improve the scaling in some cases.

Default value: n

alt_scaling_for_battery_voltage
This option, when enabled via y, sets alternate plot axis scaling for the battery
voltage graph. This can be useful to improve the scaling in some cases.

Default value: n

Wowza Media Server (wowza.pm)
This graph is able to monitor an unlimited number of Wowza servers.

list
This is a comma-separated list of URLs of Wowza server status pages. Each URL can
include the Basic Authentication in the form of
http://username:password@localhost:8086/connectioncounts.

WARNING: Every time the number of entries in this option changes, Monitorix will
resize the wowza.rrd file accordingly, removing all historical data.

Default value: http://localhost:8086/connectioncounts

desc
This is a comma-separated list of applications configured for every URL specified
in the list option.

<desc>
http://localhost:8086/connectioncounts = channel1, channel2, channel3
</desc>

The maximum number of applications allowed for each URL is 8.

Devices interrupt activity (int.pm)
Only the limit and rigid values can be set here.

Verlihub statistics (verlihub.pm)
This graph monitors the Verlihub software for DC++ network.

Monitoring the Internet traffic of your LAN (traffacct.pm)
If your server acts as the gateway for a group of PCs, devices or even whole networks in
your local LAN, you may want to know how much Internet traffic each one is generating.

This graph requires the iptables(8) command on GNU/Linux systems, and the ipfw command on
*BSD systems.

The following are the options you will need to configure to accomplish all of this.

enabled
This option enables this feature.

Default value: n

max
This is the number of LAN devices you want to monitor. There is no limit, but keep
in mind that every time this number changes, Monitorix will resize the
traffacct.rrd file, removing all historical data.

Default value: 10

graphs_per_row
If your horizontal screen resolution is pretty wide, you may want to increase the
number of graphs that appear on each row.

Default value: 2

list
This is a comma-separated list of names of PCs, LAN devices or whole networks that
you want to monitor. The only requirement is that all they must utilize this server
as their gateway.

If the names in this list are able to be resolved by a DNS query then you don't
need to define the desc list (below) with corresponding IP addresses, unless you
want monthly reports.

An example would be:

list = pc8, printer, pc9, scanner

desc
This is the list of IPv4 or IPv6 addresses with network masks and email addresses
corresponding to the entries defined in the list. This option is only used when the
those entries are not resolvable through a DNS query.

An example would be:

<desc>
0 = 192.168.1.101/32, ace@example.com
1 = 192.168.1.102/32, gene@example.com
2 = 192.168.1.103/32, paul@example.com
3 = 2607:6300:93:1::/64, peter@example.com
</desc

Monthly reports of Internet traffic (traffacct.pm)
enabled
If this option is set to y, Monitorix will send a report of all the monthly
Internet activity of the defined devices in list to the specified email address on
the first day of each month.

Default value: n

language
Define here the language used in the monthly report.

The current possible values are: ca, de, en, it, nl_NL, pl and zh_CN.

Default value: en

default_mail
This is the default email address used to send the monthly reports. This option is
only used if the second parameter in desc list is empty.

Default value: root@localhost

url_prefix
This is the prefix of the same URL you use to connect to Monitorix. This is needed
in order to get the graphs of the same machine.

Default value: http://localhost:8080

smtp_hostname
This is the hostname that will be used as a SMTP relay to deliver the monthly
report emails.

Default value: localhost

from_address
This is the address that will be used as remittent for all the monthly report
emails.

Default value: noreply@example.com

Monitoring remote servers (Multihost)
The Multihost feature allows you to monitor an unlimited number of remote servers that
already have Monitorix installed. Make sure that all servers (local and remote) have the
same version of Monitorix, otherwise there would be some incompatibilities that would
prevent showing correctly the graphs.

enabled
This option enables the Multihost feature.

Default value: n

footer_url
If set to y Monitorix will show the original URL of each server at the bottom of
the graph. Where security is important you may want to hide this information.

Default value: y

graphs_per_row
If your horizontal screen resolution is pretty wide, you may want to increase the
number of graphs that appear on each row.

Default value: 2

default_option_when_all
If the user has defined a considerable amount of remote servers and it selects the
option "All" in the Hostname list and "All graphs" in the Graph list, the browser
may hang for a while due to the huge amount of images to download remotely from
different servers.

This option prevents precisely that this happens accidentally by setting a default
value in the Graph list. Of course, the user is able to change it to "All graphs"
at any moment.

The value of this option may be any of the ones that appear in the <graphs> section
(near the end) of the monitorix.conf file.

Default value: "System load"

remotehost_list
This is a comma-separated list with descriptive names of remote servers with
Monitorix already installed and working that you plan to monitor from here.

An example of this list would be:

remotehost_list = server 1, server 2, server 3

remotehost_desc
This is a numbered list that describes each of the names defined in the
remotehost_list option and the remote values of base_url and base_cgi options.

An example would be:

<remotehost_desc>
0 = http://www.example.com,/monitorix,/monitorix-cgi
1 = http://10.0.0.1,/monitorix,/monitorix-cgi
2 = http://192.168.0.100:8080,/,/
</remotehost_desc>

As you can see all these three entries use URLs to designate the location of each
remote server. This means that each server most also have been enabled the HTTP
built-in server, or have been installed a CGI capable web server like Apache.

groups
This enables the server grouping for those environments where there are too much
servers to display at the same time. Hence, you can group them in order to show
them separately.

Default value: n

remotegroup_list
This is a list of groups of remote servers with Monitorix already installed and
working that you plan to monitor from here.

An example of this list would be:

remotegroup_list = My Group

remotegroup_desc
This is a numbered list that describes each of the names defined in the
remotegroup_list option.

An example would be:

<remotegroup_desc>
0 = server2, server 3
</remotegroup_desc>

Automatic email reports (emailreports)
This allows one to send automatically selected graphs to one or more email addresses. This
could be specially useful for some system administrators who prefer receiving via email
selected graphs instead of browsing to the remote servers every day.

enabled
This option enables this feature. Note that you still need to enable the same
option for each time interval you want to activate: daily, weekly, monthly, yearly.

Default value: n

url_prefix
This is the prefix of the same URL you use to connect to Monitorix. Such URL is
needed in order to get the graphs of that machine.

This option supports sending the credentials in the standard HTTP "Authorization"
header, just like this:

http://username:password@localhost:8080

Default value: http://localhost:8080

smtp_hostname
This is the hostname that will be used as a SMTP relay to deliver the automatic
email reports.

method
This option specifies the method of sending emails. The current valid options are
smtp and relay. By default this option is not defined which is the same as if smtp
option was defined.

Default value:

from_address
This is the address that will be used as remittent for all the monthly report
emails.

Default value: noreply@example.com

subject_prefix
This is a string that will be prefixed in the Subject of all emails that will be
sent.

Default value: Monitorix:

hour
This is the hour (in 24h format) when the email reports will be sent.

Default value: 0

minute
This is the minute when the email reports will be sent.

Default value: 0

daily
weekly
monthly
yearly
The email reports are sent based on the following schedule:

daily reports will be sent every day at 00:00h.
weekly reports will be sent the first Monday of each week.
monthly reports will be sent the first day of each month.
yearly reports will be sent the first day of each year.

enabled
This option enables each report individually.

Default value: n

graphs
This is a comma-separated list of graph names you want to appear in the email
report. The names are the same as their .rrd files. There is a list of them in the
graph_name option in monitorix.conf.

Default value: system, fs

to
This is a comma-separated list of recipient email addresses.

addendum_script
This is the full path name of an external script that will be executed during the
creation of the report, and its output will be appended to the mail. This is useful
for system administrators that want to add extra system information to the reports.

Default value:

rigid and limit values
rigid
This value defines how the graph must be scaled. Its possible values are:

0 No rigid, the graph will be scaled automatically. Only the lower-limit value
will be used if it's defined.
1 The graph will be scaled by default according the values in limit but without
rigidness.
2 The graph will be forced to scale using the contents of limit as its upper-
limit and lower-limit values.

limit
This is where you can enter the upper-limit and lower-limit values (separated by a
colon) for a graph. The lower-limit value is optional. Some examples would be:

100:0 which means 100 as the upper-limit value and 0 for the lower-limit value.
This is commonly used for percentage values.
1000 which means 1000 as the upper-limit value and leaving undefined the lower-
limit value. This can also be written as 1000:.

AUTHOR

       Monitorix is written by Jordi Sanfeliu <jordi@fibranet.cat>

COPYRIGHT

       Copyright © 2005-2022 Jordi Sanfeliu
       Licensed under the GNU General Public License version 2 (GPLv2).

NAME

DESCRIPTION

CONFIGURATION OPTIONS

AUTHOR

COPYRIGHT

SEE ALSO