Status of This Document
This document does not track any current development activity. It is the specification of the management framework implemented in the M3 release of the C++ broker and will be left here for user and developer reference.
Development continues on the Qpid Management Framework (QMF) for M4. If you are using M3, this is the document you need. If you are using the SVN trunk, please refer to Qpid Management Framework for up-to-date information.
Introduction
This document describes the management features that are used in the QPID C++ broker as of the M3 milestone. These features do not appear in earlier milestones nor are they implemented in the Java broker.
...
Placing this information in the routing key provides the ability to enforce access control at class, operation, and method granularity. It also separates the command structure from the content of the management message (i.e. element values) allowing the content to be encrypted and signed end-to-end while still allowing access control at the message-transport level. This means that special access control code need not be written for the management agent.
There are two general types of routing/binding key:
- Command messages simply use the key:
agent.<bank#>
orbroker
- Method Unsolicited keys have the structure:
agentmgmt.<agent>.method<type>.<package>.<class>.<method><severity>
where<package>
<agent>
is the namespace in which the <class> name is validuuid of the originating management agent,<class>
<type>
is the name of the class as defined in the schema, and<method>
is one of "get", "set", or a schema-defined class-specific method name.
mgmt.<agent>.<type>.<package>.<class>.<severity>
where<agent>
is the uuid of the originating management agent,<type>
is one of "schema", "one of "schema", "prop", "stat", or "event",<package>
is the namespace in which the <class> name is valid, and<class>
is the name of the class as defined in the schema.<severity>
is relevant for events only. It is one of "critical", "error", "warning", or "info".
...
field name | optional | description |
name | no | Name of the property |
type | no | Type code for the property |
access | no | Access code for the property |
index | no | 1 = index element, 0 = not an index element |
optional | no | 1 = optional element (may be not present), 0 = mandatory (always present) |
unit | yes | Units for numeric values (i.e. seconds, bytes, etc.) |
min | yes | Minimum value for numerics |
max | yes | Maximum value for numerics |
maxlen | yes | Maximum length for strings |
desc | yes | Description of the property |
...
value | type |
1 | uint8 |
2 | uint16 |
3 | uint32 |
4 | uint64 |
6 | str8 |
7 | str16 |
8 | absTime(uint64) |
9 | deltaTime(uint64) |
10 | objectReference(uint64) |
11 | boolean(uint8) |
12 | float |
13 | double |
14 | uuid |
15 | map |
16 | int8 |
17 | int16 |
18 | int32 |
19 | int64 |
access codes are numerics with the following values:
...
No Format |
---|
+-----+-----+-----+-------+-----------------------+ | 'A' | 'M' | '1' |'g/c/i'| seq | +-----+-----+-----+-------+-----------------------+--------+ | packageName (str8) | +----------------------------------------------------------+ | className (str8) | +----------------------------------------------------------+ | class hash (bin128) | +-----+-----+-----+-----+-----+-----+-----+-----+----------+ | timestamp of current sample (datetime) | +-----+-----+-----+-----+-----+-----+-----+-----+ | time object was created (datetime) | +-----+-----+-----+-----+-----+-----+-----+-----+ | time object was deleted (datetime) | +-----+-----+-----+-----+-----+-----+-----+-----+ | objectId (uint64) | +-----+-----+-----+-----+-----+-----+-----+-----+------------------------+ | config/instpresence valuesbitmasks (in 0 or more uint8 fields) | +-----+-----+-----+-----+-----+-----+-----+-----+------------------------+ | config/inst values (in schema order) | +------------------------------------------------------------------------+ |
All timestamps are uint64 values representing nanoseconds since the epoch (January 1, 1970). The objectId is a uint64 value that uniquely identifies this object instance. The objectId is a uint64 value that uniquely identifies this object instance.
If any of the properties in the object are defined as optional, there will be 1 or more "presence bitmask" octets. There are as many octets as are needed to provide one bit per optional property. The bits are assigned to the optional properties in schema order (first octet first, lowest order bit first).
For example: If there are two optional properties in the schema called "option1" and "option2" (defined in that order), there will be one presence bitmask octet and the bits will be assigned as bit 0 controls option1 and bit 1 controls option2.
If the bit for a particular optional property is set (1), the property will be encoded normally in the "values" portion of the message. If the bit is clear (0), the property will be omitted from the list of encoded values and will be considered "NULL" or "not present".
The element values are encoded by their type into the message in the order in which they appeared in the schema message.
...
Method request messages have the following structure. The sequence number is opaque to the management agent. It is returned unchanged in the method reply so the calling client can correctly associate the reply to the request. The objectId is the unique ID of the object on which the method is to be executed.of the object on which the method is to be executed.
No Format |
---|
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '1' | 'M' | seq | |
No Format |
+-----+-----+-----+-----+-----------------------+ | 'A' | 'M' | '1' | 'M' | objectId (uint64) seq | +-----+---------+-----+-----+-----------------------+ | objectId methodName (str8) | +-----------------------------------------------+------------------------+ | input and bidirectional argument values (in schema order) | +------------------------------------------------------------------------+ |
...
opcode | message | description |
'P' | Package Query | This message contains a schema package query request, requesting that the broker dump the list of known packages |
'p' | Package Indication | This message contains a schema package indication, identifying a package known by the broker |
'A' | Agent Attach Request | |
'a' | Agent Attach Response | |
Attach Request | This message is sent by a remote agent when it wishes to attach to a management broker | |
'a' | Agent Attach Response | The management broker sends this response if an attaching remote agent is permitted to join |
'x' | Console Added Indication | This message is sent to all remote agents by the management broker when a new console binds to the management exchange |
Package Query
No Format |
---|
+-----+-----+-----+-----+-----------------------+ | 'A' | 'M' | '1' | 'P' | seq | +-----+-----+-----+-----+-----------------------+ |
...
No Format |
---|
+-----+-----+-----+-----+-----------------------+ | 'A' | 'M' | '1' | 'A' | seq | +-----+-----+-----+-----+-----------------------+----------+ | label (str8) | +-----------------------+-----------------------------------+ | sessionsystem-nameid (str8uuid) | +-----------------------+----------------------------------+ | requested system-id (uuid)objId bank | +-----------------------+ |
Attach Response (success)
No Format |
---|
+-----+-----+-----+-----+-----------------------+ | 'A' | 'M' | '1' | 'a' | seq | +-----+-----+-----+-----+-------+----------------+ | assigned broker bank | +-----------------------+ | requestedassigned objId bank | +-----------------------+ |
...
Console Added Indication
No Format |
---|
+-----+-----+-----+-----+-----------------------+ | 'A' | 'M' | '1' | 'ax' | seq | +-----+-----+-----+-----+-----------------------+ | assigned objId bank | +-----------------------+ |