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

CONFIGURATION

20       pmdanetcheck reads a mandatory ini-style configuration file:
21
22              $PCP_PMDAS_DIR/netcheck/netcheck.conf
23
24       This  file  must  contain a [pmda] section.  The following PMDA options
25       are available (their default values are shown in parenthesis),  options
26       marked  with asterisk (*) can be overridden in module-specific configu‐
27       ration sections:
28
29       modules (unset)
30                      The pmdanetcheck PMDA reads  module-specific  configura‐
31                      tion  for each module listed in the comma-separated list
32                      of modules (mandatory).
33
34       hosts (DGW,DNS) *
35                      A comma-separated list of hosts (optional) specifies the
36                      hosts  to  run  the checks for.  The special values DGW,
37                      DNS, NTP will be  translated  to  the  default  gateway,
38                      nameservers  listed in /etc/resolv.conf, and timeservers
39                      listed  in  /etc/chrony.conf,  respectively,   on   PMDA
40                      startup.
41
42       background_check (True) *
43                      A boolean value for background_check (optional) controls
44                      whether to run checks constantly in  the  background  or
45                      only on demand.  Refer to the default configuration file
46                      for more discussion about this.
47
48       check_hosts_parallel (True) *
49                      check_hosts_parallel (optional) controls whether modules
50                      should check hosts one by one or in parallel.
51
52       check_interval (1m) *
53                      check_interval  (optional)  specifies  the time interval
54                      between two consecutive checks for hosts when checks are
55                      done in the background.  Refer to PCPIntro(1) for a com‐
56                      plete description of the syntax for the time interval.
57
58       align_interval (True) *
59                      align_interval (optional) specifies whether to take  the
60                      previous   check  duration  into  account  when  pausing
61                      between checks.
62
63       module_failure_fatal (True)
64                      A boolean value for module_failure_fatal (optional) con‐
65                      trols  whether  a  module  failing  to initialize should
66                      cause the whole PMDA to abort (this is the  default)  or
67                      to  start up with possibly remaining functional modules.
68                      Module configuration errors and internal errors (such as
69                      failing  to  register  the  provided  PMNS  metrics, see
70                      pmns(5)) will always cause the PMDA to fail to start.
71
72       For each module listed in modules a corresponding [module] section must
73       be  defined.   Each [module] section can contain at least the following
74       options (their default values are shown in parenthesis):
75
76       timeout (1)    Force a hard timeout (optional) for each individual net‐
77                      work check operation.
78
79       debug (False)  Enable logging of internal debug messages (rarely used).
80
81       The module-specific options modules accept are described in the default
82       configuration file.
83
84       Modules expect basic network functionality to be present on the system,
85       for example the localhost address being reachable.
86

INSTALLATION

88       To install, the following must be done as root:
89
90           # cd $PCP_PMDAS_DIR/netcheck
91           # ./Install
92
93       To uninstall, the following must be done as root:
94
95           # cd $PCP_PMDAS_DIR/netcheck
96           # ./Remove
97
98       pmdanetcheck  is  launched  by  pmcd(1)  and  should  never be executed
99       directly.  The Install and Remove scripts notify pmcd(1) when the agent
100       is installed or removed.
101
102       In  case  module_failure_fatal  is  set to False, the PMDA installation
103       will be considered successful if some (but not all) configured  modules
104       fail  to  load,  in  such cases metrics provided by the failing modules
105       will not be available.  The pmdanetcheck agent  log  file  (see  below)
106       will contain detailed information about activation of each module.
107
108       Modules will provide real values only after having collected data.  For
109       example, for the ping module the metric value is the exit value of  the
110       ping(1)  command  and  for  ping_latency  the average packet latency as
111       reported by ping(1).  For metrics indicating status, 0 denotes success.
112       In  case  a  check  has  not finished yet its metric value is -1.  If a
113       check was terminated during execution due to timeout the value is -2.
114

FILES

116       $PCP_PMDAS_DIR/netcheck/netcheck.conf
117            configuration file for the pmdanetcheck agent
118
119       $PCP_PMDAS_DIR/netcheck/netcheck/*.{py,python}
120            PCP netcheck PMDA Python modules for the pmdanetcheck agent
121
122       $PCP_PMDAS_DIR/netcheck/Install
123            installation script for the pmdanetcheck agent
124
125       $PCP_PMDAS_DIR/netcheck/Remove
126            undo installation script for the pmdanetcheck agent
127
128       $PCP_LOG_DIR/pmcd/netcheck.log
129            default log file for messages from the pmdanetcheck agent
130
131       Note   that   the   usual/default   value   for    $PCP_PMDAS_DIR    is
132       /var/lib/pcp/pmdas and the default for $PCP_LOG_DIR is /var/log/pcp but
133       these settings are platform dependent.
134

PCP ENVIRONMENT

136       Environment variables with the prefix PCP_ are used to parameterize the
137       file  and  directory names used by PCP.  On each installation, the file
138       /etc/pcp.conf contains the  local  values  for  these  variables.   The
139       $PCP_CONF  variable may be used to specify an alternative configuration
140       file, as described in pcp.conf(5).
141

SEE ALSO

143       PCPIntro(1),    ping(1),    pmcd(1),    getaddrinfo(3),    resolver(3),
144       gai.conf(5), resolv.conf(5), resolver(5), and ip(8).
145
146
147
148Performance Co-Pilot                  PCP                      PMDANETCHECK(1)
Impressum