Use MCollective to clean the state of your Puppet agents

Jesse Reynolds



4,594 latest version

4.1 quality score

Version information

  • 1.0.0 (latest)
  • 0.1.0
released Jun 21st 2017

Start using this module


jesse/puppet_agent_cleanser — version 1.0.0 Jun 21st 2017


Table of Contents

  1. Description
  2. Usage
  3. Limitations
  4. Development


This Puppet module installs an MCollective application and agent for cleaning up the state of your running Puppet agents should they become stuck for whatever reason (eg a rogue firewall stole your TCP state and left your Puppet agents with half-open connections to the master.)


By default, including the puppet_agent_cleanser class will install both the MCollective Agent and Application. If you want to be more selective you can disable one or other, eg:

class { 'puppet_agent_cleanser':
  include_app   => false,
  include_agent => true,


Obtaining status of one (or more) machines: mco puppet_agent_cleanser status

If number of agent processes is more than 1 for an extended period then it's likely the forked child process of the agent has hung, as seen below.


$ mco puppet_agent_cleanser status -I foo.example

 * [ ============================================================> ] 1 / 1

   Puppet Agent Status: 2 process.

Finished processing 1 / 1 hosts in 1087.47 ms

We can now target this machine to have its Puppet agent cleanly restarted (including killing of any stuck child processes and deletion of the agent catalog run lockfile) by running mco puppet_agent_cleanser cleanse


$ mco puppet_agent_cleanser cleanse -I foo.example

 * [ ============================================================> ] 1 / 1

   Cleanse result: success

Finished processing 1 / 1 hosts in 19230.85 ms


This has been developed with Linux agents in mind. It should work on any UNIX type OS but has only been tested on RHEL 6 to date. It will need a bit of work to get working on Windows due to pathing assumptions.


Pull requests welcome! Raise an issue if you want to discuss a possible feature addition, report a bug, etc.