Forge Home


Manages Operating System Services


233,861 latest version

2.6 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 4.0.1 (latest)
  • 4.0.0
  • 3.2.0
  • 3.1.5
  • 3.1.4
  • 3.1.3
released Apr 20th 2018
This version is compatible with:
  • Puppet Enterprise 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.4.x
  • Puppet >= 4.9.0

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'choria-mcollective_agent_service', '4.0.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add choria-mcollective_agent_service
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install choria-mcollective_agent_service --version 4.0.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



choria/mcollective_agent_service — version 4.0.1 Apr 20th 2018

Choria Service Agent

The service agent that lets you stop, start, restart and query the statuses of services on your operating system.

This agent can be extended to support different Service managers, by default it uses Puppet. See the section later in this document about extendibility.


This agent provides the following actions, for details about each please run mco plugin doc agent/service

  • restart - Restart a service
  • start - Start a service
  • status - Gets the status of a service
  • stop - Stop a service


This agent is installed by default as part of the Choria Orchestrator.


There is one plugin configuration setting for the service agent.

  • provider - The Util class that implements the start, stop, restart and status behavior. Defaults to 'puppet'

General provider configuration options can then also be set in the config file.

  provider: puppet
  puppet.hasstatus: true
  puppet.hasrestart: true


By default the Action Policy system is configured to only allow status action for all users. This is a read only action and does not expose secrets.

Follow the Choria documentation to configure your own policies either site wide or per agent.

If you do configure any Policies specific to this module these defaults will be overriden when done using Hiera.

An example policy can be seen here:

  - action: "allow"
    callers: "choria=manager.mcollective"
    actions: "*"
    facts: "*"
    classes: "*"


% mco rpc service status service=httpd -W /dev_server/
Determining the amount of hosts matching filter for 2 seconds .... 4

 * [ ============================================================> ] 4 / 4

Summary of Service Status:

   running = 3
   stopped = 1

Finished processing 4 / 4 hosts in 241.49 ms
% mco service puppet stop
Do you really want to operate on services unfiltered? (y/n): y

 * [ ============================================================> ] 4 / 4

Summary of Service Status:

   stopped = 4

Finished processing 4 / 4 hosts in 909.01 ms

Data Plugin

The Service agent also supplies a data plugin which uses the Service agent to check the current status of a service. The data plugin will return 'running' or 'stopped' and can be used during discovery or any other place where the MCollective discovery language is used.

mco rpc rpcutil ping -S "service('myservice').status=running"


The Service agent also supplies a validator plugin that will validate if a given string is a valid service name.

validate :service, :service_name


The default service agent achieves platform portability by using the Puppet provider system to support service managers on all platforms that Puppet supports.

If however you are not a Puppet user or simply want to implement some new method of service management you can do so by providing your own backend provider for this agent.

A service provider that uses the service system command has also been contributed; it can be configured to work with any command that responds to mycommand myservice start/stop/restart/status.

The logic for the Puppet version of this agent is implemented in Util::Service::PuppetService, you can create a custom service implementation that overrides #start, #stop, #restart, and #status.

To provide compatibility with the service data plugin #status should return 'stopped' if the service is stopped, and 'running' if the service is running.

This agent defaults to Util::Service::PuppetService but if you have your own you can configure it in the config file using:

  provider: puppet