The mco command

All MCollective actions are invoked with the mco executable. The mco command
always requires a subcommand to invoke actions.

Important: For security, the mco command relies on a config file (/var/lib/peadmin/.mcollective) which is only
readable by the peadmin user. PE
automatically configures and manages this file, so do not modify it.

mco
Subcommands

The mco command has
several subcommands, and it's possible to add more --- run mco help for a list of all available
subcommands. The following default subcommands are available:

main

Command

Use

rpc

This is the general purpose
client, which can invoke actions from any agent plugin.

special purpose

Command

Use

puppet

These
subcommands only invoke certain kinds of actions, but have some extra
UI enhancements to make them easier to use than the equivalent mco rpc command.

package

service

Help and support subcommands

Command

Use

help

Displays help for
subcommands.

plugin

The mco plugin doc command can
display help for agent plugins.

completion

A helper for shell
completion systems.

Inventory and reporting subcommands

Command

Use

ping

Pings all matching nodes and
reports on response times

facts

Displays a summary of values
for a single fact across all systems

inventory

General reporting tool for
nodes, collectives and subcollectives

find

Like ping, but doesn't
report response times

Getting help on the command line

You can get information about subcommands, actions, and other plugins on the command line.

Subcommand Help

Use one of the following commands to get help for a specific subcommand:

$ mco help <SUBCOMMAND>
$ mco <SUBCOMMAND> --help

List of plugins

To get a list of the available plugins, which includes agent plugins, data query plugins, discovery methods, and validator plugins, run mco plugin doc.

Agent plugin help

Related actions are bundled together in agent plugins. For example, Puppet-related actions are all in the puppet plugin.

To get detailed info on a given plugin's actions and their required inputs, run:

$ mco plugin doc <PLUGIN>

If there is also a data plugin with the same name, you may need to prepend agent/ to the plugin name to disambiguate:

$ mco plugin doc agent/<PLUGIN>

Invoking actions

MCollective actions are invoked with either the general purpose rpc subcommand or one of the special-purpose subcommands. Note that unless you specify a filter, commands will be run on every server in your Puppet Enterprise deployment; make sure you know what will happen before confirming any potentially disruptive commands.

The rpc subcommand

The most useful subcommand is mco rpc. This is the general purpose client, which can invoke actions from any agent plugin. See the list of built-in actions for more information about agent plugins.

Example:

$ mco rpc service restart service=httpd

The general form of an mco rpc command is:

$ mco rpc <AGENT PLUGIN> <ACTION> <INPUT>=<VALUE>

For a list of available agent plugins, actions, and their required inputs, see the list of built-in actions actions or the information on getting help.

Special-purpose subcommands

Although mco rpc can invoke any action, sometimes a special-purpose application can provide a more convenient interface.

Example:

$ mco puppet runall 5

The puppet subcommand's special runall action is able to run many nodes without exceeding a certain load of concurrent runs. It does this by repeatedly invoking the puppet agent's status action, and only sending a runonce action to the next node if there's enough room in the concurrency limit.

This uses the same actions that the mco rpc command can invoke, but since rpc doesn't know that the output of the status action is relevant to the timing of the runonce action, it can't provide that improved UI.

Each special-purpose subcommand (puppet, service, and package) has its own CLI syntax. For example, mco service puts the name of the service before the action, to mimic the format of the more common platform-specific service commands:

Each type of filter lets you specify a type of metadata and a desired value. The action will only run on nodes where that data has that desired value.

Any number of fact, class, and agent filters can also be combined in a single command; this will make it so nodes must match every filter to run the action.

Matching strings and regular expressions

Filter values are usually simple strings. These must match exactly and are case-sensitive.

Most filters can also accept regular expressions as their values; these are surrounded by forward slashes, and are interpreted as standard Ruby regular expressions. (You can even turn on various options for a subpattern, such as case insensitivity --- -F "osfamily=/(?i:redhat)/".) Unlike plain strings, they accept partial matches.

Filtering by identity

A node's "identity" is the same as its certname, as specified during installation. Identities will almost always be unique per node.

$ mco puppet runonce -I web3balancer.example.com

You can use the -I or --with-identity option multiple times to create a filter that matches multiple specific nodes.

You cannot combine the identity filter with other filter types.

The identity filter accepts regular expressions.

Filtering by fact, class, and agent

Facts are the standard
Puppet facts, which are available in your
Puppet manifests. A list of the core facts is available here. Use the -F or --with-fact option with a fact=value pair to filter on facts.

Classes are the
Puppet classes that are assigned to a node. This includes classes assigned in the console, assigned via
Hiera, declared in site.pp, or declared indirectly by another class. Use the -C or --with-class option with a class name to filter on classes.

Agents are
MCollective agent plugins.
PE's default plugins are available on every node, so filtering by agent makes more sense if you are distributing custom plugins to only a subset of your nodes. For example, if you made an emergency change to a custom plugin that you distribute with
Puppet, you could filter by agent to trigger an immediate run on all affected systems. (mco puppet runall 5 -A my_agent) Use the -A or --with-agent option to filter on agents.

Since mixing classes and facts is so common, you can also use the -W or --with option to supply a mixture of class names and fact=value pairs.

Compound "select" filters

The -S or --select option accepts arbitrarily complex filters. Like -W, it can accept a mixture of class names and fact=value pairs, but it has two extra tricks:

Boolean logic

The -W filter always combines facts and classes with "and" logic --- nodes must match all of the criteria to match the filter.

$ mco service httpd restart -S "((customer=acme and osfamily=RedHat) or domain=acme.com) and /apache/"

Data plugins

In addition, the -S filter lets you use data plugin queries as an additional kind of metadata.

Data plugins can be tricky, but are very powerful. To use them effectively, you must:

Check the list of data plugins with mco plugin doc.

Read the help for the data plugin you want to use, with mco plugin doc data/<NAME>. Note any required input and the available outputs.

Use the rpcutil plugin's get_data action on a single node to check the format of the output you're interested in. This action requires source (the plugin name) and query (the input) arguments:

$ mco rpc rpcutil get_data source="fstat" query="/etc/hosts" -I web01

This will show all of the outputs for that plugin and input on that node.

Construct a query fragment of the format <PLUGIN>('<INPUT>').<OUTPUT>=<VALUE> --- note the parentheses, the fact that the input must be in quotes, the .output notation, and the equals sign. Make sure the value you're searching for matches the expected format, which you saw when you did your test query.