PMIECTL(1)

✨ pmiectl 💅 — the PMIECTL(1) glow-up ✨

okay bestie so this is the General Commands Manual page for pmiectl, and it's a whole vibe. buckle up 🎀

---

✨ SYNOPSIS ✨

pmiectl [-afmNV?]  [-C check_args] [-c class] [-i ident] [-p policy]
command [host ...]

like, that's the whole incantation. type it, slay, move on 🦋

---

🌸 DESCRIPTION 🌸

so pmiectl is the tool you use to manage and control non-primary instances of the Performance Co-Pilot (PCP) inference engine, aka pmie(1). this is highkey the most relevant thing ever if you're running a PCP inference engine “farm” — think a million pmie(1) instances all evaluating rules against performance data collected from pmcd(1) across a whole bunch of remote hosts. it's giving ✨distributed girlbossery✨.

the primary pmie(1) instance is super tightly coupled to the local pmcd(1) process, and because of that it shares the same control infrastructure — namely systemd(1) or the PCP init(1) “rc scripts”. and that's exactly why the primary pmie(1) instance cannot be managed with pmiectl. nope. not it. 🙅‍♀️

for brevity in everything below, the term “instance” means a pmie(1) instance. we're keeping it cute and short, bestie.

okay so every single instance managed by pmiectl, pmie_check(1) and pmie_daily(1) has to follow these rules, no cap:

1. each instance is fetching performance data from a single pmcd(1) (so like, one host), but each pmcd(1) may be providing performance data to zero, one or more pmie(1) processes running on one or more hosts. it's a whole many-to-many situation, very polyamorous of them 💖
2. on the local host, each pmie(1) instance must be specified once in a pmie_check(1) control file, and pmie(1) creates a unique log file, named in the 4th parameter of the associated control file entry (go read the CONFIGURATION section of pmie_check(1), iykyk).
3. each instance belongs to exactly one class, optionally named using a $class=... assignment in the associated control file. the special default class is reserved for all instances that don't have an associated $class=... assignment. and for reporting purposes (peep the summary command below), the primary pmie(1) instance is automatically assigned to the special primary class. periodt.

each time you run pmiectl it manages one or more instances, updating the associated control files and then running pmie_check(1) to actually make the change happen. it's the middle manager of your pmie farm, honestly.

---

the host arguments 🫶

the host arguments are usually just valid host names. but for all commands except create and cond-create (more on those below), the host arguments can also be egrep(1) regular expressions that match the whole of a valid host name — so the pattern actually used is ^host$. literally the whole name has to match, no partials.

for example:

• foo.* — matches all host names beginning with “foo”
• .*foo — matches all host names ending with “foo”
• .*[fF][oO][oO].* — matches all host names containing “foo” in upper, lower or mixed case 🔥

the combo of a class (from the optional -c option, or the default) plus the host arguments to each command is what identifies a target set of instances that the command operation gets applied to. that's the whole targeting system, bestie.

the -i option may be used with the create or cond-create commands to override the instance identity that's specified in the ident section of the class policy file (see the CLASS POLICY FILE section below). and since the identifier must be unique across all instances and all classes, it only makes sense to use this option when there's a single host argument. one host, one ident. that's the rule 💅

---

permissions tea ☕

given the tasks that pmiectl is undertaking, it usually must be run as root — the exceptions being the status command, or when the -N option is specified. so yeah, mostly root energy, but there are escape hatches, don't worry 🌈

---

👑 COMMANDS 👑

command is one of the following, bestie. pick your fighter:

• check — check the status of all currently configured pmie instances and restart any that have failed. if the -m flag is given on systemd(1) platforms, it also migrates matching (and new) processes to the pmie_farm service. it's the wellness check + glow-up combo 💖
• create — create new instances in the class classname (default by default) for the host hosts. the name of the class is used to identify a class policy file (see the CLASS POLICY FILE section below), which provides a template for each new control file, with %h replaced by host and %i replaced by the instance's (unique) identifier — either from the ident section of the class policy file, or from ident given with the -i option.

the -p option may be used to identify a class policy file other than the one found in the standard place, i.e. $PCP_SYSCONF_DIR/pmie/class.d/classname.

at least one host must be specified for the create command. no host, no create. non-negotiable ✨

• cond-create — similar to create, but the instance will only be created if one of the conditions in the create section of the associated class policy file(s) evaluates to true. it's the conditional queen of the command list 👑

