1PMDANETCHECK(1) General Commands Manual PMDANETCHECK(1)
2
6 pmdanetcheck - netcheck PMDA
7
9 pmdanetcheck is a Performance Co-Pilot (PCP) Performance Metrics Domain
10 Agent (PMDA) which does basic network checks on the local host by using
11 simple Python modules and, in some cases, external utilities such as
12 ping(1).
13 pmdanetcheck loads and acts as a bridge for any number of configured,
15 separate PCP netcheck PMDA Python modules running Python code or exter‐
16 nal programs. Existing Python modules and programs should be possible
17 to be utilized with PCP netcheck PMDA modules with minimal effort.
18 Note that on SELinux enabled systems for pmdanetcheck to be able to use
20 the ping(1) command the pcp group must be able to create ICMP Echo
21 sockets; please make sure the group id for pcp is included in the range
22 at /proc/sys/net/ipv4/ping_group_range and refer to icmp(7) for more
23 details on this.
24
26 pmdanetcheck reads a mandatory ini-style configuration file:
27 $PCP_PMDAS_DIR/netcheck/netcheck.conf
29 This file must contain a [pmda] section. The following PMDA options
31 are available (their default values are shown in parenthesis), options
32 marked with asterisk (*) can be overridden in module-specific configu‐
33 ration sections:
34 modules (unset)
36 The pmdanetcheck PMDA reads module-specific configura‐
37 tion for each module listed in the comma-separated list
38 of modules (mandatory).
39 hosts (DGW,DNS) *
41 A comma-separated list of hosts (optional) specifies the
42 hosts to run the checks for. The special values DGW,
43 DNS, NTP will be translated to the default gateway,
44 nameservers listed in /etc/resolv.conf, and timeservers
45 listed in /etc/chrony.conf, respectively, on PMDA
46 startup.
47 background_check (True) *
49 A boolean value for background_check (optional) controls
50 whether to run checks constantly in the background or
51 only on demand. Refer to the default configuration file
52 for more discussion about this.
53 check_hosts_parallel (True) *
55 check_hosts_parallel (optional) controls whether modules
56 should check hosts one by one or in parallel.
57 check_interval (1m) *
59 check_interval (optional) specifies the time interval
60 between two consecutive checks for hosts when checks are
61 done in the background. Refer to PCPIntro(1) for a com‐
62 plete description of the syntax for the time interval.
63 align_interval (True) *
65 align_interval (optional) specifies whether to take the
66 previous check duration into account when pausing be‐
67 tween checks.
68 module_failure_fatal (True)
70 A boolean value for module_failure_fatal (optional) con‐
71 trols whether a module failing to initialize should
72 cause the whole PMDA to abort (this is the default) or
73 to start up with possibly remaining functional modules.
74 Module configuration errors and internal errors (such as
75 failing to register the provided PMNS metrics, see
76 pmns(5)) will always cause the PMDA to fail to start.
77 For each module listed in modules a corresponding [module] section must
79 be defined. Each [module] section can contain at least the following
80 options (their default values are shown in parenthesis):
81 timeout (1) Force a hard timeout (optional) for each individual net‐
83 work check operation.
84 debug (False) Enable logging of internal debug messages (rarely used).
86 The module-specific options modules accept are described in the default
88 configuration file.
89 Modules expect basic network functionality to be present on the system,
91 for example the localhost address being reachable.
92
94 To install, the following must be done as root:
95 # cd $PCP_PMDAS_DIR/netcheck
97 # ./Install
98 To uninstall, the following must be done as root:
100 # cd $PCP_PMDAS_DIR/netcheck
102 # ./Remove
103 pmdanetcheck is launched by pmcd(1) and should never be executed di‐
105 rectly. The Install and Remove scripts notify pmcd(1) when the agent
106 is installed or removed.
107 In case module_failure_fatal is set to False, the PMDA installation
109 will be considered successful if some (but not all) configured modules
110 fail to load, in such cases metrics provided by the failing modules
111 will not be available. The pmdanetcheck agent log file (see below)
112 will contain detailed information about activation of each module.
113 Modules will provide real values only after having collected data. For
115 example, for the ping module the metric value is the exit value of the
116 ping(1) command and for ping_latency the average packet latency as re‐
117 ported by ping(1). For metrics indicating status, 0 denotes success.
118 In case a check has not finished yet its metric value is -1. If a
119 check was terminated during execution due to timeout the value is -2.
120
122 $PCP_PMDAS_DIR/netcheck/netcheck.conf
123 configuration file for the pmdanetcheck agent
124 $PCP_PMDAS_DIR/netcheck/netcheck/*.{py,python}
126 PCP netcheck PMDA Python modules for the pmdanetcheck agent
127 $PCP_PMDAS_DIR/netcheck/Install
129 installation script for the pmdanetcheck agent
130 $PCP_PMDAS_DIR/netcheck/Remove
132 undo installation script for the pmdanetcheck agent
133 $PCP_LOG_DIR/pmcd/netcheck.log
135 default log file for messages from the pmdanetcheck agent
136 Note that the usual/default value for $PCP_PMDAS_DIR is
138 /var/lib/pcp/pmdas and the default for $PCP_LOG_DIR is /var/log/pcp but
139 these settings are platform dependent.
140
142 Environment variables with the prefix PCP_ are used to parameterize the
143 file and directory names used by PCP. On each installation, the file
144 /etc/pcp.conf contains the local values for these variables. The
145 $PCP_CONF variable may be used to specify an alternative configuration
146 file, as described in pcp.conf(5).
147
149 PCPIntro(1), ping(1), pmcd(1), getaddrinfo(3), resolver(3),
150 gai.conf(5), resolv.conf(5), resolver(5), icmp(7) and ip(8).
151Performance Co-Pilot PCP PMDANETCHECK(1)