SENSE Architecture & Specification: Appendices

V0.13 RBLandau 19960519

Appendix A:

Error Codes

All SENSE API entry points return status codes of C data type 'int'. If the status return is non-zero, it represents an error, or at least a warning, as specified below.

Appendix B:

Reserved Properties

Why Do We Need Reserved Properties?

To enable vendors to build interoperable Publisher and Subscriber applications, most of the standard SENSE objects have some special properties that should be present and shall be named according to the following conventions.

Reading any of the reserved property names will always return a value and never return an error (except in the case of an access control violation). If the property has not been declared and given a value in the Server, then the Client API shall return an appropriate null value, a zero-length string.

Reserved Property Names

Some properties apply to many objects. The "Id" property group contains any property that might, arguably, apply to any SENSE object; that is, its name begins with the prefix "Id." Some properties may be specific to certain object types, and will be named appropriately.

In general, not all properties will be supplied for all objects. If a Client retrieves a property that is not defined, the result is, in general, a NULL pointer; in cases where the caller has already supplied memory for a value, the returned value is a zero-length (null-terminated or counted, depending on the interface) string.

Appendix C:

Configuration Options

Where is the Publisher located?

The Publishers for an managed object in the network may be inside the object or outside it, logically or physically.

• A Publisher may be external to a managed object, that is, not integrated with the object, but added on externally. In this case, it must have a channel to the device through which it can get status information from the object and through which it can detect significant events in the object.
• Example: Many network devices implement a mechanism for detecting the status of the device through a management channel that is not synchronized with its data channels; for instance network printers may implement protocols such as SNMP, CPAP, or NPAP that can be used to determine the status of the device without synchronizing with the data stream(s) to the controller. Using this capability, a Publisher can be constructed as an external program that runs on some computing platform in the network.
  Using SNMP, for example, the Publisher can poll the device, and can subscribe to SNMP traps if the device implements any traps, and then can publish one or more Editions of the device's Publication that give information about the device. Other interested applications can subscribe to these Editions in the local SENSE Server, and need not poll the device directly.
  Note in this case that the device status is still being measured by polling over the network, so there is still some network traffic and some event latency. However, since only one agent is polling, namely the Publisher application, network traffic is greatly reduced and scales well. Also, since only one agent is polling the device, the polling interval can be adjusted if necessary to provide acceptable event latency.
• A Publisher may also be integrated into a managed object so that it can directly detect status and significant events of the object without using any external communications medium. The communications channel between the Publisher and the rest of the device still exists, but it is hidden. It may be any sort of public or proprietary mechanism. The important aspect of integration is that the communications be entirely "inside the box" and undetectable from the outside. How the Publisher is integrated with the device controller is vendor- and implementation-specific.
• A Publisher "inside the box" may have direct access to the data structures of the controller, for instance, or may use SNMP or some other communications mechanism over an internal bus, etc. It is only important that the communications not appear on the network outside the box.

Where is the Server located?

Servers, like Publishers, can be located inside a device or external to it in the network, both logically and physically.

• If a device contains a Publisher, it may also contain a Server. In this case, to conserve limited resources in the device, the Server may be dedicated to the needs of the Publisher for this one device; that is, the Server may deny requests to register new Publications or Editions.
• Note that if the embedded Server does not accept additional Editions for its Publication(s), then Editions produced by external Publishers for the same Publication(s) will be forced to appear on different Servers. This canmake it much more difficult for Clients to find all Editions for a given Publication.
• If a device contains a Publisher but no Server, then the Publisher must be configured with the location of the Server(s) in which it should publish.

If a large number of devices in a network include Servers, then the large number of servers can cause management problems.

• If there are many Servers, each with knowledge of only a small number of Publications, then Clients may have difficulty discovering all the Publications.
• A large number of Servers may represent a significant management burden for some sites.

In any case, a site may wish to reduce the number of servers to simplify management, simplify configuring Subscriber Clients, and to simplify the process of discovery by Clients. Sites can tailor the number and location of Servers, and the availability of Publications and Editions, using the Replicator application, described below. System managers can trade off management effort, vulnerability, difficulty of installing new devices, difficulty of configuring clients, etc., to suit local preferences.

Types of Managed Devices

A managed device may or may not contain SENSE components.

1. A device may contain no SENSE components, that is, both the SENSE Publisher and the SENSE Server are external to the device. An external Publisher may be responsible for more than one device.
2. A device may contain a SENSE Publisher that publishes one or more Editions for the device.
3. A device may contain both a SENSE Publisher and a SENSE Server. The internal server may be specialized to the device, that is, the Server may refuse to accept other Publications or other Editions for the device's Publication.