if a -c option is specified, then only the class classname will be considered — otherwise all classes will be considered. in that latter case, if none of the conditions in any of the classes evaluates to true, then the special pmfind class is used (this is the “default” class for the cond-create command when all else fails).

if more than one class evaluates to true, then a composite pmie(1) configuration file is created, and the instance is also assigned to the special pmfind class. that composite configuration file may contain a mix of explicit configuration clauses and the more general conditional configuration clauses as understood by the pmieconf(1) tool. it's a whole blended family situation 🦋

• start — start the target set of instances.

if the target set intentionally contains more than one instance, then the -a option should be used (this is designed to reduce the risk of accidentally starting a potentially large number of pmie(1) processes). like, please use -a, bestie, we're not trying to spawn chaos 🙈

if an instance in the target set is already started, no change is made (see the restart command if you want to force new instances to be launched).

• stop — stop the target set of instances.

if the target set intentionally contains more than one instance, then the -a option should be used (this is designed to reduce the risk of accidentally stopping a potentially large number of pmie(1) processes).

if an instance in the target set is already stopped, no change is made but a warning is issued. it's just letting you know, gently 🫶

• restart — stop and then start the target set of instances. the classic off-and-on again, the relationship-crisis special 💀

if the target set intentionally contains more than one instance, then the -a option should be used (this is designed to reduce the risk of accidentally stopping and starting a potentially large number of pmie(1) processes).

if an instance in the target set is already stopped, a warning is issued before the instance is started.

• status — report the status of the target set of instances. and if there's no -c option specified and no host arguments, i.e. the target set is empty, then all instances will be reported. it's the gossip session of commands, it tells you everything ✨
• destroy — destroy the target set of instances. at the end of this operation the associated pmie(1) processes will have been stopped and the relevant control file information removed. it's giving finale. 💅

if the target set intentionally contains more than one instance, then the -a option should be used (this is designed to reduce the risk of accidentally terminating a potentially large number of pmie(1) processes and removing their pmie_check(1) configurations). this one really matters, bestie, please use -a.

the policy file linked to the class of an instance to be destroyed may contain a destroy section that may influence if and how the destroy operation should be performed. this may require a -p option to find the associated class policy file.

the class policy checking can be by-passed using the -f (force) command line option. yes, that's a force flag. yes, that's real power. use it responsibly 🔥

🎀 CLASS POLICY FILE 🎀

ok bestie, so a class policy file is literally just a bunch of sections stacked together, and every section kicks off with a line that is simply the name of the section wrapped up in [ and ]. that's it, that's the whole opener.

Lines that start with a hash (#) are treated as comments and ignored. Blank or empty lines? also ignored, they're just vibing. ✨

The typical location of the policy file for the class foo is $PCP_SYSCONF_DIR/pmie/class.d/foo.

---

🌸 [class] 🌸

The optional class name section names the class. If it's missing, the name of the policy file (stripped of any directory prefix) is used as the name of the class. slay, the filename does the work for you.

🦋 [ident] 🦋

The ident section specifies the template to be used for the instance identifier that gets given to each member of the class. This identifier needs to be unique across all instances and all classes, and it needs to be a valid file name in the local filesystem, so it would normally contain the class name and the macro %h, e.g. foo-%h. The macro is replaced by the host when each instance is created. no cap, uniqueness is not optional here.

💅 [control] 💅

The control section consists of one or more lines of template text that will be used to create the control file for each instance. This must at least include the pmie_check(1) control line to specify how to start the associated pmie(1) process; this line contains fields separated by white space as follows:

1. the hostname, usually the macro %h
2. n to indicate this is a non-primary instance
3. the "socks" flag, typically n
4. the pathname used by pmie(1) for the log file; this needs to be unique and is usually specified using the pmie_check(1) macro PCP_LOG_DIR as the start of the path, followed by pmie, and then the instance's unique directory %i, e.g. PCP_LOG_DIR/pmie/%i/pmie.log
5. additional parameters to pmie(1) which probably include at least a -c option to provide a configuration file that describes which rules should be evaluated for instances of this class, which may be the same for all instances in this class, or it may include the %i macro to use a different configuration file for each instance. Note that if this configuration file does not exist, it will be created using pmieconf(1) the first time pmie_check(1) is run.

Before the control line there should be a line that defines the version of the control line that follows, i.e.

$version=1.1

If this is missing, pmiectl will assume the version is 1.1 and insert the line when the instance is created. so it's got your back, but like, write it anyway bestie.

pmiectl will also add the class name during creation. e.g. $class=foo

Within a control line template, a simple form of parametric substitution is supported. The ENV(spec) macro is replaced by text using environment variables as follows:

• If spec is of the form var then the value of $var from the environment is used. If $var is not defined or has the value of an empty string, this is an error. 😭
• If spec is of the form var:default then if $var from the environment is defined and is not an empty string the value of $var is used, otherwise the value default is used. The substitution is simple, so any whitespace between the : and the ) is included in default, and default cannot contain a ). yeah, it's that literal about it.

