The server daemon mcollectived can only respond to ping and inventory requests, which isn’t all that useful. It is not inappropriate to consider mcollectived to be a a container for agents. We will install several agent plugins in this chapter to extend and enhance what we can control on the server.

Each agent has a matching client or application which knows how to issue requests specific to that agent. The agent will respond to requests coming from the matching application.

Puppet Labs provides a number of MCollective agents that know how to do common systems management task: query, start, and stop processes; query, install, and remove packages. We’ll start with just the plugins they provide for now.

However, you may have needs which are custom and unique to your environment. MCollective is extensible, and you’ll find many user-provided agents available on the Puppet Forge. You will also find it easy to build your own agents and clients. In those situations you can orchestrate things that the MCollective maintainers never dreamed about. We’re going to show you how to do this in Part III.

On each server in your environment we have installed the mcollectived service. For this daemon to operate correctly it requires two plugins:

These two connectors must be the same throughout your environment. In most situations, the configuration for these plugins will be the same on every server host.

For the baseline setup described in Chapter 2 we used:

If you are using the Puppet Labs repositories as described in Puppet Labs Repository, you can simply install the baseline set of agents as follows:

$ sudo yum install mcollective-filemgr-agent
$ sudo yum install mcollective-nettest-agent
$ sudo yum install mcollective-package-agent
$ sudo yum install mcollective-service-agent

$ sudo apt-get install mcollective-filemgr-agent
$ sudo apt-get install mcollective-nettest-agent
$ sudo apt-get install mcollective-package-agent
$ sudo apt-get install mcollective-service-agent

You’ll need to do this on every server in your environment. On the client nodes you’ll need to install the corresponding client package, for example:

$ sudo yum install mcollective-filemgr-client

For any other operating systems you should install from the operating system repository or from source, as described in the next section.

Installing mcollective plugins from source is actually quite easy, and is exactly the same on every operating system I’ve tested the process on. You’ll need to have git installed and working on your host.

$ git clone git://github.com/puppetlabs/mcollective-filemgr-agent.git
Cloning into 'mcollective-filemgr-agent'...
remote: Reusing existing pack: 49, done.
remote: Total 49 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (49/49), done.
Checking connectivity... done
$ cd mcollective-filemgr-agent
$ mco plugin package .
   This will build agent, client, and common packages for many platforms.

If MCollective does not know how to build packages for your operating system yet, then you’ll need to copy the files into their location by hand, or with a configuration tool.

$ cp agent/package.rb /usr/libexec/mcollective/mcollective/agent/
$ cp agent/package.dll /usr/libexec/mcollective/mcollective/agent/
$ cp application/package.rb /usr/libexec/mcollective/mcollective/application/

$ cp agent/package.rb /usr/share/mcollective/plugins/mcollective/agent/
$ cp agent/package.dll /usr/share/mcollective/plugins/mcollective/agent/
$ cp application/package.rb /usr/share/mcollective/plugins/mcollective/application/

$ cp agent/package.rb /opt/mcollective/plugins/mcollective/agent/
$ cp agent/package.dll /opt/mcollective/plugins/mcollective/agent/
$ cp application/package.rb /opt/mcollective/plugins/mcollective/application/

After you have installed new agents on a server node you tell mcollectived to reload the agents. The simplest method is to restart mcollectived for the agents to be loaded and active.

$ sudo service mcollective restart
Shutting down mcollective:                                 [  OK  ]
Starting mcollective:                                      [  OK  ]

You can also send the daemon a USR1 signal to effect the reload. On many platforms you can do this with pkill. The -x option can be used to ensure you don’t kill any other program with a partial name match.

$ sudo pkill -USR1 -x mcollectived || echo "pkill failed: $?"

Once you have made the changes, you can use the inventory request and read through the output to see if the new agents are available on the node:

$ mco inventory nodename
read down through the output...
Agents:
      discovery       rpcutil
      filemgr         nettest
      package         service

I rather like using awk to remove all other output. Naturally it’s not guaranteed against future changes in the output.

$ mco inventory nodename | awk '/Agents:/','/^$/'

You can also query to get a list of every server which has the agent installed:

$ mco find --with-agent filemgr
geode
heliotrope
sunstone

To interact with these agents we need to have installed the client plugins on any system from which we will be sending requests to these agents, as discussed in Using Client Plugins.

