3 title: Using MCollective Command Line Applications
5 MCollective is designed first and foremost for the CLI. You will mostly
6 interact with a single executable called *mco* which has a number of
7 sub-commands, arguments and flags.
9 ## Basic Usage of the *mco* Command
11 A simple example of a *mco* command can be seen below:
13 {% highlight console %}
21 ---- ping statistics ----
22 25 replies max: 305.58 min: 57.50 avg: 113.16
25 In this example the *ping* sub-command is referred to as an
26 *application*. Mcollective provides many applications, for a list of
27 them, type *mco help*. You can also create your own application to plug
28 into the framework. The *help* sub-command will show you something like
32 {% highlight console %}
34 The Marionette Collective version 2.0.0
36 controller Control the mcollective daemon
37 facts Reports on usage for a specific fact
38 find Find hosts matching criteria
39 help Application list and help
40 inventory General reporting tool for nodes, collectives and subcollectives
42 plugin MCollective Plugin Application
43 rpc Generic RPC agent client application
46 You can request help for a specific application using either *mco help
47 application* or *mco application ---help*. Shown below is part of the
48 help for the *rpc* application:
50 {% highlight console %}
52 Generic RPC agent client application
54 Usage: mco rpc [options] [filters] --agent <agent> --action <action> [--argument <key=val> --argument ...]
55 Usage: mco rpc [options] [filters] <agent> <action> [<key=val> <key=val> ...]
57 --no-results, --nr Do not process results, just send request
58 -a, --agent AGENT Agent to call
59 --action ACTION Action to call
60 --arg, --argument ARGUMENT Arguments to pass to agent
62 --np, --no-progress Do not show the progress bar
63 -1, --one Send request to only one discovered nodes
64 --batch SIZE Do requests in batches
65 --batch-sleep SECONDS Sleep time between batches
66 --limit-nodes, --ln COUNT Send request to only a subset of nodes, can be a percentage
67 -j, --json Produce JSON output
68 -c, --config FILE Load configuratuion from file rather than default
69 -v, --verbose Be verbose
70 -h, --help Display this screen
73 -T, --target COLLECTIVE Target messages to a specific sub collective
74 --dt, --discovery-timeout SECONDS
75 Timeout for doing discovery
76 -t, --timeout SECONDS Timeout for calling remote agents
77 -q, --quiet Do not be verbose
78 --ttl TTL Set the message validity period
79 --reply-to TARGET Set a custom target for replies
82 -W, --with FILTER Combined classes and facts filter
83 -S, --select FILTER Compound filter combining facts and classes
84 -F, --wf, --with-fact fact=val Match hosts with a certain fact
85 -C, --wc, --with-class CLASS Match hosts with a certain config management class
86 -A, --wa, --with-agent AGENT Match hosts with a certain agent
87 -I, --wi, --with-identity IDENT Match hosts with a certain configured identity
89 The Marionette Collective 2.0.0
92 The *help* first shows a basic overview of the command line syntax
93 followed by options specific to this command. Following that you will
94 see some *Common Options* and *Host Filters* that generally apply to
97 ## Making RPC Requests
99 ### Overview of a Request
101 The *rpc* application is the main application used to make requests to
102 your servers. It is capable of interacting with any standard Remote
103 Procedure Call (RPC) agent. Below is an example that shows an attempt to
104 start a webserver on several machines:
106 {% highlight console %}
107 % mco rpc service start service=httpd
108 Determining the amount of hosts matching filter for 2 seconds .... 10
110 * [ ============================================================> ] 10 / 10
113 Could not start Service[httpd]: Execution of '/sbin/service httpd start' returned 1:
116 Finished processing 10 / 10 hosts in 1323.61 ms
119 The order of events in this process are:
121 * Perform discovery against the network and discover 10 servers
122 * Send the request and then show a progress bar of the replies
123 * Show any results that were out of the ordinary
124 * Show some statistics
126 Mcollective client applications aim to only provide the most relevant
127 information. In this case, the application is not showing verbose
128 information about the nine *OK* results, since the most important issue
129 is the one *Failure*. Keep this in mind when viewing the results of
132 ### Anatomy of a Request
134 MCollective agents are broken up into actions and each action can take
137 {% highlight console %}
138 % mco rpc service stop service=httpd
141 This shows the basic make-up of an RPC command. In this case we are:
143 * using the *rpc* application - a generic application that can interact with any agent
144 * directing our request to machines with the *service* agent
145 * sending a request to the *stop* action of the service agent
146 * supplying a value, *httpd*, to the *service* argument of the *stop* action
148 The same command has a longer form as well:
150 {% highlight console %}
151 % mco rpc --agent service --action stop --argument service=httpd
154 These two commands are functionally identical.
156 ### Discovering Available *Agents*
158 The above command showed you how to interact with the *service* agent,
159 but how can you find out that this agent even exists? On a correctly
160 installed MCollective system you can use the *plugin* application to get
163 {% highlight console %}
165 Please specify a plugin. Available plugins are:
168 package Install and uninstall software packages
169 puppetd Run puppet agent, get its status, and enable/disable it
170 rpcutil General helpful actions that expose stats and internals to SimpleRPC clients
171 service Agent to manage services
174 The first part of this list shows all the agents this computer is aware
175 of. In order to show up on this list, an agent must have a *DDL* file
176 and be installed locally.
178 To find out the *actions*, *inputs* and *outputs* for a specific agent
179 use the plugin application again:
181 {% highlight console %}
182 % mco plugin doc service
183 SimpleRPC Service Agent
184 =======================
186 Agent to manage services
192 Home Page: http://mcollective-plugins.googlecode.com/
198 restart, start, status, stop
202 Gets the status of a service
206 Description: The service to get the status for
209 Validation: ^[a-zA-Z\-_\d]+$
215 Description: The status of service
216 Display As: Service Status
219 This shows a truncated example of the auto-generated help for the
220 *service* agent. First shown is metadata such as version, author and
221 license. This is followed by the list of actions available, in this case
222 the *restart*, *start*, *status* and *stop* actions.
224 Further information is shown about each action. For example, you can see
225 that the *status* action requires an input called *service* which is a
226 string, has a maximum length of 30, etc. You can also see you will
227 receive one output called *status*
229 With this information, you can request the status for a specific
232 {% highlight console %}
233 % mco rpc service status service=httpd
234 Determining the amount of hosts matching filter for 2 seconds .... 10
236 * [ ============================================================> ] 10 / 10
240 Service Status: stopped
243 Service Status: stopped
249 Finished processing 10 / 10 hosts in 326.01 ms
252 Unlike the previous example, in this case specific information is
253 returned on the success of the action. This is because this specific
254 action is meant to retrieve information and so mcollective assumes you
255 would like to see complete, thorough data regardless of success or
258 Note that this output displays *Service Status* as shown in the *mco
259 plugin doc service* help page. Any time you need more information about
260 a display name, the doc for the associated agent will have a
261 *Description* section for every input and output.
263 ## Selecting Request Targets Using *Filters*
267 A key capability of mcollective is fast discovery of network resources.
268 Discovery rules are written using *filters*. For example:
270 {% highlight console %}
271 % mco rpc service status service=httpd -S "environment=development or customer=acme"
274 This shows a filter rule that limits the RPC request to being run on
275 machines that are either in the Puppet environment *development* or
276 belong to the Customer *acme*.
278 Filtering can be based on *facts*, the presence of a *Configuration
279 Management Class* on the node, the node's *Identity*, or installed
280 *Agents* on the node.
282 Here are a number of examples of this with short descriptions of each
285 {% highlight console %}
286 # all machines with the service agent
287 % mco ping -A service
288 % mco ping --with-agent service
290 # all machines with the apache class on them
292 % mco ping --with-class apache
294 # all machines with a class that match the regular expression
295 % mco ping -C /service/
297 # all machines in the UK
298 % mco ping -F country=uk
299 % mco ping --with-fact country=uk
301 # all machines in either UK or USA
302 % mco ping -F "country=/uk|us/"
304 # just the machines called dev1 or dev2
305 % mco ping -I dev1 -I dev2
307 # all machines in the domain foo.com
308 % mco ping -I /foo.com$/
311 As you can see, you can filter by Agent, Class and/or Fact, and you can
312 use regular expressions almost anywhere. You can also combine filters
313 additively in a command so that all the criteria have to be matched.
315 Note: You can use a shortcut to combine Class and Fact filters:
317 {% highlight console %}
318 # all machines with classes matching /apache/ in the UK
319 % mco ping -W "/apache/ location=uk"
322 ### Complex *Compound* or *Select* Queries
324 While the above examples are easy to enter, they are limited in that
325 they can only combine filters additively. If you want to create searches
326 with more complex boolean logic use the *-S* switch. For example:
328 {% highlight console %}
329 % mco ping -S "((customer=acme and environment=staging) or environment=development) and /apache/"
332 The above example shows a scenario where the development environment is
333 usually labeled *development* but one customer has chosen to use
334 *staging*. You want to find all machines in those customer's
335 environments that match the class *apache*. This search would be
336 impossible using the previously shown methods, but the above command
337 uses *-S* to allow the use of boolean operators such as *and* and *or*
338 so you can easily build the logic of the search.
340 The *-S* switch also allows for negative matches using *not* or *!*:
342 {% highlight console %}
343 % mco ping -S "environment=development and !customer=acme"
344 % mco ping -S "environment=development and not customer=acme"
347 ### Filtering Using Data Plugins
349 As of version 2.1.0, custom data plugins can also be used to create
352 {% highlight console %}
353 % mco ping -S "fstat('/etc/hosts').md5=/baa3772104/ and environment=development"
356 This will search for the md5 hash of a specific file with matches
357 restricted to the *development* environment. Note that as before,
358 regular expressions can also be used.
360 As with agents, you can also discover which plugins are available for
363 {% highlight console %}
366 Please specify a plugin. Available plugins are:
373 agent Meta data about installed MColletive Agents
374 augeas_match Allows agents and discovery to do Augeas match lookups
375 fstat Retrieve file stat data for a given file
376 resource Information about Puppet managed resources
377 sysctl Retrieve values for a given sysctl
380 For information on the input these plugins take and output they provide
381 use the *mco plugin doc fstat* command.
383 Currently, each data function can only accept one input while matches
384 are restricted to a single output field per invocation.
386 ## Chaining RPC Requests
388 The *rpc* application can chain commands one after the other. The
389 example below uses the *package* agent to find machines with a specific
390 version of mcollective and then schedules Puppet runs on those machines:
392 {% highlight console %}
393 % mco rpc package status package=mcollective -j|jgrep "data.properties.ensure=2.0.0-6.el6" |mco rpc puppetd runonce
396 Mcollective results can also be filtered using the opensource gem,
397 jgrep. Mcollective data output is fully compatible with jgrep.
399 ## Seeing the Raw Data
401 By default the *rpc* application will try to show human-readable data.
402 To see the actual raw data, add the *-v* flag to disable the display
405 {% highlight console %}
406 % mco rpc nrpe runcommand command=check_load -I dev1 -v
410 {:exitcode=>0, :output=>"OK - load average: 0.00, 0.00, 0.00", :perfdata=> "load1=0.000;1.500;2.000;0; load5=0.000;1.500;2.000;0; load15=0.000;1.500;2.000;0;"}
414 This data can also be returned in JSON format:
416 {% highlight console %}
417 % mco rpc nrpe runcommand command=check_load -I dev1 -j
420 "action": "runcommand",
424 "output": "OK - load average: 0.00, 0.00, 0.00",
425 "perfdata": "load1=0.000;1.500;2.000;0; load5=0.000;1.500;2.000;0; load15=0.000;1.500;2.000;0;"
436 When an application encounters an error, it returns an explanatory
439 {% highlight console %}
440 % mco rpc rpcutil foo
441 rpc failed to run: Attempted to call action foo for rpcutil but it's not declared in the DDL (MCollective::DDLValidationError)
444 By default only an abbreviated error string is shown that provides some
445 insight into the nature of the problem. For more details, add the *-v*
446 flag to show a full stack trace:
448 {% highlight console %}
449 % mco rpc rpcutil foo -v
450 rpc failed to run: Attempted to call action foo for rpcutil but it's not declared in the DDL (MCollective::DDLValidationError)
451 from /usr/lib/ruby/site_ruby/1.8/mcollective/ddl.rb:303:in `validate_rpc_request'
452 from /usr/lib/ruby/site_ruby/1.8/mcollective/rpc/client.rb:218:in `method_missing'
453 from /home/rip/.mcollective.d/lib/mcollective/application/rpc.rb:133:in `send'
454 from /home/rip/.mcollective.d/lib/mcollective/application/rpc.rb:133:in `main'
455 from /usr/lib/ruby/site_ruby/1.8/mcollective/application.rb:283:in `run'
456 from /usr/lib/ruby/site_ruby/1.8/mcollective/applications.rb:23:in `run'
460 ## Custom Applications
461 The *rpc* application should suit most needs. However, sometimes the
462 data being returned calls for customization such as custom aggregation,
463 summarising or complete custom display.
465 In such cases, a custom application may be useful For example, the
466 *package* application provides concluding summaries and provides some
467 basic safe guards for its use. The agent also provides the commonly
468 required data. Typical *package* output looks like this:
470 {% highlight console %}
471 % mco package status kernel
472 Do you really want to operate on packages unfiltered? (y/n): y
474 * [ ============================================================> ] 25 / 25
477 dev5 version = kernel-2.6.32-220.7.1.el6
478 dev9 version = kernel-2.6.32-220.2.1.el6
482 ---- package agent summary ----
484 Versions: 9 * 2.6.32-220.2.1.el6, 9 * 2.6.32-220.4.1.el6, 7 * 2.6.32-220.el6
489 Notice how this application recognises that you are acting on all
490 possible machines, an action which might have a big impact on your YUM
491 servers. Consequently, *package* prompts for confirmation and, at the
492 end of processing, displays a brief summary of the network status.
494 While the behaviors of custom applications are not always consistant
495 with each other, in general they accept the standard discovery flags.
496 For details of which flags are accepted in a given application, use the
497 *mco help appname* command.
499 To discover which custom applications are available, run *mco* or *mco