How many servers in a network?

The system manager can control, to a great extent, the configuration of SENSE Servers in the local network. The number and location of Servers can be controlled to trade off, for instance, the difficulty of installing new devices against the difficulty of installing new clients. (A tool for controlling the configuration is the Replicator Application, described below.) The SENSE network can be tuned to local needs, system management style, and network management style.

Below is a partial list of considerations in configuring a SENSE network.

How do clients find servers?

Discovery of network objects is not a simple problem, and no single strategy is likely to be suitable for all situations. Most implementations may combine several strategies for finding servers.

The list below includes several possible strategies, from high tech to low tech, that might be useful to SENSE clients. (This list is only suggestive, not exhaustive.)

High technology is nice to have, but it requires a lot of network support and management. If some high tech solutions are not available in some configurations, or if high tech solutions need to be supplemented with simpler solutions that require less management, one can fall back to lower-tech solutions.

1. Name Service. Adapt or establish conventions for storing the names of interesting entities. Publish the list of SENSE server addresses in the global name service, local name service, domain or cell directory service, whatever.
2. Association: Some network entities may be associated with others in peer or hierarchical relationships. For instance, Servers might share information with other Servers, and therefore they might maintain lists of other active Servers.
3. Advertising. Servers use a "service advertising" protocol, such as Novell SAP or similar, to advertise their presence and services offered. Clients listen for advertising messages from servers theyre interested in.
4. Broadcast and Reply. Design a specialized broadcast message that SENSE clients and servers answer. This is the method used by the Mac Chooser to locate printers, namely broadcasting a "Hey, all you LaserWriters out there!" message. Similarly, the newly proposed "Service Locator Protocol" uses a specialized multicast message to which the appropriate servers respond.
5. Systematic Ping. Algorithmically go through all "local" IP (or other network) addresses, asking if they have a SENSE server. This strategy is limited to servers on well-known ports, but that is probably not a serious limitation.
6. Configuration Files. Put well-known files in well-known locations containing the addresses of servers. It is typical to have a hierarchy of files, ranging from shared file(s) maintained by a system manager to local file(s) on each client system.

Note that the information the clients seek can be either static or dynamic, that is, either the clients read statically defined information, or they actively solicit dynamic information from the network. Static information may come either from a central name service or from distributed configuration files. Dynamic information may come either from passively listening to the network or from actively asking the network.

The Replicator/Repeater Application

A SENSE Client application can be a Subscriber and a Publisher simultaneously. This feature enables two applications that permit unusual flexibility in configuring a SENSE network: the Replicator and the Translator.

The Replicator subscribes to Editions in one Server and publishes them unchanged in another Server, or in several other Servers. In general, a Replicator should reproduce all Editions for a Publication that it is replicating, but in some special circumstances it may be desirable to configure a Replicator to eliminate some Editions.

A Replicator can be used in two very different ways:

• As a concentrator (fan-in): a Replicator can gather Publications from many Servers and republish them in a single Server. Additional Servers can be used as backups, if necessary. If Replicators are used to concentrate all Publications in a Server, then Client applications can easily find any Publications and Editions they want.
• As a distributor (fan-out): A Replicator can gather Publications from one or more Servers and republish them in a number of other Servers. In this configuration, a number of Servers can carry the same "product line" and thus share the load of many Subscriber applications. Servers with the same content can be positioned in the network geographically or topologically to minimize network congestion, management effort, or other local considerations.

Replicators can be used by system managers to configure the SENSE servers in the network in very general ways.

The Translator Application

The Translator application subscribes to Editions in one Server and publishes them in a different form, in the same server, in another Server, or in several other Servers.

• A Translator may enhance an Edition by extracting content from the messages and adding properties to the messages.
• A Translator may transform the opaque section of the Event messages from one data syntax to another. For instance, a Translator could change SNMP TRAP or NPAP condition messages into some other notification format.
• A Translator may filter Event messages to select a subset of the stream of Events.

Translators can be used to produce specialized Editions for specialized monitoring applications, even though primary Publishers for those Editions may not be available for some devices.

How do Servers Deal with Multiple Network Protocols?

They don't. A SENSE Server uses only one network discipline at a time. That is, a SENSE Server may be capable of using IP, or IPX, or AppleTalk, but any instance of the Server is statically configured to use one network stack.

Appendix D:

The Server's Publication

