pmieconf(1) — Linux manual page


PMIECONF(1)              General Commands Manual             PMIECONF(1)

NAME         top

       pmieconf - display and set configurable pmie rule variables

SYNOPSIS         top

       pmieconf [-cFv?]  [-f file] [-r rulepath] [command [args...]]

DESCRIPTION         top

       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         top

       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

       -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 commands allow information related to the various
       rules and configurable variables to be displayed or modified.  If
       no pmieconf commands are presented on the command line, pmieconf
       prompts for commands interactively.


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

       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         top

       Specify that all of the rules in the "memory" group should be

         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         top

            generalized system resource monitoring rules

            default super-user settings for system resource monitoring

            default user settings for system resource monitoring rules

ENVIRONMENT         top

       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.


       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

SEE ALSO         top

       PCPIntro(1), pmie(1), pmie_check(1) and pmieconf(5).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this manual
       page, send it to  This page was obtained from the
       project's upstream Git repository
       ⟨⟩ on 2023-12-22.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-12-16.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot               PCP                       PMIECONF(1)

Pages that refer to this page: pcpintro(1)pmie(1)pmie_check(1)pmieconf(5)