- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with mcollective
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
The mcollective module installs, configures, and manages the mcollective agents, clients, and middleware of an mcollective cluster.
The mcollective module handles installing and configuring mcollective across a range of operating systems and distributions. Where possible we follow the standards laid down by the MCollective Standard Deployment guide.
A quick aside, mcollective's terminology differs a little from what you might be used to in puppet. There are 3 main components, the client (the mco commands you run to control your servers), the server (a daemon that runs on all of your managed nodes and executes the commands), and the middleware (a message broker the servers and agent connect to).
If it helps to map these to puppet concepts you loosely have:
- Middleware -> Puppet Master
- MCollective Server -> Puppet Agent
- MCollective Client -> no direct equivalent
On a server
- mcollective package
- mcollective server configuration file
- mcollective service
On a client
- mcollective-client package
- mcollective client configuration file
- optionally user configuration files (~/.mcollective and ~/.mcollective.d)
On a middleware host
- broker installation
- broker configuration
Your main entrypoint to the mcollective module is the mcollective class, so assuming you have your middleware configured on a node this is all you need to add a server to mcollective.
class { '::mcollective':
middleware_hosts => [ 'broker1.example.com' ],
}
Your primary interaction with the mcollective module will be though the main
mcollective class, with secondary configuration managed by the defined types
mcollective::user
, mcollective::plugin
, mcollective::actionpolicy
, and
mcollective::actionpolicy::rule
.
node 'broker1.example.com' {
class { '::mcollective':
middleware => true,
middleware_hosts => [ 'broker1.example.com' ],
}
}
node 'server1.example.com' {
class { '::mcollective':
middleware_hosts => [ 'broker1.example.com' ],
}
}
node 'control1.example.com' {
class { '::mcollective':
client => true,
middleware_hosts => [ 'broker1.example.com' ],
}
}
This default install will be using no TLS, a set of well-known usernames and passwords, and the psk securityprovider. This is against the recommendataion of the standard deploy guide but does save you from having to deal with ssl certificates to begin with.
Gather some credentials for the server and users. You'll need the ca certificate, and a keypair for the server to use, and a keypair for each user to allow.
See the standard deploy guide for more information about how to generate these.
node 'broker1.example.com' {
class { '::mcollective':
middleware => true,
middleware_hosts => [ 'broker1.example.com' ],
middleware_ssl => true,
securityprovider => 'ssl',
ssl_client_certs => 'puppet:///modules/site_mcollective/client_certs',
ssl_ca_cert => 'puppet:///modules/site_mcollective/certs/ca.pem',
ssl_server_public => 'puppet:///modules/site_mcollective/certs/server.pem',
ssl_server_private => 'puppet:///modules/site_mcollective/private_keys/server.pem',
}
}
node 'server1.example.com' {
class { '::mcollective':
middleware_hosts => [ 'broker1.example.com' ],
middleware_ssl => true,
securityprovider => 'ssl',
ssl_client_certs => 'puppet:///modules/site_mcollective/client_certs',
ssl_ca_cert => 'puppet:///modules/site_mcollective/certs/ca.pem',
ssl_server_public => 'puppet:///modules/site_mcollective/certs/server.pem',
ssl_server_private => 'puppet:///modules/site_mcollective/private_keys/server.pem',
}
mcollective::actionpolicy { 'nrpe':
default => 'deny',
}
mcollective::actionpolicy::rule { 'vagrant user can use nrpe agent':
agent => 'nrpe',
callerid => 'cert=vagrant',
}
}
node 'control.example.com' {
class { '::mcollective':
client => true,
middleware_hosts => [ 'broker1.example.com' ],
middleware_ssl => true,
securityprovider => 'ssl',
ssl_client_certs => 'puppet:///modules/site_mcollective/client_certs',
ssl_ca_cert => 'puppet:///modules/site_mcollective/certs/ca.pem',
ssl_server_public => 'puppet:///modules/site_mcollective/certs/server.pem',
ssl_server_private => 'puppet:///modules/site_mcollective/private_keys/server.pem',
}
mcollective::user { 'vagrant':
certificate => 'puppet:///modules/site_mcollective/client_certs/vagrant.pem',
private_key => 'puppet:///modules/site_mcollective/private_keys/vagrant.pem',
}
}
The mcollective
class is the main entry point to the module. From here you
can configure the behaviour of your mcollective install of server, client, and
middleware.
The following parameters are available to the mcollective class:
Boolean: defaults to true. Whether to install the mcollective server on this node.
Boolean: defaults to false. Whether to install the mcollective client application on this node.
Boolean: defaults to false. Whether to install middleware that matches
$mcollective::connector
on this node.
String: defaults to 'mcollective/activemq.xml.erb'. Template to use when configuring activemq middleware.
Boolean: defaults to false. Whether to enable the jetty admin console when configuring the activemq middleware.
String: defaults to undef. If supplied the contents of the activemq.xml
configuration file to use when configuring activemq middleware. Bypasses
mcollective::activemq_template
String: default based on distribution. The directory to copy ssl certificates
to when configuring activemq middleware with mcollective::middleware_ssl
.
String: defaults to '/etc/rabbitmq'. The directory to copy ssl certificates to
when configuring rabbitmq middleware with mcollective::middleware_ssl
.
String: defaults to '/mcollective'. The vhost to connect to/manage when using rabbitmq middleware.
Boolean: defaults to true. Whether to install mcollective and mcollective- client packages when installing the server and client components.
String: defaults to 'present'. What version of packages to ensure
when
mcollective::manage_packages
is true.
String: defaults to 'mcollective'. The name of the main collective for this client/server.
String: defaults to 'mcollective'. Comma seperated list of collectives this server should join.
String: defaults to 'activemq'. Name of the connector plugin to use.
Currently supported are activemq
, rabbitmq
, and redis
String: defaults to 'psk'. Name of the security provider plugin to use. 'ssl' is recommended but requires some additional setup.
String: defaults to 'changemeplease'. Used by the 'psk' security provider as the pre-shared key to secure the collective with.
String: defaults to 'yaml'. Name of the factsource plugin to use on the server.
String: defaults to '/etc/mcollective/facts.yaml'. Name of the file the 'yaml' factsource plugin should load facts from.
String: defaults to '/var/lib/puppet/state/classes.txt'. Name of the file the server will load the configuration management class for filtering.
String: defaults to 'action_policy'. Name of the RPC Auth Provider to use on the server.
String: defaults to 'logfile'. Name of the RPC Audit Provider to use on the server.
String: defaults to undef. Name of the registration plugin to use on the server.
String: default is based on platform. Path to the core plugins that are installed by the mcollective-common package.
String: default is based on platform. Path to the site-specific plugins that
the mcollective::plugin
type will install with its source
parameter.
This path will be managed and purged by puppet, so don't point it at core_libdir or any other non-dedicated path.
Array of strings: defaults to []. Where the middleware servers this client/server should talk to are.
String: defaults to 'mcollective'. Username to use when connecting to the middleware.
String: defaults to 'marionette'. Password to use when connecting to the middleware.
String: defaults to '61613'. Port number to use when connecting to the middleware over an unencrypted connection.
String: defaults to '61614'. Port number to use when connecting to the middleware over a ssl connection.
Boolean: defaults to false. Whether to talk to the middleware over a ssl
protected channel. Highly recommended. Requires mcollective::ssl_ca_cert
,
mcollective::ssl_server_public
, mcollective::ssl_server_private
parameters
for the server/client install.
String: default is '/etc/mcollective/server.cfg'. Path to the server configuration file.
String: defaults to '/var/log/mcollective.log'. Logfile the mcollective server should log to.
String: defaults to 'info'. Level the mcollective server should log at.
String: defaults to '1'. Should the mcollective server daemonize when started.
String: defaults to '/etc/mcollective/client.cfg'. Path to the client configuration file.
String: defaults to 'console'. What type of logger the client should use.
String: defaults to 'warn'. Level the mcollective client should log at.
String: defaults to undef. A file source that points to the ca certificate used to manage the ssl keys of the mcollective install.
String: defaults to undef. A file source that points to the public key or certificate of the server keypair.
String: defaults to undef. A file source that points to the private key of the server keypair.
String: defaults to 'puppet:///modules/mcollective/empty'. A file source that contains a directory of user certificates which are used by the ssl security provider in authenticating user requests.
mcollective::user
installs a client configuration and any needed client
certificates in a users home directory.
String: defaults to $name. The username of the user to install for.
String: defaults to $name. The group of the user to install for.
String: defaults to "/home/${name}". The home directory of the user to install for.
String: defaults to undef. A file source for the certificate of the user. Used by the 'ssl' securityprovider to set the identity of the user.
String: defaults to undef. A file source for the private key of the user.
Used when mcollective::middleware_ssl
is true to connect to the middleware
and by the 'ssl' securityprovider to sign messages as from this user.
mcollective::plugin
installs a plugin from a source uri or a package. When
installing from a source uri the plugin will be copied to
mcollective::site_libdir
mcollective::plugin { 'puppet':
package => true,
}
mcollective::plugin { 'myplugin':
source => 'puppet:///modules/site_mcollective/plugins',
}
String: the resource title. The base name of the plugin to install.
String: will default to "puppet:///modules/mcollective/plugins/${name}". The
source uri that will be copied to mcollective::site_libdir
Boolean: defaults to false. Whether to install the plugin from a file copy or a package install.
String: defaults to 'agent'. The type of the plugin package to install.
Boolean: defaults to true. When installing from a package, whether to attempt
to install mcollective-${name}-client
on the client node.
mcollective::actionpolicy
configures an agent for use with actionpolicy in
conjunction with mcollective::actionpolicy::rule
.
String: the resource title. The name of the agent to set up an actionpolicy for.
String: defaults to 'deny'. The default actionpolicy to apply to the agent.
mcollective::actionpolicy::rule
represents a single actionpolicy policy
entry.
String: the resource title. A descriptive name for the rule you are adding.
String: required, no default. The name of the agent you are adding a rule for.
String: defaults to 'allow'. What to do when the other conditions of this line are matched.
String: defaults to '*'. What callerids should match this rule.
String: defaults to '*'. What actions should match this rule.
String: defaults to '*'. What facts should match this rule.
String: defaults to '*'. What classes should match this rule.
mcollective::common::setting
declares a setting that is common between
server and client.
String: defaults to the resource title. The name of the setting to set.
String: no default. The value to set.
String: default '10'. The order in which to merge this setting.
mcollective::server::setting
declares a setting that is exclusive to a server.
String: defaults to the resource title. The name of the setting to set.
String: no default. The value to set.
String: default '30'. The order in which to merge this setting.
mcollective::client::setting
declares a setting that is common to clients
and users.
String: defaults to the resource title. The name of the setting to set.
String: no default. The value to set.
String: default '30'. The order in which to merge this setting.
mcollective::user::setting
declares a setting that is specific to a user.
String: required, no default. Which user to set this value for.
String: required, no default. The name of the setting to set.
String: no default. The value to set.
String: default '70'. The order in which to merge this setting.
The configuration of the server and client are built up from the various calls
to mcollective::common::setting
, mcollective::server::setting
,
mcollective::client::setting
, and mcollective::user::setting
.
Settings for the server will be a merge of mcollective::common::setting
and
mcollective::server::setting
, highest order of the setting wins.
Settings for the client will be a merge of mcollective::common::setting
,
and mcollective::client::setting
, highest order of the setting wins.
Settings for a specific user will be a merge of
mcollective::common::setting
, mcollective::client::setting
and
mcollective::user::setting
for that specific user, highest order of setting
wins.
You can override an existing server setting from outside of the module by simply specifying that setting again with a higher order than the default of that type, for example to make a server's loglevel be debug (without simply setting mcollective::server_loglevel) you could write:
mcollective::server::setting { 'override loglevel':
setting => 'loglevel',
value => 'debug',
order => '50',
}
This module has been built on and tested against Puppet 3.0 and higher.
The module has been tested on:
- CentOS 6
- Ubuntu 12.04
Testing on other platforms has been light and cannot be guaranteed.
Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
You can read the complete module contribution guide on the Puppet Labs wiki.