Every SENSE Server contains a Publication that represents the Server itself, and publishes several Editions detailing events within the Server.

The Server Publication is distinguished by the following properties. See Appendix B for further details.

Servers shall include the following properties in the Server Publication.

The Server Publication includes several Editions. All Servers shall publish at least the following editions.

Appendix E:

Editions of Publications

An Edition of a Publication is a specific format and subset of event messages relating to that entity. Generally, an Edition includes a specific type of opaque data and a specific set of properties that describe the event and the resulting condition of the entity. Together these two specifications describe the format of SENSE Event messages of this Edition.

Event Protocols are typed with respect to the syntax and content of the information conveyed within Event messages. Several protocols have subtypes that further delineate syntax and/or content aspects of the Event messages.

The official names of each Event Protocol described below are used as the keywords for the DATA property present in each Event message. In effect, these names serve as a classing mechanism that is typically used by a SENSE Client to distinguish among the various Event Protocols associated with a Publication Edition. Therfore, if an Edition is published in one of these protocols, the Publisher shall use the string given here as the first atom of the value of the Edition property Id.Name.

Event Protocol names are structured using the standard "dotted octet" form that provides a visual and processable form of class hierarchy. A collection of Event Protocols that compose a particular hierarchy are referred to as an "Edition set" in this document.

Appendix F:

Server Management Properties

The SENSE Server is also a manageable object in the network, and can be managed through the client management interface. After passing local security screens, a Manager Client can modify the properties and operation of the Server.

Properties of the Server object

Appendix G:

The SNMP.TRAP Edition

Properties of the Edition

Syntax of Opaque Data in Event Messages

For this edition, the opaque data in each event message is an SNMP V1 TRAP-PDU. The trap message should be precisely what would be delivered to a process by the UDP service on the client platform for a real SNMP TRAP message.

The TRAP message shall contain whatever fields are required by the NOTIFICATION-TYPE macro that defines the message for this type of trap. The cause of the trap, the TrapOID, etc., depend on the device and the event.

Properties Included in Event Messages

Publishers shall include the following Publication properties in every Event Message of this Edition.

Publishers may also include other Publication and Edition properties in Event Messages.

Appendix H:

The Minimal Edition of a Publication

For some devices, it may be desirable to publish a minimal Edition of the Publication that reports changes in the overall "condition" of the device. Such an edition can be used for very simple green-yellow-red-light status monitoring applications.

Properties of the Edition

Syntax of Opaque Data in Event Messages

The minimal Edition of a Publication contains no opaque data. The length of the opaque data region of the message is zero.

Properties Included in Event Messages

Publishers shall include the following Publication properties in every Event Message of this Edition.

Publishers may also include other Publication and Edition properties in Event Messages.

Appendix I:

Server-Supplied Properties in Event Messages

The SENSE Server adds several properties to an Event message in an Edition when it forwards the message to Subscribers of that Edition. The Server includes enough identifying information that the Subscriber can uniquely identify the message source, and can recognize duplicate messages in the case of retransmissions.

Appendix J:

Condition Codes

The property Condition.Code contains a composite value that is encoded as described in this section. The condition code is a three-digit value that contains three sub-codes. In order from right to left, from least-significant digit to most-significant digit, the sub-codes represent Activity (values 0-9), Health (values 0-4), and Support (values 0-5).

Additionally, the three-digit general condition code may be prefixed with a vendor code. The format of vendor codes is vendor-specific. If a vendor code is present, all three digits of the condition code must be specified, including leading zeros, so that the general condition code and vendor code may be unambiguously distinguished.

[[more tbs]]

The "Support" code describes the level of human expertise required to resolve a problem, ranging from basic familiarity with the device to trained hardware or software service skills.

The "Activity" code describes the recent level of activity in the device, from idle to very busy. In many devices, there may not be sufficient history to evaluate this property in detail. If the Publisher does not have the data necessary to make find distinctions, it should indicate only that the device is "idle" or "not idle." If the Publisher has no data about device activity, it should indicate "unknown."

The "Health" code describes the ability of the device to continue processing without receiving attention or service.

[[many examples tbs]]

Appendix K:

Classes of SENSE Objects

The Id.Class property of a Publication can be used to distinguish quickly the type of network entity that the Publication represents. This property is used in the ObjectGetFirst() API function to restrict the search to a particular class of Publications.

SENSE objects other than Publications also use the Id.Class property to distinguish these objects in the ObjectGetFirst() function. Note that enumerating certain classes of objects, such as Clients, may be subject to security constraints in some implementations.