Page History

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#> or broker
• 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 valid,
  • <class> 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.
  Unsolicited keys have the structure: mgmt.<agent>.<type>.<package>.<class>.<severity> where
  • uuid of the originating management agent,
  • <type> is one of "
  • <agent> is the uuid of the originating management agent,
  • <type> is 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".

...

...

access codes are numerics with the following values:

...

        +-----+-----+-----+-------+-----------------------+
        | '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 (in0 schemaor order)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 element values are encoded by their type into the message in the order in which they appeared in the schema message.

Get Query Message

A Get Request may be sent by the management console to cause a management agent to immediately send content information for objects of a class.

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.

Get Query Message

A Get Request may be sent by the management console to cause a management agent to immediately send content information for objects of a class.

        +-----+-----+-----+-----+-----------------------+
        | 'A' | 'M' | '1' | 'G' |          seq          |
        +-----+-----+-----+-----+-----------------------+----------+
        | Get request field table                                  |
        +----------------------------------------------------------+

...

When the management agent receives a get request, it sends content messages describing the requested objects. Once the last content message is sent, it then sends a Command Completion message with the same sequence number supplied in the request to indicate to the requestor that there are no more messages coming.

Method Request

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.

        +-----+-----+-----+-----+-----------------------+
        | 'A' | 'M' | '1' | 'M' |          seq          |
        +-----+-----+-----+-----+-----------------------+
        |  objectId                                     |
        +-----------------------------------------------+------------------------+
        |  input and bidirectional argument values (in schema order)             |
        +------------------------------------------------------------------------+

Method Response

messages coming.

Method Request

Method request Method reply messages have the following structure. The sequence number is identical to that supplied 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 status code (and text) indicate whether or not the method was successful and if not, what the error was. Output and bidirectional arguments are only included if the status code was 0 (STATUS_OK)objectId is the unique ID of the object on which the method is to be executed.

        +-----+-----+-----+-----+-----------------------+
        | 'A' | 'M' | '1' | 'mM' |          seq          |
        +-----+-----+-----+-----+-----------------------+
        |  status codeobjectId (uint64)                            |
        +-----------------------+----------------------------------+
        |  status text (str8)       |  methodName (str8)                            |
        +-----------------------+------------------------+-----------+-------------+
        |  outputinput and bidirectional argument values (in schema order)             |
        +------------------------------------------------------------------------+

Method Response

Method reply messages have the following structure. The sequence number is identical to that supplied in the method request. The status code (and text) indicate whether or not the method was successful and if not, what the error was. Output and bidirectional arguments are only included if the status code was 0 (STATUS_OK).

        +-----+-----+-----+--------+-----------------------+

status code values are:

Messages for Extended Scenario

Extended Management Protocol

Qpid supports management extensions that allow the management broker to be a central point for the management of multiple external entities with their own management schemas.

      Broker        | 'A' | 'M' | '1' | 'm' |          seq          |
        +-----+-----+-----+-----+-----------------------+
        |  status code          |
        +-----------------------+----------------------------------+
        |  status text (str8)        Remote Agent
        |                     |
        +-----------------------+----------------------------------+-------------+
        |  output and bidirectional argument values (in schema   order)               |
        | <-----------+------------------------------ Attach Request --- |
        | --- Attach Response ------------------------------------+

status code values are:

Messages for Extended Scenario

Extended Management Protocol

Qpid supports management extensions that allow the management broker to be a central point for the management of multiple external entities with their own management schemas.

-> |
        |                                                               |
      Broker  |                                                               |
        | --- Package Query ------------------------------------------> |
        |     Remote Agent
        |                                                  |
        | <------------------------------------- Package Indication --- |
        | <----------------------------------------- PackageAttach IndicationRequest --- |
        | <-------- Attach Response ------------------------------- Command Complete --- |
        |                                                               ---------> |
        |                                                               |
        | <--- Class Query (package) ----------------------------------> |
Package       Indication --- |
        | <------------------------------------- Package Indication --- |
        |                                          |
        | <--------------------------------------- Class Indication --- |
                      | <--------------------------------------- Class Indication --- |
        | <--------------------------------------- Class Indication --- |
        | <--------------------------------------- Class Indication --- |
        | <--------------------------------------- Class Indication --- |
        | <--------------------------------------- Command Complete --- |
        |                                       ---------- Class Indication --- |
        | <--------------------------------------- Class              Indication --- |
        |                                                               |
        | --- Schema Request (class key) -----------------------------> |
        | <---------------------------------------- Schema Response --- |
        |                                                               |
        | --- Schema Request (class key) -----------------------------> |
        | <---------------------------------------- Schema Response --- |
        |                                                               |
        |                                                               |

...

Package Query

        +-----+-----+-----+-----+-----------------------+
        | 'A' | 'M' | '1' | 'P' |          seq          |
        +-----+-----+-----+-----+-----------------------+

...

        +-----+-----+-----+-----+-----------------------+
        | 'A' | 'M' | '1' | 'A' |          seq          |
        +-----+-----+-----+-----+-----------------------+----------+
        |  label (str8)                                            |
        +-----------------------+-----------------------------------+
        |  sessionsystem-nameid (str8uuid)                                        |
        +-----------------------+----------------------------------+
        |  requested objId bank |  system-id (uuid)
        +-----------------------+

Attach Response (success)

        +-----+-----+-----+-----+-----------------------+
        | 'A' | 'M' | '1' | 'a' |            seq            |
        +-----+-----+-----+-----+---------+--------------+
        |  assigned broker bank |
        +-----------------------+
        |  requestedassigned objId bank  |
        +-----------------------+

...

Console Added Indication

        +-----+-----+-----+-----+-----------------------+
        | 'A' | 'M' | '1' | 'ax' |          seq          |
        +-----+-----+-----+-----+-----------------------+
        |  assigned objId bank  |
        +-----------------------+