You must use SimpleRPC for writing agents and clients. SimpleRPC is a framework that wraps the core MCollective client and agent structures in a lot of helpful convention and tools.
The approach to developing agents and clients documented below is not supported post version 2.0.0 and the functionality will be removed for the next major release.
Writing agents for mcollective is simple, we’ll write a simple echo agent as well as a cli tool to communicate with it that supports discovery, filtering and more.
The agent will send back everything that got sent to it, not overly useful but enough to demonstrate the concepts.
Agents go into a directory configured in the server.cfg using the libdir directive. You should have mcollective/agent directory under that, restart the daemon when you’ve put it there.
Create a file echo.rb with the following, I’ll walk through each part:
Once you have it running you can test your agent works as below, we’ll send the word hello to the agent and we’ll see if we get it back:
Each agent should be wrapped in a module and class as below, this will create an agent called echo and should live in a file called agents/echo.rb.
Every agent needs to specify a timeout and meta data. The timeout gets used by the app server to kill off agents that is taking too long to finish.
Meta data contains some information about the licence, author and version of the agent. Right now the information is free-form but I suggest supplying at the very least the details below as we’ll start enforcing the existence of it in future.
Handling incoming messages
You do not need to be concerned with filtering, authentication, authorization etc when writing agents - the app server takes care of all of that for you.
Whenever a message for your agent pass all the checks it will be passed to you via the handlemsg method.
The msg will be a hash with several keys giving you information about sender, hashes, time it was sent and so forth, in our case we just want to know about the body and we’re sending it right back as a return value.
We keep help information, not used right now but future version of the code will have a simple way to get help for each agent, the intent is that inputs, outputs and behavior to all agents would be described in this.
More complex agents
As you write more complex agents and clients you might find the need to have a few separate files make up your agent, you can drop these files into a directory named util under the plugins (that is, at the same level of the agent folder, so as /usr/libexec/mcollective/mcollective/util at the time of writing).
Create the util folder if needed.
The classes should be MCollective::Util::Yourclass and you should use the following construct to require them from disk:
Create util/yourclass.rb with this content :
loadclass on Yourclass will automatically search for a yourclass.rb file (lowercase).
At present simply requiring them will work and we’ll hope to maintain that but to be 100% future safe use this method.
It also loads modules in exactly the same way.
We provide a client library that abstracts away a lot of the work in writing simple attractive cli frontends to your agents that supports discovery, filtering, generates help etc. The client lib is functional but we will improve/refactor the options parsing a bit in future.
We can test it works as below:
Discovery and filtering: