3 title: Data Definition Language
5 [WritingAgents]: /mcollective/reference/basic/basic_agent_and_client.html
6 [SimpleRPCClients]: /mcollective/simplerpc/clients.html
7 [ResultsandExceptions]: /mcollective/simplerpc/clients.html#results_and_exceptions
8 [SimpleRPCAuditing]: /mcollective/simplerpc/auditing.html
9 [SimpleRPCAuthorization]: /mcollective/simplerpc/authorization.html
10 [WritingAgentsScreenCast]: http://mcollective.blip.tv/file/3808928/
11 [DDLScreenCast]: http://mcollective.blip.tv/file/3799653
12 [RPCUtil]: /mcollective/reference/plugins/rpcutil.html
13 [ValidatorPlugins]: /mcollective/reference/plugins/validator.html
15 As with other remote procedure invocation systems MCollective has a DDL that defines what remote methods are available, what inputs they take and what outputs they generate.
17 In addition to the usual procedure definitions we also keep meta data about author, versions, license and other key data points.
19 The DDL is used in various scenarios:
21 * The user can access it in the form of a human readable help page
22 * User interfaces can access it in a way that facilitate auto generation of user interfaces
23 * The RPC client auto configures and use appropriate timeouts in waiting for responses
24 * Before sending a call over the network inputs get validated so we do not send unexpected data to remote nodes.
25 * Module repositories can use the meta data to display a standard view of available modules to assist a user in picking the right ones.
26 * The server will validate incoming requests prior to sending it to agents
28 We've created [a screencast showing the capabilities of the DDL][DDLScreenCast] that might help give you a better overview.
30 **NOTE:** As of version 2.1.1 the DDL is required on all servers before an agent will be activated
33 We'll start with a few examples as I think it's pretty simple what they do, and later on show what other permutations are allowed for defining inputs and outputs.
35 A helper agent called [_rpcutil_][RPCUtil] is included that helps you gather stats, inventory etc about the running daemon. This helper has a full DDL included, see the plugins dir for this agent.
37 The typical service agent is a good example, it has various actions that all more or less take the same input. All but status would have almost identical language.
40 First we need to define the meta data for the agent itself:
42 {% highlight ruby linenos %}
43 metadata :name => "SimpleRPC Service Agent",
44 :description => "Agent to manage services using the Puppet service provider",
45 :author => "R.I.Pienaar",
48 :url => "http://projects.puppetlabs.com/projects/mcollective-plugins/wiki",
52 It's fairly obvious what these all do, *:timeout* is how long the MCollective daemon will let the threads run.
55 As of MCollective 2.1.2 you can indicate which is the lowest version of MCollective needed to use a plugin. Plugins that do not meet the requirement can not be used.
57 {% highlight ruby linenos %}
58 requires :mcollective => "2.0.0"
61 You should add this right after the metadata section in the DDL
63 ## Actions, Input and Output
64 Defining inputs and outputs is the hardest part, below first the *status* action:
66 {% highlight ruby linenos %}
67 action "status", :description => "Gets the status of a service" do
68 display :always # supported in 0.4.7 and newer only
71 :prompt => "Service Name",
72 :description => "The service to get the status for",
74 :validation => '^[a-zA-Z\-_\d]+$',
76 :default => "mcollective",
80 :description => "The status of service",
81 :display_as => "Service Status",
82 :default => "unknown status"
86 As you see we can define all the major components of input and output parameters. *:type* can be one of various values and each will have different parameters, more on that later.
88 As of version 2.1.1 the outputs can define a default value. For agents the reply structures are pre-populated with all the defined outputs, if no default is supplied a default of nil will be set.
90 As of version 2.3.1 the inputs can also define default values, this is only processed and applied for non optional inputs.
92 By default mcollective only show data from actions that failed, the *display* line above tells it to always show the results. Possible values are *:ok*, *:failed* (the default behavior) and *:always*.
94 Finally the service agent has 3 almost identical actions - *start*, *stop* and *restart* - below we use a simple loop to define them all in one go.
96 {% highlight ruby linenos %}
97 ["start", "stop", "restart"].each do |act|
98 action act, :description => "#{act.capitalize} a service" do
100 :prompt => "Service Name",
101 :description => "The service to #{act}",
103 :validation => '^[a-zA-Z\-_\d]+$',
108 :description => "The status of service after #{act}",
109 :display_as => "Service Status",
110 :default => "unknown status"
115 All of this code just goes into a file, no special class or module bits needed, just save it as *service.ddl* in the same location as the *service.rb*.
117 Importantly you do not need to have the *service.rb* on a machine to use the DDL, this means on machines that are just used for running client programs you can just drop the *.ddl* files into the agents directory.
119 You can view a human readable version of this using *mco plugin doc <agent>* command:
121 {% highlight console %}
122 % mco plugin doc service
123 SimpleRPC Service Agent
124 =======================
126 Agent to manage services using the Puppet service provider
132 Home Page: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki
138 restart, start, status, stop
146 Description: The service to restart
149 Validation: ^[a-zA-Z\-_\d]+$
155 Description: The status of service after restart
156 Display As: Service Status
160 The input block has a mandatory *:optional* field, when true it would be ok if a client attempts to call the agent without this input supplied. If it is supplied though it will be validated.
163 As you see above the input block has *:type* option, types can be *:string*, *:list*, *:boolean*, *:integer*, *:float* or *:number*
166 The string type validates initially that the input is infact a String, then it validates the length of the input and finally matches the supplied Regular Expression.
168 Both *:validation* and *:maxlength* are required arguments for the string type of input.
170 If you want to allow unlimited length text you can make *:maxlength => 0* but use this with care.
172 As of version 2.2.0 a new plugin type called [Validator Plugins][ValidatorPlugins] exist that allow you to supply your own validations for *:string* types.
175 List types provide a list of valid options and only those will be allowed, see an example below:
177 {% highlight ruby linenos %}
179 :prompt => "Service Action",
180 :description => "The action to perform",
183 :list => ["stop", "start", "restart"]
186 In user interfaces this might be displayed as a drop down list selector or another kind of menu.
190 The value input should be either _true_ or _false_ actual boolean values. This feature was introduced in version _0.4.9_.
194 The value input should be an integer number like _1_ or _100_ but not _1.1_. This feature was introduced in version _1.3.2_
198 The value input should be a floating point number like _1.0_ but not _1_. This feature was introduced in version _1.3.2_
202 The value input should be an integer or a floating point number. This feature was introduced in version _1.3.2_
206 The value input can be any type, this allows you to send rich objects like arrays of hashes around, it effectively disables validation of the type of input.
208 The :any type is deprecated and will be removed after version 2.2.x.
210 ### Accessing the DDL
211 While programming client applications or web apps you can gain access to the DDL for any agent in several ways:
213 {% highlight ruby linenos %}
214 require 'mcollective'
216 config = MCollective::Config.instance
217 config.loadconfig(options[:config])
219 ddl = MCollective::DDL.new("service")
220 puts ddl.help("#{config.configdir}/rpc-help.erb")
223 This will produce the text help output from the above example, you can supply any ERB template to format the output however you want.
225 You can also access the data structures directly:
227 {% highlight ruby linenos %}
228 ddl = MCollective::DDL.new("service")
233 puts "Status Action:"
234 pp ddl.action_interface("status")
237 {% highlight ruby linenos %}
240 :author=>"R.I.Pienaar",
241 :name=>"SimpleRPC Service Agent",
244 :url=>"http://projects.puppetlabs.com/projects/mcollective-plugins/wiki",
245 :description=>"Agent to manage services using the Puppet service provider"}
251 {:validation=>"^[a-zA-Z\\-_\\d]+$",
253 :prompt=>"Service Name",
256 :description=>"The service to get the status for"}},
259 {:display_as=>"Service Status", :description=>"The status of service"}},
260 :description=>"Gets the status of a service"}
264 The ddl object is also available on any *rpcclient*:
266 {% highlight ruby linenos %}
267 service = rpcclient("service")
271 In the case of accessing it through the service as in this example, if there was no DDL file on the machine for the service agent you'd get a *nil* back from the ddl accessor.
274 As mentioned earlier the client does automatic input validation using the DDL, if validation fails you will get an *MCollective::DDLValidationError* exception thrown with an appropriate message.