# pmieconf

## NAME



           **pmieconf** - display and set configurable pmie rule variables
    


## SYNOPSIS



           **pmieconf**[**-cFv?**]  [**-f** _file_] [**-r** _rulepath_] [_command_ [_args..._]]
    


## DESCRIPTION



           **pmieconf** is a utility for viewing and configuring variables from
           generalized pmie(1) rules.  The set of generalized rules is read
           in from _rulepath_ , and the output _file_ produced by **pmieconf** is a
           valid input file for **pmie**.
    


## OPTIONS



           The available command line options are:
    
           **-c** When run from automated **pmie** setup processes, this option is
                used to add a specific message and timestamp indicating that
                this is the case.  Unless over-ridden by the **-f** flag, the
                default configuration file to be written or updated when the
                **-c** flag is given and **pmieconf** is run by the root user, is
                _$PCP_VAR_DIR/config/pmie/config.default_.  This is also the
                default configuration file used by the **pmie** service, see
                pmie_daily(1).  This flag is not appropriate when using the
                tool interactively.
    
           **-f** _file_ , **--config** =_file_
                Any rule modifications resulting from **pmieconf** manipulation
                of variable values will be written to _file_.  The default
                value of _file_ is dependent on the user ID - for the root user
                (when the **-c** flag is **not** also given, see above) the file is
                _$PCP_SYSCONF_DIR/pmie/config.default_.  For other users the
                default is _$HOME/.pcp/pmie/config.pmie_.
    
           **-F** , **--force**
                Forces the **pmieconf** output _file_ to be created (or updated),
                after which **pmieconf** immediately exits.
    
           **-r** _rulepath_ , **--rules** =_rulepath_
                Allows the source of generalized **pmie** rules to be changed -
                _rulepath_ is a colon-delimited list of pmieconf(5) rule files
                and/or subdirectories.  The default value for _rulepath_ is
                _$PCP_VAR_DIR/config/pmieconf_.  Use of this option overrides
                the **PMIECONF_PATH** environment variable which has a similar
                function.
    
           **-v** , **--verbose**
                Enable verbose mode.  associated variables will be displayed.
                This is the complete list of variables which affects any
                given rule (by default, global variables are not displayed
                with the rule).
    
           **-?** , **--help**
                Display usage message and exit.
    
           The **pmieconf** _command_ s allow information related to the various
           rules and configurable variables to be displayed or modified.  If
           no **pmieconf** _command_ s are presented on the command line, **pmieconf**
           prompts for _command_ s interactively.
    


