1PMDANETCHECK(1)             General Commands Manual            PMDANETCHECK(1)
2
3
4

NAME

6       pmdanetcheck - netcheck PMDA
7

DESCRIPTION

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
14       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
19       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

CONFIGURATION

26       pmdanetcheck reads a mandatory ini-style configuration file:
27
28              $PCP_PMDAS_DIR/netcheck/netcheck.conf
29
30       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
35       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
40       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
48       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
54       check_hosts_parallel (True) *
55                      check_hosts_parallel (optional) controls whether modules
56                      should check hosts one by one or in parallel.
57
58       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
64       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
69       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
78       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
82       timeout (1)    Force a hard timeout (optional) for each individual net‐
83                      work check operation.
84
85       debug (False)  Enable logging of internal debug messages (rarely used).
86
87       The module-specific options modules accept are described in the default
88       configuration file.
89
90       Modules expect basic network functionality to be present on the system,
91       for example the localhost address being reachable.
92

INSTALLATION

94       To install, the following must be done as root:
95
96           # cd $PCP_PMDAS_DIR/netcheck
97           # ./Install
98
99       To uninstall, the following must be done as root:
100
101           # cd $PCP_PMDAS_DIR/netcheck
102           # ./Remove
103
104       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
108       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
114       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

FILES

122       $PCP_PMDAS_DIR/netcheck/netcheck.conf
123            configuration file for the pmdanetcheck agent
124
125       $PCP_PMDAS_DIR/netcheck/netcheck/*.{py,python}
126            PCP netcheck PMDA Python modules for the pmdanetcheck agent
127
128       $PCP_PMDAS_DIR/netcheck/Install
129            installation script for the pmdanetcheck agent
130
131       $PCP_PMDAS_DIR/netcheck/Remove
132            undo installation script for the pmdanetcheck agent
133
134       $PCP_LOG_DIR/pmcd/netcheck.log
135            default log file for messages from the pmdanetcheck agent
136
137       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

PCP ENVIRONMENT

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

SEE ALSO

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).
151
152
153
154Performance Co-Pilot                  PCP                      PMDANETCHECK(1)
Impressum