+++ /dev/null
----
-layout: default
-title: Single Executable Application Plugin
----
-[Clients]: ../../simplerpc/clients.html
-[SimpleRPCAgents]: ../../simplerpc/agents.html
-
-
-## Overview
-The Marionette Collective 1.1.1 and newer supports a single executable - called
-mco - and have a plugin type called application that lets you create
-applications for this single executable.
-
-In the past we tended to write small standalone scripts to interact with
-MCollective, this had a number of issues:
-
- * Large number of executables in _/usr/sbin_
- * Applications behave inconsistently with regard to error handling and reporting
- * Discovering new applications is difficult since they are all over the filesystem
- * Installation and packaging of plugins is complex
-
-We've attempted to address these concerns by creating a single point of access
-for all applications - the _mco_ script - with unified help, error reporting and
-option parsing.
-
-Below you can see the single executable system in use:
-
-{% highlight console %}
-The Marionette Collective version 2.0.0
-
-usage: /usr/bin/mco: command <options>
-
-Known commands:
-
- cap controller exim
- facts filemgr find
- help inventory iptables
- nettest nrpe package
- pgrep ping plugin
- puppetd rpc service
- virt
-
-Type 'mco help' for a detailed list of commands and 'mco help command'
-to get detailed help for a command
-
-{% endhighlight %}
-
-{% highlight console %}
-$ mco help
-The Marionette Collection version 2.0.0
-
- facts Reports on usage for a specific fact
- filemgr Generic File Manager Client
- find Find hosts matching criteria
- help Application list and RPC agent help
- inventory Shows an inventory for a given node
- ping Ping all nodes
- rpc Generic RPC agent client application
-{% endhighlight %}
-
-{% highlight console %}
-$ mco rpc package status package=zsh
-Determining the amount of hosts matching filter for 2 seconds .... 51
-
- * [ ============================================================> ] 51 / 51
-
-
- test.com:
- Properties:
- {:provider=>:yum,
- :release=>"3.el5",
- :arch=>"x86_64",
- :version=>"4.2.6",
- :epoch=>"0",
- :name=>"zsh",
- :ensure=>"4.2.6-3.el5"}
-{% endhighlight %}
-
-These applications are equivalent to the old mc-rpc and similar applications but without the problem of lots of files in _/usr/sbin_.
-
-## Basic Application
-Applications goes in _libdir/mcollective/application/echo.rb_, the one below is a simple application that speaks to a hypothetical _echo_ action of a _helloworld_ agent. This agent has been demonstrated in : writing [agents][SimpleRPCAgents].
-
-{% highlight ruby %}
-class MCollective::Application::Echo<MCollective::Application
- description "Reports on usage for a specific fact"
-
- option :message,
- :description => "Message to send",
- :arguments => ["-m", "--message MESSAGE"],
- :type => String,
- :required => true
-
- def main
- mc = rpcclient("helloworld")
-
- printrpc mc.echo(:msg => configuration[:message], :options => options)
-
- printrpcstats
- end
-end
-{% endhighlight %}
-
-Here's the application we wrote in action:
-
-{% highlight console %}
-$ mco echo
-The message option is mandatory
-
-Please run with --help for detailed help
-{% endhighlight %}
-
-{% highlight console %}
-$ mco echo -m test
-
- * [ ============================================================> ] 1 / 1
-
-
-example.com
- Message: test
- Time: Mon Jan 31 21:27:03 +0000 2011
-
-
-Finished processing 1 / 1 hosts in 68.53 ms
-{% endhighlight %}
-
-Most of the techniques documented in SimpleRPC [Clients] can be reused here, we've just simplified a lot of the common used patterns like CLI arguments and incorporated it all in a single framework.
-
-## Reference
-
-### Usage Messages
-
-To add custom usage messages to your application we can add lines like this:
-
-{% highlight ruby %}
-class MCollective::Application::Echo<MCollective::Application
- description "Reports on usage for a specific fact"
-
- usage "mco echo [options] --message message"
-end
-{% endhighlight %}
-
-You can add several of these messages by just adding multiple such lines.
-
-### Application Options
-
-A standard options hash is available simply as options you can manipulate it and pass it into the RPC Client like normal. See the SimpleRPC [Clients] reference for more on this.
-
-### CLI Argument Parsing
-
-There are several options available to assist in parsing CLI arguments. The most basic option is:
-
-{% highlight ruby %}
-class MCollective::Application::Echo<MCollective::Application
- option :message,
- :description => "Message to send",
- :arguments => ["-m", "--message MESSAGE"]
-end
-{% endhighlight %}
-
-In this case if the user used either _-m message_ or _--message message_ on the CLI the desired message would be in _configuration`[`:message`]`_
-
-#### Required Arguments
-You can require that a certain parameter is always passed:
-
-{% highlight ruby %}
-option :message,
- :description => "Message to send",
- :arguments => ["-m", "--message MESSAGE"],
- :required => true
-{% endhighlight %}
-
-#### Argument data types
-CLI arguments can be forced to a specific type, we also have some additional special types that the default ruby option parser cant handle on its own.
-
-You can force data to be of type String, Fixnum etc:
-
-{% highlight ruby %}
-option :count,
- :description => "Count",
- :arguments => ["--count MESSAGE"],
- :type => Fixnum
-{% endhighlight %}
-
-You can force an argument to be boolean:
-
-{% highlight ruby %}
-option :detail,
- :description => "Detailed view",
- :arguments => ["--detail"],
- :type => :bool
-{% endhighlight %}
-
-If you have an argument that can be called many times you can force that to build an array:
-
-{% highlight ruby %}
-option :args,
- :description => "Arguments",
- :arguments => ["--argument ARG"],
- :type => :array
-{% endhighlight %}
-
-Here if you supplied multiple arguments _configuration`[`:args`]`_ will be an array with all the options supplied.
-
-#### Argument validation
-You can validate input passed on the CLI:
-
-{% highlight ruby %}
-option :count,
- :description => "Count",
- :arguments => ["--count MESSAGE"],
- :type => Fixnum,
- :validate => Proc.new {|val| val < 10 ? true : "The message count has to be below 10" }
-{% endhighlight %}
-
-Should the supplied value be 10 or more a error message will be displayed.
-
-#### Disabling standard sections of arguments
-By default every Application get all the RPC options enabling filtering, discovery etc. In some cases this is undesirable so we let users disable those.
-
-{% highlight ruby %}
-class MCollective::Application::Echo<MCollective::Application
- exclude_argument_sections "common", "filter", "rpc"
-end
-{% endhighlight %}
-
-This application will only have --help, --verbose and --config as options, all the other options will be removed.
-
-#### Post argument parsing hook
-Right after all arguments are parsed you can have a hook in your program called, this hook could perhaps parse the remaining data on _ARGV_ after option parsing is complete.
-
-{% highlight ruby %}
-class MCollective::Application::Echo<MCollective::Application
- description "Reports on usage for a specific fact"
-
- def post_option_parser(configuration)
- unless ARGV.empty?
- configuration[:message] = ARGV.shift
- else
- STDERR.puts "Please specify a message on the command line"
- exit 1
- end
- end
-
- def main
- # use configuration[:message] here to access the message
- end
-end
-{% endhighlight %}
-
-#### Validating configuration
-After the options are parsed and the post hook is called you can validate the contents of the configuration:
-
-{% highlight ruby %}
-class MCollective::Application::Echo<MCollective::Application
- description "Reports on usage for a specific fact"
-
- # parse the first argument as a message
- def post_option_parser(configuration)
- configuration[:message] = ARGV.shift unless ARGV.empty?
- end
-
- # stop the application if we didnt receive a message
- def validate_configuration(configuration)
- raise "Need to supply a message on the command line" unless configuration.include?(:message)
- end
-
- def main
- # use configuration[:message] here to access the message
- end
-end
-{% endhighlight %}
-
-### Exiting your application
-You can use the normal _exit_ Ruby method at any time to exit your application and you can supply any
-exit code as normal.
-
-The supplied applications have a standard exit code convention, if you want your applications to exhibit
-the same behavior use the _halt_ helper. The exit codes are below:
-
-|Code|Description |
-|----|-----------------------------------------------------|
-|0 |Nodes were discovered and all passed |
-|0 |No discovery was done but responses were received |
-|1 |No nodes were discovered |
-|2 |Nodes were discovered but some responses failed |
-|3 |Nodes were discovered but no responses were received |
-|4 |No discovery were done and no responses were received|
-
-{% highlight ruby %}
-class MCollective::Application::Echo<MCollective::Application
- description "Reports on usage for a specific fact"
-
- def main
- mc = rpcclient("echo")
-
- printrpc mc.echo(:msg => "Hello World", :options => options)
-
- printrpcstats
-
- halt mc.stats
- end
-end
-{% endhighlight %}
-
-As you can see you pass the _halt_ helper an instance of the RPC Client statistics and it will then
-use that to do the right exit code.
-
Code Review / packages / precise / mcollective.git / blobdiff