diff options
Diffstat (limited to 'qpid/doc/book/src/old/Management-Design-notes.xml')
| -rw-r--r-- | qpid/doc/book/src/old/Management-Design-notes.xml | 2136 |
1 files changed, 0 insertions, 2136 deletions
diff --git a/qpid/doc/book/src/old/Management-Design-notes.xml b/qpid/doc/book/src/old/Management-Design-notes.xml deleted file mode 100644 index 76f0dac926..0000000000 --- a/qpid/doc/book/src/old/Management-Design-notes.xml +++ /dev/null @@ -1,2136 +0,0 @@ -<?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> - |