diff options
Diffstat (limited to 'qpid/doc/book/src/Management-Design-notes.xml')
| -rw-r--r-- | qpid/doc/book/src/Management-Design-notes.xml | 2136 |
1 files changed, 2136 insertions, 0 deletions
diff --git a/qpid/doc/book/src/Management-Design-notes.xml b/qpid/doc/book/src/Management-Design-notes.xml new file mode 100644 index 0000000000..76f0dac926 --- /dev/null +++ b/qpid/doc/book/src/Management-Design-notes.xml @@ -0,0 +1,2136 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +--> + +<section><title> + Management Design notes + </title><section role="h2" id="ManagementDesignnotes-StatusofThisDocument"><title> + Status + of This Document + </title> + + <para> + 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. + </para><para> + 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 <xref linkend="qpid_Qpid-Management-Framework"/> for + up-to-date information. + </para> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-Introduction"><title> + Introduction + </title> + + <para> + 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. + </para><para> + This specification is <emphasis>not</emphasis> a standard and is not endorsed + by the AMQP working group. When such a standard is adopted, the + QPID implementation will be brought into compliance with that + standard. + </para> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-Links"><title> + Links + </title> + + <itemizedlist> + <listitem><para>The schema is checked into <xref linkend="qpid_management-schema.xml"/>. + </para></listitem> + </itemizedlist><section role="h3" id="ManagementDesignnotes-DesignnoteforgettinginfoinandoutviaJMX"><title> + Design + note for getting info in and out via JMX + </title> + + <para> + <xref linkend="qpid_JMX-Gateway"/> + </para> + <!--h3--></section> + + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-ManagementRequirements"><title> + Management + Requirements + </title> + + <itemizedlist> + <listitem><para>Must operate from a formally defined management schema. + </para></listitem> + <listitem><para>Must natively use the AMQP protocol and its type system. + </para></listitem> + <listitem><para>Must support the following operations + <itemizedlist> + <listitem><para>SET operation on configurable (persistent) aspects of + objects + </para></listitem> + <listitem><para>GET operation on all aspects of objects + </para></listitem> + <listitem><para>METHOD invocation on schema-defined object-specific + methods + </para></listitem> + <listitem><para>Distribution of unsolicited periodic updates of + instrumentation data + <itemizedlist> + <listitem><para>Data updates shall carry an accurate sample timestamp + for rate calculation + </para></listitem> + <listitem><para>Updates shall carry object create/delete timestamps. + </para></listitem> + <listitem><para>Transient objects shall be fully accounted for via + updates. Note that short-lived transient objects may come + and go within a single update interval. All of the + information pertaining to such an object must be captured + and transmitted. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para>Distribution of unsolicited event and/or alert + indications (schema defined) + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para>Role-based access control at object, operation, and method + granularity + </para></listitem> + <listitem><para>End-to-end encryption and signing of management content + </para></listitem> + <listitem><para>Schema must be self-describing so the management client need + not have prior knowledge of the management model of the system + under management. + </para></listitem> + <listitem><para>Must be extensible to support the management of objects + beyond the QPID component set. This allows AMQP to be used as a + general-purpose management protocol. + </para></listitem> + </itemizedlist> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-DefinitionofTerms"><title> + Definition + of Terms + </title> + + <table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + class + </entry> + <entry> + A type definition for a manageable object. + </entry> + </row> + <row> + <entry> + package + </entry> + <entry> + A grouping of class definitions that are related to a + single software component. The package concept is used to + extend the management schema beyond just the QPID software + components. + </entry> + </row> + <row> + <entry> + object + </entry> + <entry> + Also "manageable object". An instantiation of a class. An + object represents a physical or logical component in the + core function of the system under management. + </entry> + </row> + <row> + <entry> + property + </entry> + <entry> + A typed member of a class which represents a configurable + attribute of the class. In general, properties don't change + frequently or may not change at all. + </entry> + </row> + <row> + <entry> + statistic + </entry> + <entry> + A typed member of a class which represents an + instrumentation attribute of the class. Statistics are + always read-only in nature and tend to change rapidly. + </entry> + </row> + <row> + <entry> + method + </entry> + <entry> + A member of a class which represents a callable procedure + on an object of the class. Methods may have an arbitrary + set of typed arguments and may supply a return code. + Methods typically have side effects on the associated + object. + </entry> + </row> + <row> + <entry> + event + </entry> + <entry> + A member of a class which represents the occurence of an + event of interest within the system under management. + </entry> + </row> + <row> + <entry> + management broker + </entry> + <entry> + A software component built into the messaging broker that + handles management traffic and distributes management data. + </entry> + </row> + <row> + <entry> + management agent + </entry> + <entry> + A software component that is separate from the messaging + broker, connected to the management broker via an AMQP + connection, which allows any software component to be + managed remotely by QPID. + </entry> + </row> + </tbody> + </tgroup></table> + <!--h2--></section> + + + <section role="h2" id="ManagementDesignnotes-OperationalScenarios-3ABasicvs.Extended"><title> + Operational + Scenarios: Basic vs. Extended + </title> + + <para> + The extensibility requirement introduces complexity to the + management protocol that is unnecessary and undesirable for the + user/developer that wishes only to manage QPID message brokers. + For this reason, the protocol is partitioned into two parts: The + <emphasis>basic protocol</emphasis>, which contains only the capability to + manage a single broker; and the <emphasis>extended protocol</emphasis>, which + provides the hooks for managing an extended set of components. A + management console can be implemented using only the basic + protocol if the extended capabilities are not needed. + </para> +<!--h2--></section> + + + <section role="h2" id="ManagementDesignnotes-ArchitecturalFramework"><title> + Architectural + Framework + </title> + + <para> + <xref linkend="qpid_qmf_architecture"/> + </para> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-TheManagementExchange"><title> + The + Management Exchange + </title> + + <para> + The management exchange (called "qpid.management" currently) is a + special type of exchange used for remote management access to the + Qpid broker. The management exchange is an extension of the + standard "Topic" exchange. It behaves like a topic exchange with + the following exceptions: + </para><orderedlist> + <listitem><para>When a queue is successfully bound to the exchange, a method + is invoked on the broker's management agent to notify it of the + presence of a new remote managment client. + </para></listitem> + <listitem><para>When messages arrive at the exchange for routing, the + exchange examines the message's routing key and if the key + represents a management command or method, it routes it directly + to the management agent rather than routing it to queues using + the topic algorithm. + The management exchange is used by the management agent to + distribute unsolicited management data. Such data is classified + by the routing key allowing management clients to register for + only the data they need. + </para></listitem> + </orderedlist><section role="h3" id="ManagementDesignnotes-RoutingKeyStructure"><title> + Routing + Key Structure + </title> + + <para> + As noted above, the structure of the binding and routing keys + used on the management exchange is important to the function of + the management architecture. The routing key of a management + message determines: + </para><orderedlist> + <listitem><para>The type of message (i.e. operation request or unsolicited + update). + </para></listitem> + <listitem><para>The class of the object that the message pertains to. + </para></listitem> + <listitem><para>The specific operation or update type. + </para></listitem> + <listitem><para>The namespace in which the class belongs. This allows for + plug-in expansion of the management schema for manageable objects + that are outside of the broker itself. + </para></listitem> + </orderedlist><para> + 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: + </para><itemizedlist> + <listitem><para> + <emphasis>Command</emphasis> messages use the key: + agent.<bank#> or broker + </para></listitem> + <listitem><para> + <emphasis>Unsolicited</emphasis> keys have the structure: + mgmt.<agent>.<type>.<package>.<class>.<severity> + where + <itemizedlist> + <listitem><para> + <agent> is the uuid of the originating + management agent, + </para></listitem> + <listitem><para> + <type> is one of "schema", "prop", "stat", + or "event", + </para></listitem> + <listitem><para> + <package> is the namespace in which the + <class> name is valid, and + </para></listitem> + <listitem><para> + <class> is the name of the class as defined + in the schema. + </para></listitem> + <listitem><para> + <severity> is relevant for events only. It + is one of "critical", "error", "warning", or "info". + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist><para> + In both cases, the content of the message (i.e. method arguments, + element values, etc.) is carried in the body segment of the + message. + </para><para> + The <package> namespace allows this management + framework to be extended with the addition of other software + packages. + </para> + <!--h3--></section> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-TheProtocol"><title> + The Protocol + </title> + + <section role="h3" id="ManagementDesignnotes-ProtocolHeader"><title> + Protocol + Header + </title> + + <para> + The body segments of management messages are composed of + sequences of binary-encoded data fields, in a manner consistent + with the 0-10 version of the AMQP specification. + </para><para> + All management messages begin with a message header: + </para> + <programlisting> + octet 0 1 2 3 4 5 6 7 + +---------+---------+---------+---------+---------+---------+---------+---------+ + | 'A' | 'M' | '1' | op-code | sequence | + +---------+---------+---------+---------+---------+---------+---------+---------+ +</programlisting> + <para> + The first three octets contain the protocol <emphasis>magic number</emphasis> + "AM1" which is used to identify the type and version of the + message. + </para><para> + The <emphasis>opcode</emphasis> field identifies the operation represented by + the message + </para> + <!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-ProtocolExchangePatterns"><title> + Protocol + Exchange Patterns + </title> + + <para> + The following patterns are followed in the design of the + protocol: + </para><itemizedlist> + <listitem><para>Request-Response + </para></listitem> + <listitem><para>Query-Indication + </para></listitem> + <listitem><para>Unsolicited Indication + </para></listitem> + </itemizedlist><section role="h4" id="ManagementDesignnotes-TheRequestResponsePattern"><title> + The + Request-Response Pattern + </title> + + <para> + In the request-response pattern, a requestor sends a + <emphasis>request</emphasis> message to one of its peers. The peer then does + one of two things: If the request can be successfully processed, + a single <emphasis>response</emphasis> message is sent back to the requestor. + This response contains the requested results and serves as the + positive acknowledgement that the request was successfully + completed. + </para><para> + If the request cannot be successfully completed, the peer sends a + <emphasis>command complete</emphasis> message back to the requestor with an + error code and error text describing what went wrong. + </para><para> + The sequence number in the <emphasis>response</emphasis> or <emphasis>command + complete</emphasis> message is the same as the sequence number in the + <emphasis>request</emphasis>. + </para> + <programlisting> + Requestor Peer + | | + | --- Request (seq) ------------------------------------------> | + | | + | <----------------------------------------- Response (seq) --- | + | | +</programlisting> + + <programlisting> + Requestor Peer + | | + | --- Request (seq) ------------------------------------------> | + | | + | <-------------------------- Command Complete (seq, error) --- | + | | +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-TheQueryIndicationPattern"><title> + The + Query-Indication Pattern + </title> + + <para> + The query-indication pattern is used when there may be zero or + more answers to a question. In this case, the requestor sends a + <emphasis>query</emphasis> message to its peer. The peer processes the query, + sending as many <emphasis>indication</emphasis> messages as needed back to the + requestor (zero or more). Once the last <emphasis>indication</emphasis> has + been sent, the peer then sends a <emphasis>command complete</emphasis> message + with a success code indicating that the query is complete. + </para><para> + If there is an error in the <emphasis>query</emphasis>, the peer may reply with + a <emphasis>command complete</emphasis> message containg an error code. In this + case, no <emphasis>indication</emphasis> messages may be sent. + </para><para> + All <emphasis>indication</emphasis> and <emphasis>command complete</emphasis> messages shall + have the same sequence number that appeared in the <emphasis>query</emphasis> + message. + </para> + <programlisting> + Requestor Peer + | | + | --- Query (seq) --------------------------------------------> | + | | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | | + | <------------------------ Command Complete (seq, success) --- | + | | +</programlisting> + + <programlisting> + Requestor Peer + | | + | --- Query (seq) --------------------------------------------> | + | | + | <-------------------------- Command Complete (seq, error) --- | + | | +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-TheUnsolicitedIndicationPattern"><title> + The + Unsolicited-Indication Pattern + </title> + + <para> + The unsolicited-indication pattern is used when one peer needs to + send unsolicited information to another peer, or to broadcast + information to multiple peers via a topic exchange. In this case, + indication messages are sent with the sequence number field set + to zero. + </para> + <programlisting> + Peer Peer + | | + | <----------------------------------- Indication (seq = 0) --- | + | <----------------------------------- Indication (seq = 0) --- | + | <----------------------------------- Indication (seq = 0) --- | + | <----------------------------------- Indication (seq = 0) --- | + | | +</programlisting> +<!--h4--></section> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-ObjectIdentifiers"><title> + Object + Identifiers + </title> + + <para> + Manageable objects are tagged with a unique 64-bit object + identifier. The object identifier space is owned and managed by + the management broker. Objects managed by a single management + broker shall have unique object identifiers. Objects managed by + separate management brokers may have the same object identifier. + </para><para> + If a management console is designed to manage multiple management + brokers, it must use the broker identifier as well as the object + identifier to ensure global uniqueness. + </para> + <programlisting> + 62 48 47 24 23 0 + +-+-------------+-----------------------+-----------------------+ + |0| sequence | bank | object | + +-+-------------+-----------------------+-----------------------+ + + bit 63 - reserved, must be zero + bits 63 .. 48 - broker boot sequence (32K) + bits 47 .. 24 - bank (16M) + bits 23 .. 0 - object (16M) +</programlisting> + <itemizedlist> + <listitem><para>For persistent IDs, boot-sequence is zero + </para></listitem> + <listitem><para>For non-persistent IDs, boot sequence is a constant number + which increments each time the management broker is restarted. + </para></listitem> + <listitem><para>Bank number: + <itemizedlist> + <listitem><para>0 - reserved + </para></listitem> + <listitem><para>1 - broker-persistent objects + </para></listitem> + <listitem><para>2..4 - store-persistent objects + </para></listitem> + <listitem><para>> 4 - transient objects + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> +<!--h3--></section> + + + <section role="h3" id="ManagementDesignnotes-EstablishingCommunicationBetweenClientandAgent"><title> + Establishing Communication Between Client and Agent + </title> + + <para> + Communication is established between the management client and + management agent using normal AMQP procedures. The client creates + a connection to the broker and then establishes a session with + its corresponding channel. + </para><para> + Two private queues are then declared (only one if method + invocation is not needed). A management queue is declared and + bound to the qpid.management exchange. If the binding key is + "mgmt.#", all management-related messages sent to the exchange + will be received by this client. A more specific binding key will + result in a more restricted set of messages being received (see + the section on Routing Key Structure below). + </para><para> + If methods are going to be invoked on managed objects, a second + private queue must be declared so the client can receive method + replies. This queue is bound to the amq.direct exchange using a + routing key equal to the name of the queue. + </para><para> + When a client successfully binds to the qpid.management exchange, + the management agent schedules a schema broadcast to be sent to + the exchange. The agent will publish, via the exchange, a + description of the schema for all manageable objects in its + control. + </para> + <programlisting> + Client Broker + | | + | --- AMQP Connection and Session Setup ----------------------> | + | | + | --- Queue.declare (private data queue) ---------------------> | + | --- Bind queue to exchange 'qpid.management' key 'mgmt.#' --> | + | | + | --- Queue.declare (private method-reply queue) -------------> | + | --- Bind queue to exchange 'amq.direct' --------------------> | + | | + | --- Broker Request -----------------------------------------> | + | <---------------------------------------- Broker Response --- | + | | + | | + | | + | <------- Management schema via exchange 'qpid.management' --- | + | | +</programlisting> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-BroadcastofConfigurationandInstrumentationUpdates"><title> + Broadcast of Configuration and Instrumentation Updates + </title> + + <para> + The management agent will periodically publish updates to the + configuration and instrumentation of management objects under its + control. Under normal circumstances, these updates are published + only if they have changed since the last time they were + published. Configuration updates are only published if + configuration has changed and instrumentation updates are only + published if instrumentation has changed. The exception to this + rule is that after a management client binds to the + qpid.management exchange, all configuration and instrumentation + records are published as though they had changed whether or not + they actually did. + </para> + <programlisting> + Client Broker + | | + | <------------------ Object properties via 'mgmt.*.prop.#' --- | | + | <------------------ Object statistics via 'mgmt.*.stat.#' --- | | + | | | + | | | Publish Interval + | | | + | | | + | | V + | <------------------ Object properties via 'mgmt.*.prop.#' --- | + | <------------------ Object statistics via 'mgmt.*.stat.#' --- | + | | +</programlisting> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-InvokingaMethodonaManagedObject"><title> + Invoking + a Method on a Managed Object + </title> + + <para> + When the management client wishes to invoke a method on a managed + object, it sends a method request message to the qpid.management + exchange. The routing key contains the object class and method + name (refer to Routing Key Structure below). The method request + must have a header entry (reply-to) that contains the name of the + method-reply queue so that the method response can be properly + routed back to the requestor. + </para><para> + The method request contains a sequence number that is copied to + the method reply. This number is opaque to the management agent + and may be used by the management client to correlate the reply + to the request. The asynchronous nature of requests and replies + allows any number of methods to be in-flight at a time. Note that + there is no guarantee that methods will be replied to in the + order in which they were requested. + </para> + <programlisting> + Client Broker + | | + | --- Method Request (to exchange 'qpid.management') ---------> | + | | + | | + | <--------------- Method Reply (via exchange 'amq.direct') --- | + | | +</programlisting> +<!--h3--></section> + + + <section role="h3" id="ManagementDesignnotes-MessagesfortheBasicScenario"><title> + Messages + for the Basic Scenario + </title> + + <para> + The principals in a management exchange are the <emphasis>management + client</emphasis> and the <emphasis>management agent</emphasis>. The management + agent is integrated into the QPID broker and the management + client is a remote entity. A management agent may be managed by + zero or more management clients at any given time. Additionally, + a management client may manage multiple management agents at the + same time. + </para><para> + For authentication and access control, management relies on the + mechanisms supplied by the AMQP protocol. + </para><section role="h4" id="ManagementDesignnotes-BasicOpcodes"><title> + Basic Opcodes + </title> + + <table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>opcode</emphasis> + </entry> + <entry> + <emphasis>message</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + 'B' + </entry> + <entry> + Broker Request + </entry> + <entry> + This message contains a broker request, sent from the + management console to the broker to initiate a management + session. + </entry> + </row> + <row> + <entry> + 'b' + </entry> + <entry> + Broker Response + </entry> + <entry> + This message contains a broker response, sent from the + broker in response to a broker request message. + </entry> + </row> + <row> + <entry> + 'z' + </entry> + <entry> + Command Completion + </entry> + <entry> + This message is sent to indicate the completion of a + request. + </entry> + </row> + <row> + <entry> + 'Q' + </entry> + <entry> + Class Query + </entry> + <entry> + Class query messages are used by a management console to + request a list of schema classes that are known by the + management broker. + </entry> + </row> + <row> + <entry> + 'q' + </entry> + <entry> + Class Indication + </entry> + <entry> + Sent by the management broker, a class indication notifies + the peer of the existence of a schema class. + </entry> + </row> + <row> + <entry> + 'S' + </entry> + <entry> + Schema Request + </entry> + <entry> + Schema request messages are used to request the full schema + details for a class. + </entry> + </row> + <row> + <entry> + 's' + </entry> + <entry> + Schema Response + </entry> + <entry> + Schema response message contain a full description of the + schema for a class. + </entry> + </row> + <row> + <entry> + 'h' + </entry> + <entry> + Heartbeat Indication + </entry> + <entry> + This message is published once per publish-interval. It can + be used by a client to positively determine which objects + did not change during the interval (since updates are not + published for objects with no changes). + </entry> + </row> + <row> + <entry> + 'c', 'i', 'g' + </entry> + <entry> + Content Indication + </entry> + <entry> + This message contains a content record. Content records + contain the values of all properties or statistics in an + object. Such records are broadcast on a periodic interval + if 1) a change has been made in the value of one of the + elements, or 2) if a new management client has bound a + queue to the management exchange. + </entry> + </row> + <row> + <entry> + 'G' + </entry> + <entry> + Get Query + </entry> + <entry> + Sent by a management console, a get query requests that the + management broker provide content indications for all + objects that match the query criteria. + </entry> + </row> + <row> + <entry> + 'M' + </entry> + <entry> + Method Request + </entry> + <entry> + This message contains a method request. + </entry> + </row> + <row> + <entry> + 'm' + </entry> + <entry> + Method Response + </entry> + <entry> + This message contains a method result. + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-BrokerRequestMessage"><title> + Broker + Request Message + </title> + + <para> + When a management client first establishes contact with the + broker, it sends a Hello message to initiate the exchange. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'B' | 0 | + +-----+-----+-----+-----+-----------------------+ +</programlisting> + <para> + The Broker Request message has no payload. + </para> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-BrokerResponseMessage"><title> + Broker + Response Message + </title> + + <para> + When the broker receives a Broker Request message, it responds + with a Broker Response message. This message contains an + identifier unique to the broker. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'b' | 0 | + +-----+-----+-----+-----+-----------------------+----------------------------+ + | brokerId (uuid) | + +----------------------------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-CommandCompletionMessage"><title> + Command + Completion Message + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'z' | seq | + +-----+-----+-----+-----+-----------------------+ + | Completion Code | + +-----------------------+-----------------------------------------+ + | Completion Text | + +-----------------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-ClassQuery"><title> + Class Query + </title> + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'Q' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | package name (str8) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-ClassIndication"><title> + Class + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'q' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | package name (str8) | + +----------------------------------------------------------+ + | class name (str8) | + +----------------------------------------------------------+ + | schema hash (bin128) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-SchemaRequest"><title> + Schema Request + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'S' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | packageName (str8) | + +----------------------------------------------------------+ + | className (str8) | + +----------------------------------------------------------+ + | schema-hash (bin128) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-SchemaResponse"><title> + Schema + Response + </title> + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 's' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | packageName (str8) | + +----------------------------------------------------------+ + | className (str8) | + +----------------------------------------------------------+ + | schema-hash (bin128) | + +-----------+-----------+-----------+-----------+----------+ + | propCnt | statCnt | methodCnt | eventCnt | + +-----------+-----------+-----------+-----------+----------------------------+ + | propCnt property records | + +----------------------------------------------------------------------------+ + | statCnt statistic records | + +----------------------------------------------------------------------------+ + | methodCnt method records | + +----------------------------------------------------------------------------+ + | eventCnt event records | + +----------------------------------------------------------------------------+ +</programlisting> + <para> + Each <emphasis>property</emphasis> record is an AMQP map with the following + fields. Optional fields may optionally be omitted from the map. + </para><table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + no + </entry> + <entry> + Name of the property + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + no + </entry> + <entry> + Type code for the property + </entry> + </row> + <row> + <entry> + access + </entry> + <entry> + no + </entry> + <entry> + Access code for the property + </entry> + </row> + <row> + <entry> + index + </entry> + <entry> + no + </entry> + <entry> + 1 = index element, 0 = not an index element + </entry> + </row> + <row> + <entry> + optional + </entry> + <entry> + no + </entry> + <entry> + 1 = optional element (may be not present), 0 = mandatory + (always present) + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + yes + </entry> + <entry> + Units for numeric values (i.e. seconds, bytes, etc.) + </entry> + </row> + <row> + <entry> + min + </entry> + <entry> + yes + </entry> + <entry> + Minimum value for numerics + </entry> + </row> + <row> + <entry> + max + </entry> + <entry> + yes + </entry> + <entry> + Maximum value for numerics + </entry> + </row> + <row> + <entry> + maxlen + </entry> + <entry> + yes + </entry> + <entry> + Maximum length for strings + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + Description of the property + </entry> + </row> + </tbody> + </tgroup></table><para> + Each <emphasis>statistic</emphasis> record is an AMQP map with the following + fields: + </para><table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + no + </entry> + <entry> + Name of the statistic + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + no + </entry> + <entry> + Type code for the statistic + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + yes + </entry> + <entry> + Units for numeric values (i.e. seconds, bytes, etc.) + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + Description of the statistic + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>method</emphasis> and <emphasis>event</emphasis> records contain a main map that + describes the method or header followed by zero or more maps + describing arguments. The main map contains the following fields: + </para><table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + no + </entry> + <entry> + Name of the method or event + </entry> + </row> + <row> + <entry> + argCount + </entry> + <entry> + no + </entry> + <entry> + Number of argument records to follow + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + Description of the method or event + </entry> + </row> + </tbody> + </tgroup></table><para> + Argument maps contain the following fields: + </para><table><title/><tgroup cols="5"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>method</emphasis> + </entry> + <entry> + <emphasis>event</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + Argument name + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + Type code for the argument + </entry> + </row> + <row> + <entry> + dir + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Direction code for method arguments + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + Units for numeric values (i.e. seconds, bytes, etc.) + </entry> + </row> + <row> + <entry> + min + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Minimum value for numerics + </entry> + </row> + <row> + <entry> + max + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Maximum value for numerics + </entry> + </row> + <row> + <entry> + maxlen + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Maximum length for strings + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + Description of the argument + </entry> + </row> + <row> + <entry> + default + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Default value for the argument + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>type codes</emphasis> are numerics with the following values: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>type</emphasis> + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + uint8 + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + uint16 + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + uint32 + </entry> + </row> + <row> + <entry> + 4 + </entry> + <entry> + uint64 + </entry> + </row> + <row> + <entry> + 6 + </entry> + <entry> + str8 + </entry> + </row> + <row> + <entry> + 7 + </entry> + <entry> + str16 + </entry> + </row> + <row> + <entry> + 8 + </entry> + <entry> + absTime(uint64) + </entry> + </row> + <row> + <entry> + 9 + </entry> + <entry> + deltaTime(uint64) + </entry> + </row> + <row> + <entry> + 10 + </entry> + <entry> + objectReference(uint64) + </entry> + </row> + <row> + <entry> + 11 + </entry> + <entry> + boolean(uint8) + </entry> + </row> + <row> + <entry> + 12 + </entry> + <entry> + float + </entry> + </row> + <row> + <entry> + 13 + </entry> + <entry> + double + </entry> + </row> + <row> + <entry> + 14 + </entry> + <entry> + uuid + </entry> + </row> + <row> + <entry> + 15 + </entry> + <entry> + map + </entry> + </row> + <row> + <entry> + 16 + </entry> + <entry> + int8 + </entry> + </row> + <row> + <entry> + 17 + </entry> + <entry> + int16 + </entry> + </row> + <row> + <entry> + 18 + </entry> + <entry> + int32 + </entry> + </row> + <row> + <entry> + 19 + </entry> + <entry> + int64 + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>access codes</emphasis> are numerics with the following values: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>access</emphasis> + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + Read-Create access + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + Read-Write access + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + Read-Only access + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>direction codes</emphasis> are numerics with the following values: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>direction</emphasis> + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + Input (from client to broker) + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + Output (from broker to client) + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + IO (bidirectional) + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-HeartbeatIndication"><title> + Heartbeat + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'h' | 0 | + +-----+-----+-----+-----+-----------------------+ + | timestamp of current interval (datetime) | + +-----------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-ConfigurationandInstrumentationContentMessages"><title> + Configuration and Instrumentation Content Messages + </title> + + <para> + Content messages are published when changes are made to the + values of properties or statistics or when new management clients + bind a queue to the management exchange. + </para> + <programlisting> + +-----+-----+-----+-------+-----------------------+ + | '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) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + | presence bitmasks (0 or more uint8 fields) | + +-----+-----+-----+-----+-----+-----+-----+-----+------------------------+ + | config/inst values (in schema order) | + +------------------------------------------------------------------------+ +</programlisting> + <para> + 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. + </para><para> + 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). + </para><para> + 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. + </para><para> + 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". + </para><para> + The element values are encoded by their type into the message in + the order in which they appeared in the schema message. + </para> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-GetQueryMessage"><title> + Get Query + Message + </title> + + <para> + 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. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'G' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | Get request field table | + +----------------------------------------------------------+ +</programlisting> + <para> + The content of a get request is a field table that specifies what + objects are being requested. Most of the fields are optional and + are available for use in more extensive deployments. + </para><table><title/><tgroup cols="4"> + <tbody> + <row> + <entry> + <emphasis>Field Key</emphasis> + </entry> + <entry> + <emphasis>Mandatory</emphasis> + </entry> + <entry> + <emphasis>Type</emphasis> + </entry> + <entry> + <emphasis>Description</emphasis> + </entry> + </row> + <row> + <entry> + "_class" + </entry> + <entry> + yes + </entry> + <entry> + short-string + </entry> + <entry> + The name of the class of objects being requested. + </entry> + </row> + <row> + <entry> + "_package" + </entry> + <entry> + no + </entry> + <entry> + short-string + </entry> + <entry> + The name of the extension package the class belongs to. If + omitted, the package defaults to "qpid" for access to + objects in the connected broker. + </entry> + </row> + <row> + <entry> + "_agent" + </entry> + <entry> + no + </entry> + <entry> + uuid + </entry> + <entry> + The management agent that is the target of the request. If + omitted, agent defaults to the connected broker. + </entry> + </row> + </tbody> + </tgroup></table><para> + 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. + </para> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-MethodRequest"><title> + Method Request + </title> + + <para> + 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. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'M' | seq | + +-----+-----+-----+-----+-----------------------+ + | objectId (uint64) | + +-----------------------------------------------+ + | methodName (str8) | + +-----------------------------------------------+------------------------+ + | input and bidirectional argument values (in schema order) | + +------------------------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-MethodResponse"><title> + Method + Response + </title> + + <para> + 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). + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'm' | seq | + +-----+-----+-----+-----+-----------------------+ + | status code | + +-----------------------+----------------------------------+ + | status text (str8) | + +-----------------------+----------------------------------+-------------+ + | output and bidirectional argument values (in schema order) | + +------------------------------------------------------------------------+ +</programlisting> + <para> + <emphasis>status code</emphasis> values are: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + 0 + </entry> + <entry> + STATUS_OK - successful completion + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + STATUS_UNKNOWN_OBJECT - objectId not found in the agent + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + STATUS_UNKNOWN_METHOD - method is not known by the object + type + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + STATUS_NOT_IMPLEMENTED - method is not currently + implemented + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-MessagesforExtendedScenario"><title> + Messages + for Extended Scenario + </title> + + <section role="h4" id="ManagementDesignnotes-ExtendedManagementProtocol"><title> + Extended + Management Protocol + </title> + + <para> + 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. + </para> + <programlisting> + Broker Remote Agent + | | + | <----------------------------------------- Attach Request --- | + | --- Attach Response ----------------------------------------> | + | | + | <------------------------------------- Package Indication --- | + | <------------------------------------- Package Indication --- | + | | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | | + | --- Schema Request (class key) -----------------------------> | + | <---------------------------------------- Schema Response --- | + | | + | --- Schema Request (class key) -----------------------------> | + | <---------------------------------------- Schema Response --- | + | | + | | +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-ExtendedOpcodes"><title> + Extended + Opcodes + </title> + + <table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>opcode</emphasis> + </entry> + <entry> + <emphasis>message</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + 'P' + </entry> + <entry> + Package Query + </entry> + <entry> + This message contains a schema package query request, + requesting that the broker dump the list of known packages + </entry> + </row> + <row> + <entry> + 'p' + </entry> + <entry> + Package Indication + </entry> + <entry> + This message contains a schema package indication, + identifying a package known by the broker + </entry> + </row> + <row> + <entry> + 'A' + </entry> + <entry> + Agent Attach Request + </entry> + <entry> + This message is sent by a remote agent when it wishes to + attach to a management broker + </entry> + </row> + <row> + <entry> + 'a' + </entry> + <entry> + Agent Attach Response + </entry> + <entry> + The management broker sends this response if an attaching + remote agent is permitted to join + </entry> + </row> + <row> + <entry> + 'x' + </entry> + <entry> + Console Added Indication + </entry> + <entry> + This message is sent to all remote agents by the management + broker when a new console binds to the management exchange + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-PackageQuery"><title> + Package Query + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'P' | seq | + +-----+-----+-----+-----+-----------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-PackageIndication"><title> + Package + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'p' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | package name (str8) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-AttachRequest"><title> + Attach Request + </title> + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'A' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | label (str8) | + +-----------------------+----------------------------------+ + | system-id (uuid) | + +-----------------------+----------------------------------+ + | requested objId bank | + +-----------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-AttachResponse-28success-29"><title> + Attach + Response (success) + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'a' | seq | + +-----+-----+-----+-----+-----------------------+ + | assigned broker bank | + +-----------------------+ + | assigned objId bank | + +-----------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-ConsoleAddedIndication"><title> + Console Added + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'x' | seq | + +-----+-----+-----+-----+-----------------------+ +</programlisting> + + + + <!--h4--></section> + <!--h3--></section> + <!--h2--></section> + + +</section> + |