As an example

# unset PMPROXY_PORT; PMPROXY_HOST=foobar.com pmiectl create ...

with a policy class control template line that includes

http://ENV(PMPROXY_HOST):ENV(PMPROXY_PORT:44322)

will generate a control line that includes

http://foobar.com:44322

✨ [create] ✨

The create section defines the conditions that must be met before an instance will be created with the cond-create command. The intent is to allow different decisions to be made when a new host running pmcd(1) is discovered, e.g. by pmfind(1).

Each non-blank line in the create section is a condition of the form function(arg), where function is one of the following:

exists

arg is the name of a performance metric and exists evaluates to true if that metric exists in the Performance Metrics Name Space (PMNS) on the remote host.

values

arg is the name of a performance metric in the remote PMNS and values evaluates to true if some instance of that metric has a value on the remote host.

condition

arg is a derived metric expression in the format supported by pmRegisterDerived(3), and condition evaluates to true if the value of that expression on the remote host is greater than zero.

hostname

arg is a regular expression in the style of egrep(1) and hostname evaluates to true if the remote host name matches arg.

🍓 [destroy] 🍓

The destroy section defines the policy to be applied when an instance is destroyed.

The intent is to allow different decisions to be made when discovery service, e.g. pmfind(1), notices that a host associated with an instance is no longer present. But in the current version this is not implemented and the destroy section syntax and semantics is not yet defined. so like... it's giving placeholder energy, don't build your whole life on it.

A sample class policy file is as follows:

# policy file for the foo class
[class]
foo
[ident]
foo-%h

[control]
$version=1.1
%h n n PCP_LOG_DIR/pmie/%i/pmie.log -c foo-metrics.config

[create]
# matches all hosts
hostname(.*)

[destroy]
# still to be defined

---

👑 OPTIONS 👑

The available command line options are:

• -a, --all — Apply action to all matching instances. By default only one instance definition is expected and acted upon.
• -c class, --class=class — Set the name of the class for which pmie(1) instances belong to as class.
• -C check_args, --checkargs=check_args — check_args are additional command line arguments for pmie_check(1) when it is called. This is most useful for options like -V. Multiple -C options may be used and the various check_args options will be accumulated and all passed to pmie_check(1). stacking them? iconic.
• -f, --force — Force action if possible.
• -i ident, --ident=ident — Override instance identifier with ident. This option applies only for the commands create and cond-create.
• -N, --showme — Runs pmiectl in a "show me" or "dry run" mode where the intent of the command is shown, but no changes are made. perfect for the cautious girlies 🫶
• -m, --migrate — When used with the create or check commands on systemd(1) platforms, also migrate new or existing non-primary pmie processes to the pmie_farm service. This is normally done automatically by the pmie_farm_check service, which is timer driven (so there may be a few minutes delay before automatic migration is initiated).
• -p policy, --policy=policy — Use policy as the class policy file. Defaults to $PCP_SYSCONF_DIR/pmie/class.d/<class>.
• -V, --verbose — Enable verbose mode. Using this option twice increases verbosity. Verbose output is written to stderr.
• -?, --help — Display usage message and exit.

---

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

---

💖 SEE ALSO 💖

egrep(1), init(1), PCPIntro(1), pmcd(1), pmieconf(1), pmie(1), pmie_check(1), pmie_daily(1), systemd(1), PMAPI(3), pmDerivedRegister(3) and pcp.conf(5).

---

and that's the whole page bestie 💜 this one ships from Performance Co-Pilot (PCP) as PMIECTL(1) — go forth and manage those pmie instances like the main character you are. periodt. ✨👑