# pmdanetcheck

## 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).
    


* * *