## COMMAND LANGUAGE



           The **pmieconf** _command_ language is described here:
    
           **help  [ { . | all | global | <rule> | <group> } [<variable>] ]**
                   Without arguments, the **help** command displays the syntax
                   for all of the available **pmieconf** commands.  With one
                   argument, a description of one or more of the generalized
                   rules is displayed.  With two arguments, a description of
                   a specific variable relating to one or more of the
                   generalized rules is displayed.
    
           **rules  [ enabled | disabled ]**
                   Display the name and short summary for all of the
                   generalized rules found on _rulepath_.  Each of the rule
                   names can be used in place of the keyword **< rule> **in this
                   command syntax description.  The **enabled** and **disabled**
                   options can be used to filter the set of rules displayed
                   to just those which are enabled or disabled respectfully.
    
           **groups** Display the name of all of the rule groups that were found
                   on _rulepath_.  Each of the group names can be used in place
                   of the keyword **< group> **in this command syntax description,
                   which applies the command to all rules within the rule
                   group.
    
           **status** Display status information relating to the current
                   **pmieconf** session, including a list of running **pmie**
                   processes which are currently using _file_.
    
           **enable  { . | all | <rule> | <group> }**
                   Enables the specified rule or group of rules.  An enabled
                   rule is one which will be included in the **pmie**
                   configuration file generated by **pmieconf**.  Any enabled
                   "actions" will be appended to the rule's "predicate", in a
                   manner conforming to the **pmie** syntax ("actions" can be
                   viewed using the **list global** command, described below).
    
           **disable  { . | all | <rule> | <group> }**
                   Disables the specified rule or group of rules.  If the
                   rule was previously enabled, it will be removed from the
                   **pmie** configuration file generated by **pmieconf** , and hence
                   no longer evaluated when **pmie** is restarted (using **pmieconf**
                   does not affect any existing **pmie** processes using _file_).
    
           **list  { . | all | global | <rule> | <group> } [<variable>]**
                   Display the values for a specific rule variable; or for
                   all variables of a rule, a rule group, all rules, or the
                   global variables.
    
           **modify  { . | all | global | <rule> | <group> } <variable> <value>**
                   Enable, disable, or otherwise change the value for one or
                   more rule variables.  This value must be consistent with
                   the type of the variable, which can be inferred from the
                   format of the printed value - e.g. strings will be
                   enclosed in double-quotes, percentages have the ``%''
                   symbol appended, etc.  Note that certain rule variables
                   cannot be modified through **pmieconf** - "predicate" and
                   "help", for example.
    
           **undo  { . | all | global | <rule> | <group> } [<variable>]**
                   Applicable only to a variable whose value has been
                   modified - this _command_ simply reverts to the default
                   value for the given variable.
    
           **quit** Save any changes made to _file_ and then exit **pmieconf**.
    
           **abort** Exit **pmieconf** immediately without saving any changes to
                   _file_.
    
           Each of the commands above can be shortened by simply using the
           first character of the command name, and also ``?'' for help.
    
           Use of the **all** keyword causes the command to be applied to all of
           the rules.  The **global** keyword refers to those variables which are
           applied to every rule.  Such variables can be changed either
           globally or locally, for example:
    
             pmieconf> modify global delta "5 minutes"
             pmieconf> modify memory delta "1 minute"
    
           causes all rules to now be evaluated once every five minutes,
           except for rules in the "memory" group which are to be evaluated
           once per minute.
    
           The ``.'' character is special to **pmieconf** - it refers to the last
           successfully used value of **all** , **global** , **< rule> **or **< group>**.
    


## EXAMPLES



           Specify that all of the rules in the "memory" group should be
           evaluated:
    
             pmieconf> modify memory enabled yes
    
           Change your mind, and revert to using only the "memory" rules
           which were enabled by default:
    
             pmieconf> undo memory enabled
    
           Specify that notification of rules which evaluate to true should
           be sent to **syslogd**(1):
    
             pmieconf> modify global syslog_action yes
    
           Specify that rules in the "per_cpu" group should use a different
           holdoff value to other rules:
    
             pmieconf> help global holdoff
               rule: global  [generic parameters applied to all rules]
                var: holdoff
               help: Once the predicate is true and the action is executed,
                  this variable allows suppression of further action
                  execution until the specified interval has elapsed.
                  A value of zero enables execution of the action if
                  the rule predicate is true at the next sample. Default
                  units are seconds and common units are "second", "sec",
                  "minute", "min" and "hour".
    
             pmieconf> modify per_cpu holdoff "1 hour"
    
           Lower the threshold associated with a particular variable for a
           specified rule:
    
             pmieconf> l cpu.syscall predicate
               rule: cpu.syscall  [High aggregate system call rate]
                 predicate =
                      some_host (
                       ( kernel.all.syscall $hosts$ )
                         > $threshold$ count/sec * hinv.ncpu $hosts$
                      )
    
             pmieconf> m . threshold 7000
    
             pmieconf> l . threshold
               rule: cpu.syscall  [High aggregate system call rate]
                    threshold = 7000
    


## FILES



           _$PCP_VAR_DIR/config/pmieconf/*/*_
                generalized system resource monitoring rules
    
           _$PCP_SYSCONF_DIR/pmie/config.pmie_
                default super-user settings for system resource monitoring
                rules
    
           _$HOME/.pcp/pmie/config.pmie_
                default user settings for system resource monitoring rules
    


## ENVIRONMENT



           The environment variable **PMIECONF_PATH** has a similar function to
           the **-r** option described above, and if set will be used provided no
           **-r** option is presented.
    


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


* * *