README - mcollective version 2.12.5

# The Marionette Collective¶ ↑

The Marionette Collective aka. mcollective is a framework to build server orchestration or parallel job execution systems.

For documentation please see docs.puppet.com/mcollective

## Developing¶ ↑

The documentation above details how `MCollective` works and many of its extension points.

### Spec Tests¶ ↑

To run spec tests `bundle install bundle exec rake test`

### Acceptance Tests¶ ↑

To run acceptance tests, see this.

### Development Environment (MacOS)¶ ↑

Setup ActiveMQ using acceptance config: `brew install activemq cp acceptance/files/activemq.* /usr/local/opt/activemq/libexec/conf activemq start`

ActiveMQ can later by stopped with `activemq stop`. ActiveMQ logs are located at `/usr/local/opt/activemq/libexec/data/activemq.log`.

Setup `MCollective` with acceptance config: `mkdir -p ~/.puppetlabs/etc/mcollective/ssl-clients cp acceptance/files/client.* ~/.puppetlabs/etc/mcollective cp acceptance/files/server.* ~/.puppetlabs/etc/mcollective cp acceptance/files/ca_crt.pem ~/.puppetlabs/etc/mcollective cp acceptance/files/client.crt ~/.puppetlabs/etc/mcollective/ssl-clients/client.pem ln -s ~/.puppetlabs/etc/mcollective/client.cfg ~/.mcollective`

Modify `client.cfg` to work on the local machine: * Change the `ssl_server_public`, `ssl_client_private`, `ssl_client_public` paths to point to `~/.puppetlabs/etc/mcollective/{server.crt,client.key,client.pem}`. * Change the `activemq.pool.1.ssl.{ca,cert,key}` paths to `~/.puppetlabs/etc/mcollective/{ca_crt.pem,client.crt,client.key}`. Note that `~` needs to be expanded to the full path. Also, that `client.pem` doesn't point to an actual file is intentional (I don't fully understand why).

Create `server.cfg`, updating `<user>`: “` main_collective = mcollective collectives = mcollective logger_type = console loglevel = info daemonize = 0

securityprovider = ssl plugin.ssl_server_private = /Users/<user>/.puppetlabs/etc/mcollective/server.key plugin.ssl_server_public = /Users/<user>/.puppetlabs/etc/mcollective/server.crt plugin.ssl_client_cert_dir = /Users/<user>/.puppetlabs/etc/mcollective/ssl-clients

connector = activemq plugin.activemq.pool.size = 1 plugin.activemq.pool.1.host = activemq plugin.activemq.pool.1.port = 61613 plugin.activemq.pool.1.user = mcollective plugin.activemq.pool.1.password = marionette plugin.activemq.pool.1.ssl = true plugin.activemq.pool.1.ssl.ca = /Users/<user>/.puppetlabs/etc/mcollective/ca_crt.pem plugin.activemq.pool.1.ssl.cert = /Users/<user>/.puppetlabs/etc/mcollective/server.crt plugin.activemq.pool.1.ssl.key = /Users/<user>/.puppetlabs/etc/mcollective/server.key “`

The configuration above uses `activemq` as the name of the ActiveMQ broker. `MCollective` will enforce that the SSL certificate presented by the server matches the name it's trying to connect to. To use the configuration above, traffic to `activemq` must be redirected to the local host. On most machines, that can be accomplished with `sudo echo "127.0.0.1   activemq" >> /etc/hosts`

From the root of this repository, test the setup by running a server `RUBYLIB=lib bundle exec bin/mcollectived --config ~/.puppetlabs/etc/mcollective/server.cfg` and client `RUBYLIB=lib bundle exec bin/mco ping`

Note that it may be useful to change the `loglevel` in `client.cfg` to debug issues with `mco ping`.

To enable specific plugins, you may need to set `libdir` in `server.cfg` and add plugin-specific configuration.

## Contributing¶ ↑

Please refer to this document.