- Copying Plugins Into the Libdir
- Packaging Custom Plugins
- Verifying Installed Agent Plugins
Pre-built packages are no longer provided in the Puppet Labs apt and yum repos. Installation via Puppet modules is preferred, and can be facilitated by the Choria project. Puppet Enterprise comes with a predefined set of plugins.
Not all plugins can be installed with those methods, so alternatively you can:
You may also want to:
About Plugins / Available Plugin Types
|agent||servers, clients (DDL only)||Executing actions|
|application||clients||CLI subcommands (for sending requests, etc.)|
|connector||servers, clients||Interfacing with middleware|
|data||servers, clients (DDL only)||Enabling new kinds of metadata for filtering|
|discovery||clients||Acquiring a list of nodes that match a filter|
|facts||servers||Enabling fact metadata for filtering|
|pluginpackager||clients||Building OS-appropriate packages to install other plugins|
|registration||servers||Sending heartbeat and metadata to some form of inventory database|
|security||servers, clients||Serializing and validating messages|
|util||servers, clients||Various, usually supporting other plugins; includes authorization plugins|
|validator||servers, clients||Validating input formats before sending a request|
This may seem like a lot to manage, but the general experience is:
- Most users write custom agent plugins.
- Validator and aggregate plugins can be useful when writing advanced agents.
- Many users write some application plugins, but most agents don’t need anything beyond the built-in
- Custom discovery and data plugins can useful if you need faster or more versatile discovery, but aren’t necessary if the existing discovery features suit you.
- It’s rare to write or install custom plugins of the other types.
Copying Plugins Into the Libdir
For older agent plugins, certain non-agent plugins (such as authorization), and most custom plugins, you will need to install by copying files directly into MCollective’s
About the Libdir
The default libdir created by the MCollective install process varies per platform:
The libdir is arranged like a standard Ruby lib directory: It always contains a single directory called
mcollective, which contains a directory for each type of plugin (see above); each of these directories contains any number of
.ddl (and sometimes
In the general case, this means plugin files should be named
util directory may include some extra directory levels.
As an example, here are the platform-appropriate destinations for two of the files installed by the
- On Windows systems:
- On other systems:
mcollectivedirectory goes inside the libdir, whatever the libdir’s path is. In the Red Hat case, this means the complete path contains the string
mcollective/mcollective; be careful not to accidentally skip the second
Copying From Source
Most public MCollective plugins are developed and published in a source repository (e.g. on GitHub) that mimics the structure of the
<LIBDIR>/mcollective directory — that is, the repo will have an
agent directory, an
application directory, etc. You can ignore any Rakefiles, READMEs, or
If you come across a repository that has
lib at the top level you
will need to treat lib/mcollective as the repository root and then
continue with the following instructions.
Note: Servers and clients will not need every file for a given plugin set — you can consult the plugin types table above to see which parts should go where.
Alternately, you can just copy everything in the plugin’s repo to every client and server — nothing bad will happen from installing unused components.
- Copy every file in the plugin source (or just the server-appropriate files) to the corresponding location in the libdir of each server node that should have it. E.g.
agent/package.rbshould be copied to
- Since this must happen across a large number of servers, you should generally use Puppet or other configuration management to copy the files.
- Restart the
mcollectiveserver daemon on every server.
- Copy every file in the plugin source (or just the client-appropriate files) to the corresponding location in each client system’s libdir.
- Since client systems are often admin or developer workstations, this may or may not be automatable; at the least, you should maintain a list of which plugins are in use at your site, so that your admins can keep their clients up to date.
- Optionally, verify the installation on some proportion of your clients and servers.
To demonstrate, this is what you would do to install the puppet agent plugin on a collection of Red Hat-like servers and clients.
The repository for the puppet plugin set is laid out as follows:
├── CHANGELOG.md ├── README.md ├── Rakefile ├── agent │ ├── puppet.ddl │ └── puppet.rb ├── aggregate │ ├── boolean_summary.ddl │ └── boolean_summary.rb ├── application │ └── puppet.rb ├── data │ ├── puppet_data.ddl │ ├── puppet_data.rb │ ├── resource_data.ddl │ └── resource_data.rb ├── spec │ ├── agent │ │ └── puppet_agent_spec.rb │ ├── aggregate │ │ └── boolean_summary_spec.rb │ ├── application │ │ └── puppet_spec.rb │ ├── data │ │ ├── puppet_data_spec.rb │ │ └── resource_data_spec.rb │ ├── fixtures │ │ └── last_run_summary.yaml │ ├── spec.opts │ ├── spec_helper.rb │ ├── util │ │ ├── puppet_agent_mgr │ │ │ └── common_spec.rb │ │ ├── puppet_agent_mgr_spec.rb │ │ ├── puppetrunner_spec.rb │ │ ├── v2 │ │ │ ├── manager_spec.rb │ │ │ └── unix_spec.rb │ │ └── v3 │ │ ├── manager_spec.rb │ │ └── unix_spec.rb │ └── validator │ ├── puppet_resource_validator_spec.rb │ ├── puppet_server_address_validator_spec.rb │ ├── puppet_tags_validator_spec.rb │ └── puppet_variable_validator_spec.rb ├── util │ ├── puppet_agent_mgr │ │ ├── common.rb │ │ ├── v2 │ │ │ ├── manager.rb │ │ │ ├── unix.rb │ │ │ └── windows.rb │ │ └── v3 │ │ ├── manager.rb │ │ ├── unix.rb │ │ └── windows.rb │ ├── puppet_agent_mgr.rb │ └── puppetrunner.rb └── validator ├── puppet_resource_validator.ddl ├── puppet_resource_validator.rb ├── puppet_server_address_validator.ddl ├── puppet_server_address_validator.rb ├── puppet_tags_validator.ddl ├── puppet_tags_validator.rb ├── puppet_variable_validator.ddl └── puppet_variable_validator.rb
On Red Hat-like OSes, you would install these files in the following locations:
/opt/puppetlabs/mcollective/plugins/mcollective/agent/puppet.ddl /opt/puppetlabs/mcollective/plugins/mcollective/agent/puppet.rb /opt/puppetlabs/mcollective/plugins/mcollective/data/puppet_data.ddl /opt/puppetlabs/mcollective/plugins/mcollective/data/puppet_data.rb /opt/puppetlabs/mcollective/plugins/mcollective/data/resource_data.ddl /opt/puppetlabs/mcollective/plugins/mcollective/data/resource_data.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/common.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v2/manager.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v2/unix.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v2/windows.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v3/manager.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v3/unix.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v3/windows.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppetrunner.rb /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_resource_validator.ddl /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_resource_validator.rb /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_server_address_validator.ddl /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_server_address_validator.rb /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_tags_validator.ddl /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_tags_validator.rb /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_variable_validator.ddl /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_variable_validator.rb
/opt/puppetlabs/mcollective/plugins/mcollective/agent/puppet.ddl /opt/puppetlabs/mcollective/plugins/mcollective/aggregate/boolean_summary.ddl /opt/puppetlabs/mcollective/plugins/mcollective/aggregate/boolean_summary.rb /opt/puppetlabs/mcollective/plugins/mcollective/application/puppet.rb /opt/puppetlabs/mcollective/plugins/mcollective/data/puppet_data.ddl /opt/puppetlabs/mcollective/plugins/mcollective/data/resource_data.ddl /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/common.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v2/manager.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v2/unix.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v2/windows.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v3/manager.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v3/unix.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr/v3/windows.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppet_agent_mgr.rb /opt/puppetlabs/mcollective/plugins/mcollective/util/puppetrunner.rb /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_resource_validator.ddl /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_resource_validator.rb /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_server_address_validator.ddl /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_server_address_validator.rb /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_tags_validator.ddl /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_tags_validator.rb /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_variable_validator.ddl /opt/puppetlabs/mcollective/plugins/mcollective/validator/puppet_variable_validator.rb
Packaging Custom Plugins
You can use the
mco plugin package command to generate OS-appropriate packages (limited to Red Hat and Debian-like systems) for your own agent plugins.
The Choria project can also be used with
mco plugin package to generate Puppet modules for plugins.
Note that the packaging tool uses each system’s native tools to build packages — it doesn’t necessarily support building, for example, .deb and .rpm packages on a Mac.
Verifying Installed Agent Plugins
To verify that an agent plugin is correctly installed you can do the following. (Verifying other types of plugins can be harder; we suggest looking in the debug logs)
Check List of Agents
mco inventory <NODE NAME> command includes a list of the agents installed on the node:
Check Agent Version Info
You can also use the
agent_inventory action of the
rpcutil agent to see more complete info for each agent:
Check Agent Docs on Client
On the client, if you installed a DDL file, you can look up the help for an agent:
Examine Debug Output in Log File
If you start the server daemon with a
loglevel setting of
debug, the log (usually the file specified by the
logfile setting) should contain a bunch of lines like:
D, [2010-11-30T21:33:33.144290 #5753] DEBUG -- : 5753 pluginmanager.rb:83:in `loadclass': Loading MCollective::Agent::Service from mcollective/agent/service.rb D, [2010-11-30T21:33:33.144786 #5753] DEBUG -- : 5753 pluginmanager.rb:36:in `<<': Registering plugin service_agent with class MCollective::Agent::Service D, [2010-11-30T21:33:33.144928 #5753] DEBUG -- : 5753 stomp.rb:150:in `subscribe': Subscribing to /topic/mcollective.service.command
Check Presence of Agent Across All Nodes
Finally, since agents are a common filter criteria, you can find all nodes that are running your agent: