Provided by: pcp_5.3.6-1build1_amd64 
NAME
pmdanetcheck - netcheck PMDA
DESCRIPTION
pmdanetcheck is a Performance Co-Pilot (PCP) Performance Metrics Domain Agent (PMDA) which
does basic network checks on the local host by using simple Python modules and, in some
cases, external utilities such as ping(1).
pmdanetcheck loads and acts as a bridge for any number of configured, separate PCP
netcheck PMDA Python modules running Python code or external programs. Existing Python
modules and programs should be possible to be utilized with PCP netcheck PMDA modules with
minimal effort.
Note that on SELinux enabled systems for pmdanetcheck to be able to use the ping(1)
command the pcp group must be able to create ICMP Echo sockets; please make sure the group
id for pcp is included in the range at /proc/sys/net/ipv4/ping_group_range and refer to
icmp(7) for more details on this.
CONFIGURATION
pmdanetcheck reads a mandatory ini-style configuration file:
$PCP_PMDAS_DIR/netcheck/netcheck.conf
This file must contain a [pmda] section. The following PMDA options are available (their
default values are shown in parenthesis), options marked with asterisk (*) can be
overridden in module-specific configuration sections:
modules (unset)
The pmdanetcheck PMDA reads module-specific configuration for each module
listed in the comma-separated list of modules (mandatory).
hosts (DGW,DNS) *
A comma-separated list of hosts (optional) specifies the hosts to run the
checks for. The special values DGW, DNS, NTP will be translated to the
default gateway, nameservers listed in /etc/resolv.conf, and timeservers
listed in /etc/chrony.conf, respectively, on PMDA startup.
background_check (True) *
A boolean value for background_check (optional) controls whether to run
checks constantly in the background or only on demand. Refer to the
default configuration file for more discussion about this.
check_hosts_parallel (True) *
check_hosts_parallel (optional) controls whether modules should check hosts
one by one or in parallel.
check_interval (1m) *
check_interval (optional) specifies the time interval between two
consecutive checks for hosts when checks are done in the background. Refer
to PCPIntro(1) for a complete description of the syntax for the time
interval.
align_interval (True) *
align_interval (optional) specifies whether to take the previous check
duration into account when pausing between checks.
module_failure_fatal (True)
A boolean value for module_failure_fatal (optional) controls whether a
module failing to initialize should cause the whole PMDA to abort (this is
the default) or to start up with possibly remaining functional modules.
Module configuration errors and internal errors (such as failing to
register the provided PMNS metrics, see pmns(5)) will always cause the PMDA
to fail to start.
For each module listed in modules a corresponding [module] section must be defined. Each
[module] section can contain at least the following options (their default values are
shown in parenthesis):
timeout (1) Force a hard timeout (optional) for each individual network check
operation.
debug (False) Enable logging of internal debug messages (rarely used).
The module-specific options modules accept are described in the default configuration
file.
Modules expect basic network functionality to be present on the system, for example the
localhost address being reachable.
INSTALLATION
To install, the following must be done as root:
# cd $PCP_PMDAS_DIR/netcheck
# ./Install
To uninstall, the following must be done as root:
# cd $PCP_PMDAS_DIR/netcheck
# ./Remove
pmdanetcheck is launched by pmcd(1) and should never be executed directly. The Install
and Remove scripts notify pmcd(1) when the agent is installed or removed.
In case module_failure_fatal is set to False, the PMDA installation will be considered
successful if some (but not all) configured modules fail to load, in such cases metrics
provided by the failing modules will not be available. The pmdanetcheck agent log file
(see below) will contain detailed information about activation of each module.
Modules will provide real values only after having collected data. For example, for the
ping module the metric value is the exit value of the ping(1) command and for ping_latency
the average packet latency as reported by ping(1). For metrics indicating status, 0
denotes success. In case a check has not finished yet its metric value is -1. If a check
was terminated during execution due to timeout the value is -2.
FILES
$PCP_PMDAS_DIR/netcheck/netcheck.conf
configuration file for the pmdanetcheck agent
$PCP_PMDAS_DIR/netcheck/netcheck/*.{py,python}
PCP netcheck PMDA Python modules for the pmdanetcheck agent
$PCP_PMDAS_DIR/netcheck/Install
installation script for the pmdanetcheck agent
$PCP_PMDAS_DIR/netcheck/Remove
undo installation script for the pmdanetcheck agent
$PCP_LOG_DIR/pmcd/netcheck.log
default log file for messages from the pmdanetcheck agent
Note that the usual/default value for $PCP_PMDAS_DIR is /var/lib/pcp/pmdas and the default
for $PCP_LOG_DIR is /var/log/pcp but these settings are platform dependent.
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory
names used by PCP. On each installation, the file /etc/pcp.conf contains the local values
for these variables. The $PCP_CONF variable may be used to specify an alternative
configuration file, as described in pcp.conf(5).
SEE ALSO
PCPIntro(1), ping(1), pmcd(1), getaddrinfo(3), resolver(3), gai.conf(5), resolv.conf(5),
resolver(5), icmp(7) and ip(8).