1 files changed, 326 insertions, 0 deletions
diff --git a/man/man1/pmieconf.1 b/man/man1/pmieconf.1
new file mode 100644
index 0000000..0b65d0a
--- /dev/null
+++ b/man/man1/pmieconf.1
@@ -0,0 +1,326 @@
+'\"macro stdmacro
+.ie \(.g \{\
+.\" ... groff (hack for khelpcenter, man2html, etc.)
+.TH PMIECONF 1 "PCP" "Performance Co-Pilot"
+\}
+.el \{\
+.if \nX=0 .ds x} PMIECONF 1 "PCP" "Performance Co-Pilot"
+.if \nX=1 .ds x} PMIECONF 1 "Performance Co-Pilot"
+.if \nX=2 .ds x} PMIECONF 1 "" "\&"
+.if \nX=3 .ds x} PMIECONF "" "" "\&"
+.TH \*(x}
+.rr X
+\}
+.SH NAME
+\f3pmieconf\f1 \- display and set configurable pmie rule variables
+.SH SYNOPSIS
+\f3pmieconf\f1
+[\f3\-cFv\f1]
+[\f3\-f\f1 \f2file\f1]
+[\f3\-r\f1 \f2rulepath\f1]
+[\f2command\f1 [\f2args...\f1]]
+.SH DESCRIPTION
+.B pmieconf
+is a utility for viewing and configuring variables from generalized
+.BR pmie (1)
+rules.
+The set of generalized rules is read in from
+.IR rulepath ,
+and the output
+.I file
+produced by
+.B pmieconf
+is a valid input file for
+.BR pmie .
+.PP
+A brief description of the
+.B pmieconf
+command line options follows:
+.TP 8
+\f3-c\f1
+When run from automated
+.B pmie
+setup processes, this option is used to add a specific message and
+timestamp indicating that this is the case.
+It is not appropriate when using the tool interactively.
+.TP 8
+\f3\-f\f1 \f2file\f1 
+Any rule modifications resulting from
+.B pmieconf
+manipulation of variable values will be written to \f2file\f1.
+The default value of \f2file\f1 is dependent on the user ID \- for the root
+user, the file
+.I $PCP_VAR_DIR/config/pmieconf/config.pmie
+is used, for other users the default is
+.IR $HOME/.pcp/pmie/config.pmie .
+.TP 8
+\f3\-F\f1
+Forces the
+.B pmieconf
+output
+.I file
+to be created (or updated), after which
+.B pmieconf
+immediately exits.
+.TP 8
+\f3\-r\f1 \f2rulepath\f1
+Allows the source of generalized
+.B pmie
+rules to be changed \- \f2rulepath\f1 is a colon-delimited list of
+.BR pmieconf (5)
+rule files and/or subdirectories.
+The default value for
+.I rulepath
+is
+.IR $PCP_VAR_DIR/config/pmieconf .
+Use of this option overrides the
+.B PMIECONF_PATH
+environment variable which has a similar function.
+.TP 8
+\f3\-v\f1
+Verbose mode.  Additional information associated with each rule and its
+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).
+.PP
+The
+.B pmieconf
+.IR command s
+allow information related to the various rules and configurable variables
+to be displayed or modified.
+If no
+.B pmieconf
+.IR command s
+are presented on the command line,
+.B pmieconf
+prompts for
+.IR command s
+interactively.
+.PP
+The
+.B pmieconf
+.I command
+language is described here:
+.TP 8
+.B "help  [ { . | all | global | <rule> | <group> } [<variable>] ]"
+Without arguments, the
+.B help
+command displays the syntax for all of the available
+.B 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.
+.TP 8
+.B "rules  [ enabled | disabled ]"
+Display the name and short summary for all of the generalized rules found on
+.IR rulepath .
+Each of the rule names can be used in place of the keyword
+.B <rule>
+in this command syntax description.
+The
+.B enabled
+and
+.B disabled
+options can be used to filter the set of rules displayed to just those which
+are enabled or disabled respectfully.
+.TP 8
+.B "groups"
+Display the name of all of the rule groups that were found on
+.IR rulepath .
+Each of the group names can be used in place of the keyword
+.B <group>
+in this command syntax description, which applies the command to all rules
+within the rule group.
+.TP 8
+.B "status"
+Display status information relating to the current
+.B pmieconf
+session, including a list of running
+.B pmie
+processes which are currently using
+.IR file .
+.TP 8
+.B "enable  { . | all | <rule> | <group> }"
+Enables the specified rule or group of rules.  An enabled rule is one which
+will be included in the
+.B pmie
+configuration file generated by
+.BR pmieconf .
+Any enabled "actions" will be appended to the rule's "predicate", in a
+manner conforming to the
+.B pmie
+syntax ("actions" can be viewed using the
+.B "list global"
+command, described below).
+.TP 8
+.B "disable  { . | all | <rule> | <group> }"
+Disables the specified rule or group of rules.  If the rule was previously
+enabled, it will be removed from the
+.B pmie
+configuration file generated by
+.BR pmieconf ,
+and hence no longer evaluated when
+.B pmie
+is restarted (using
+.B pmieconf
+does not affect any existing
+.B pmie
+processes using
+.IR file ).
+.TP 8
+.B "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.
+.TP 8
+.B "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
+.B pmieconf
+\- "predicate" and "help", for example.
+.TP 8
+.B "undo  { . | all | global | <rule> | <group> } [<variable>]"
+Applicable only to a variable whose value has been modified - this
+.I command
+simply reverts to the default value for the given variable.
+.TP 8
+.B "quit"
+Save any changes made to
+.I file
+and then exit
+.BR pmieconf .
+.TP 8
+.B "abort"
+Exit
+.B pmieconf
+immediately without saving any changes to
+.IR file .
+.PP
+Each of the commands above can be shortened by simply using the first
+character of the command name, and also ``?'' for help.
+.PP
+Use of the
+.B all
+keyword
+causes the command to be applied to all of the rules.
+The
+.B global
+keyword refers to those variables which are applied to every rule.
+Such variables can be changed either globally or locally, for example:
+.sp
+.nf
+  pmieconf> modify global delta "5 minutes"
+  pmieconf> modify memory delta "1 minute"
+.fi
+.sp
+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.
+.PP
+The ``.'' character is special to
+.B pmieconf
+\- it refers to the last successfully used value of
+.BR all ,
+.BR global ,
+.B <rule>
+or
+.BR <group> .
+.SH EXAMPLES
+Specify that all of the rules in the "memory" group should be evaluated:
+.sp
+.nf
+  pmieconf> modify memory enabled yes
+.fi
+.sp
+Change your mind, and revert to using only the "memory" rules which were
+enabled by default:
+.sp
+.nf
+  pmieconf> undo memory enabled
+.fi
+.sp
+Specify that notification of rules which evaluate to true should be sent to
+.BR syslogd (1):
+.sp
+.nf
+  pmieconf> modify global syslog_action yes
+.fi
+.sp
+Specify that rules in the "per_cpu" group should use a different holdoff value
+to other rules:
+.sp
+.nf
+  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"
+.fi
+.sp
+Lower the threshold associated with a particular variable for a specified
+rule:
+.sp
+.nf
+  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
+.fi
+.sp
+.SH ENVIRONMENT
+The environment variable
+.B PMIECONF_PATH
+has a similar function to the 
+.B \-r
+option described above, and if set will be used provided no
+.B \-r
+option is presented.
+.SH FILES
+.PD 0
+.TP 10
+.IR $PCP_VAR_DIR/config/pmieconf/ */*
+generalized system resource monitoring rules
+.TP 10
+.I $PCP_VAR_DIR/config/pmieconf/config.pmie
+default super-user settings for system resource monitoring rules
+.TP 10
+.I $HOME/.pcp/pmie/config.pmie
+default user settings for system resource monitoring rules
+.PD
+.SH "PCP ENVIRONMENT"
+Environment variables with the prefix
+.B PCP_
+are used to parameterize the file and directory names
+used by PCP.
+On each installation, the file
+.I /etc/pcp.conf
+contains the local values for these variables.
+The
+.B $PCP_CONF
+variable may be used to specify an alternative
+configuration file,
+as described in
+.BR pcp.conf (5).
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR pmie (1),
+.BR pmie_check (1)
+and
+.BR pmieconf (5).