5 [SecurityPlugins]: http://github.com/puppetlabs/marionette-collective/tree/master/plugins/mcollective/security/
6 [SimpleRPCIntroduction]: /mcollective/simplerpc/
7 [MessageFlow]: messageflow.html
8 [ScreenCast]: /mcollective/screencasts.html#message_flow
10 The messages that gets put on the middleware attempts to contain everything that mcollective needs to function, avoiding where possible special features in the Middle Ware. This will hopefully make it easier to create Connector plugins for other middleware.
12 At present the task of encoding and decoding messages lies with the _MCollective::Security::`*`_ classes, see the provided [security plugins][SecurityPlugins] as a examples.
14 Abstracting the encoding away from the security plugins is a goal for future refactorings, till then each security plugin will need to at least conform to the following structure.
16 In general this is all hidden from the developers, especially if you use [Simple RPC][SimpleRPCIntroduction]. If you want to implement your own security or serialization you will need to know exactly how all of this sticks together.
18 There is also a [screencast][ScreenCast] that shows this process and message format, recommend you watch that.
21 For details of the flow of messages and how requests / replies travel around the network see the [MessageFlow] page.
25 |Date|Description|Ticket|
26 |----|-----------|------|
27 |2011/04/23|Add _agent_ and _collective_ to the request hashes|7113|
29 ### Requests sent to agents
30 A sample request that gets sent to the connector can be seen here, each component is described below:
34 {"cf_class" => ["common::linux"],
35 "fact" => [{:fact=>"country", :value=>"uk"}],
36 "agent" => ["package"]},
37 :senderid => "devel.your.com",
38 :msgtarget => "/topic/mcollective.discovery.command",
39 :agent: => 'discovery',
40 :collective' => 'mcollective',
42 :hash => "2d437f2904980ac32d4ebb7ca1fd740b",
43 :msgtime => 1258406924,
45 :requestid => "0b54253cb5d04eb8b26ea75bbf468cbc"}
48 Once this request is created the security plugin will serialize it and sent it to the connector, in the case of the PSK security plugin this is done using Marshal.
51 The filter will be evaluated by each node, if it passes the node will dispatch the message to an agent.
53 You can see all these types of filter in action in the _MCollection::Optionparser_ class.
55 Each filter is an array and you can have multiple filters per type which will be applied with an _AND_
56 Valid filter types are:
60 This will look in a list of classes/recipes/cookbooks/roles applied by your
61 configuration management system and match based on that
64 filter["cf_class"] = ["common::linux"]
67 ##### MCollective Agent
69 This will look through the list of known agents and match against that.
72 filter["agent"] = ["package"]
77 Since facts are key => value pairs this is a bit more complex than normal as you need to build a nested Hash.
80 filter["fact"] = [{:fact => "country", :value => "uk"}]
83 Regular expression matches are:
86 filter["fact"] = [{:fact => "country", :value => "/uk/"}]
89 As of version 1.1.0 this has been extended to support more comparison operators:
92 filter["fact"] = [{:fact => "country", :value => "uk", :operator => "=="}]
95 Valid operators are: ==, =~, <=, =>, >=, =<, > < and !=
97 As regular expressions are now done using their own operator backwards compatability
98 is lost and in mixed version environment 1.1.x clients doing regex matches on facts
99 will be treated as equality on 1.0.x and older clients.
103 The identity is the configured identity in the server config file, many hosts can have the same identity it's just another level of filter doesn't really mean much like a hostname that would need to be unique.
106 filter["identity"] = ["foo.bar.com"]
111 The value of _identity_ in the configuration file.
115 The Middleware topic or channel the message is being sent to. This is not being used since later 1.1.x and since 1.3.1 it is not included in messages anymore.
119 The contents of the body will vary by what ever the security provider choose to impliment, the PSK security provider simply Marshal encodes the body into a serialized format ready for transmission.
121 This ensures that variable types etc remain in tact end to end. Other security providers might use JSON etc, the decoding of this is also handled by the security provider so its totally up to the provider to decide.
123 In the case of [Simple RPC][SimpleRPCIntroduction] the entire RPC request and replies will be in the body of the messages, it's effectively a layer on top of the basic message flow.
127 This is an example of something specific to the security provider, this is used only by the PSK provider so it's optional and specific to the PSK provider
131 The unix timestamp that the message was sent at.
135 Each request has a TTL, messages older than this gets discarded. Added in version 1.3.1
139 This is a unique id for each message that gets sent, replies will have the same id attached to them for validation.
141 ### Replies from Agents
142 Replies are very similar to requests, I'll show a reply below and only highlight the differences between requests.
145 {:senderid => "devel.your.com",
146 :senderagent => "package",
147 :msgtarget => "/topic/mcollective.package.reply",
149 :hash => "2d437f2904980ac32d4ebb7ca1fd740b",
150 :msgtime => 1258406924,
151 :requestid => "0b54253cb5d04eb8b26ea75bbf468cbc"}
154 Once this reply is created the security plugin will serialize it and sent it to the connector, in the case of the PSK security plugin this is done using serialization tools like Marshal or YAML depending on Security Plugin.
157 This is the agent name that sent the reply
160 The id that was contained in the request we are replying to. Agents do not generally tend to generate messages - they only reply - so this should always be provided.