What if you want to disable an agent on a machines? For example, if there was a problem with the agent but you didn’t want to go through uninstalling it yet.

There are two ways to disable an agent. The first option is within the server configuration file:

plugin.plugin_name.activate_agent = false

The other way is to create a configuration file for that particular agent:

$ echo "activate_agent = false" | sudo tee -a /etc/mcollective/plugins.d/plugin_name.cfg

Any time this parameter is changed you’ll need to signal mcollectived to reload as documented in Notify mcollectived.

Client plugins provide an application to issue commands to their respective agents. They are not useful until you install the matching server agent as described in Agent Plugins.

If you are using the Puppet Labs repositories as described in Puppet Labs Repository, you can install a baseline set of safe and well-tested clients like this:

# RedHat, CentOS, Fedora Based Systems
$ sudo yum install mcollective-filemgr-client
$ sudo yum install mcollective-nettest-client
$ sudo yum install mcollective-package-client
$ sudo yum install mcollective-service-client

# Debian or Ubuntu
$ sudo apt-get install mcollective-filemgr-client
$ sudo apt-get install mcollective-nettest-client
$ sudo apt-get install mcollective-package-client
$ sudo apt-get install mcollective-service-client

After you install the client plugins, you can get a list of applications available on a node with the doc command:

$ mco plugin doc
Please specify a plugin. Available plugins are:

Agents:
  filemgr                   File Manager
  nettest                   Agent to do network tests from a mcollective host
  package                   Install and uninstall software packages
...etc

The applications add custom subcommands (called faces) to the mco client, allowing easy access to the commands provided by each client plugin. You can get documentation for how to use the plugin from the help command.

$ mco help package

Install, uninstall, update, purge and perform other actions to packages

Usage: mco package [OPTIONS] [FILTERS] <ACTION> <PACKAGE>
Usage: mco package <PACKAGE> <install|uninstall|purge|update|status>

The ACTION can be one of the following:

    install    - install PACKAGE
    uninstall  - uninstall PACKAGE
    purge      - uninstall PACKAGE and purge related config files
    update     - update PACKAGE
    status     - determine whether PACKAGE is installed and report its version

$ mco package update mcollective -I heliotrope
 * [ ==================================================> ] 1 / 1

Summary of Ensure:
   2.5.0-1.el6 = 1

Finished processing 1 / 1 hosts in 5923.31 ms

You’ll find the help command useful for determining command syntax, but extensive details about inputs and output can only be found in the plugin’s documentation.

$ mco plugin doc agent/package
package
=======

Install and uninstall software packages

      Author: R.I.Pienaar
     Version: 4.2.2
     License: ASL 2.0
     Timeout: 180
   Home Page: https://github.com/puppetlabs/mcollective-package-agent

   Requires MCollective 2.2.1 or newer

ACTIONS:
========
   apt_checkupdates, apt_update, checkupdates, install, purge, status, uninstall, update, yum_checkupdates, yum_clean

   apt_checkupdates action:
   ------------------------
       Check for APT updates

       INPUT:
          This action does not have any inputs

       OUTPUT:
           exitcode:
              Description: The exitcode from the apt command
               Display As: Exit Code
...etc

Before you set out to build your own plugin, you should look around to ensure that nobody hasn’t built it already. There are many benefits to using something which is easy to extend. One of them is that it builds a large community of people who extend the software to meet their own needs. The other is that the community can share the plugins with each other. So before you go off to build a module yourself, you should check to make sure someone hasn’t already made an agent for this.

The first location to look for plugin agents and clients should always be the Puppet Labs Yum or APT repositories. This repo and how to use it is documented in Puppet Labs Repository.

$ yum search --enablerepo=puppetlabs* mcollective # RedHat
$ apt-cache search mcollective                    # Debian

Puppet Labs maintains a wiki page with links to many of the plugins at http://projects.puppetlabs.com/projects/mcollective-plugins/wiki

At the time this book was written the only place where the Author saw significant community MCollective plugin development was on GitHub. GitHub contains hundreds of MCollective plugins that others have already developed. The following query will find most of the plugins available for download: GitHub Search mcollectivel

It is always best if you can build packages of the plugins with the mco plugin package command. Install the -agent packages on servers, and the -client packages on clients. You’ll need to follow the steps outlined in Notify mcollectived so that the server will pick up the new agents.

If you can’t build a package with the plugin, the process for installing plugins from source is documented in Installing from Source.