11.1 What is an Agent Schema?

An agent schema is a data description that characterizes an agent's capabilities. It publishes agent interface information to management processes that submit requests and receive results. It may be used to interpret results from the agent.

While the terms "agent schema" and "schema file" are sometimes used interchangeably, they refer to slightly different things. The "agent schema" refers to the data description of a single agent. The term "schema file" is more generic--it refers to a file that may contain one or more descriptions.

11.2 Agent Schema Attributes

Managed objects are characterized by attributes. Attributes are variables an agent can get and set for a manager application. Attributes are characterized primarily by a data type (see Table 11-1 or consult the definition for the enumerated type snmdb_type in netmgt_db.h, located in /usr/snm/include/netmgt for SunOS 4.x machines or at /opt/SUNWconn/snm/include/netmgt for Solaris 2.x installations) and an agent-defined name. Attributes often have other associated information (for example, an extended textual description).

See the Administration Guide for a list of agents for the Solaris 1.x and 2.x versions of the products and any attribute changes made to them.

Because an agent can supply many attributes, a mechanism exists to collect them into logically-related sets called groups.

Certain kinds of groups known as tables have multiple instances of a given logically-related set. Consider a group of attributes that apply equally to a set of distinct interfaces or devices managed by an agent--such as the data for a group of RS-232-C ports. A particular instance of a table is identified by an associated key.

The first steps in writing an agent schema are defining the "attributes" (for example, variables, counters, state and error information) that you want your agent to collect, and naming and selecting data types for the attributes. Table 11-1, lists the defined data types.

Table 11-1

Agent Schema	Service Library	C-language	Description
short	NETMGT_SHORT	short	16-bit integer
unsigned short	NETMGT_U_SHORT	unsigned short	unsigned 16-bit integer
int	NETMGT_INT	int	32-bit integer
unsigned int	NETMGT_U_INT	unsigned int	unsigned 32-bit integer
long	NETMGT_LONG	long	32-bit integer
unsigned long	NETMGT_U_LONG	unsigned long	unsigned 32-bit integer
float	NETMGT_FLOAT	float	32-bit floating point
double	NETMGT_DOUBLE	double	64-bit floating point
string[n]	NETMGT_STRING	char *	null-terminated ASCII string; <n> sets maximum size; length includes the null terminator
ipaddress	NETMGT_INADDR	u_char[4]	32-bit IP address (represented by an octet 1 string of length 4, in host byte order)
unixtime	NETMGT_UNIXTIME	long	signed long, number of seconds since Jan 1, 1970
enum enumtype	NETMGT_ENUM	enum	enumeration
octet[n]	NETMGT_OCTET	char[n]	opaque stream of <n> 8-bit bytes, not necessarily null-terminated
netaddress	NETMGT_IP_ADDRESS	u_char[4]	32-bit IP address (represented by an octet1 string of length 4, in network byte order)
objectid	NETMGT_OBJECT_IDENTIFIER	u_long[n]	RFC 1065 object identifier
counter	NETMGT_COUNTER	unsigned int	unsigned integer, only increments, wraps after 32 maximum value (2 -1)
gauge	NETMGT_GAUGE	unsigned int	unsigned integer, may either increment or32 decrement, latches at maximum value (2 -1)
timeticks	NETMGT_TIMETICKS	unsigned int	unsigned integer, elapsed time since some referenced event (in hundredths of seconds)

1 While an IP address can be represented in host byte order, network byte order should be used to ensure correct operation with all management applications.

11.3Agent Schema Syntax

After the attributes have been selected, the agent schema can be written. The examples shown in this section are arranged in the following top-down logical order:

• Naming and describing the agent.
• Naming and describing any agent specific enumerations.
• Naming and describing the agent's groups and tables.
• Naming and describing the attributes in each group or table.
• Naming and describing the agent-specific errors.

11.3.1 Syntax Rules

Use the following rules when defining an agent schema:

• Names may be any character above ASCII 0x20 (space). The following special characters must be enclosed in quotes if used: space, tab, left and right parenthesis, left and right brackets, and pound ("#").
• A pound sign (#) causes the remainder of the line to be treated as a comment.
• Strings are enclosed in double quotes. Repeat the double quote character (for example "") to include a double quote inside a string.
• Spaces, tabs and newlines (\n) are the token delimiters. All are equivalent when parsing a schema. Use them to improve the readability of your agent schema.
• If an argument string passed to snm_cmd contains spaces (ASCII 0x20), these will be treated as delimiters and the substrings on either side of the spaces will be interpreted as separate arguments.

11.3.2 Conventions

The agent schema descriptions shown in this section use the following conventions:

• Bold font indicates a keyword.
• Italic font indicates text you supply or fill in.

• An ellipsis (...) indicates zero or more occurrences of the preceding item.
• A vertical bar | inside braces { } indicates a choice of keywords.
• Brackets [ ] indicate an optional item.

11.3.3 Defining an Agent

An agent description consists of naming the agent, optionally giving it descriptive text, its serial number and RPC number, specifying its enumerations, groups, and tables, and optionally specifying its error return codes and messages. The syntax is:

{agent | proxy} <agentName> [ description "descriptive text" ] [ rpcid <program_number> ] [ serial <serial_number> ] ( [ agent specific enumeration descriptions ] group/table description ... [ agent error description ] )

where

{ agent | proxy }

is a keyword identifying this structure as an agent schema. A proxy agent is an "intermediate" agent that can carry out requests for another system (for example, a ping agent or an SNMP agent).

<agentName>

is the name of the agent schema as it appears in the agent schema list in the Element Properties window in the Console. <agentName> has a maximum length of 64 characters.

description

keyword that introduces descriptive text providing documentary information on this agent.

"<descriptive text>"

is the user-supplied text. This description appears in the agent schema list of the Element Properties window in the Console. The descriptive text has a maximum length of 1024 characters. (Note that the schema parser does not recognize any continuation conventions. All characters--including newlines (\n)--are included in the text up to the closing quote.)

rpcid

keyword that indicates that the RPC program number follows.

<program_number>

is the RPC program number of the agent. If specified, the Console and set tool use this number when making agent requests rather than consulting the NIS/NIS+ service or the rpc file (located in /etc on SunOS 4.x machines, or in /etc/opt/SUNWconn/snm in Solaris 2.x installations).

serial

keyword that indicates that the serial number follows.

<serial_number>

is the version number of the agent, beginning with 1 and increasing for each release of the agent. This is not the RPC version number, but a method for ensuring that the agent and its schema file are in sync. In the current release, the snm and snm_cmd managers do not look at this information.

<agent specific enumeration descriptions>

list of agent-specific enumeration definitions. See the discussion in Section 11.3.4, "Defining an Agent Enumeration."

<group/table description>

list of group or table descriptions. See the discussion in Section 11.3.5, "Defining a Group and Table," on page 11-8.

<agent error description>

list of errors returned by the agent. See the discussion in Section 11.3.7, "Defining an Agent Error," on page 11-11.

The following example shows the agent portion of the sync agent schema. The complete sync agent schema can be found in Section 11.5, "An Example Agent Schema," on page 11-12. "

agent sync description "synchronous interface stats" serial 1 rpcid 100104 ( ...

11.3.4 Defining an Agent Enumeration

If any of the attributes of any agent are enumerated types, the enumeration should be defined in the agent schema. An agent schema may define zero or more agent-specific enumerations. The scope of an agent-specific enumeration is confined to the agent. The format is as follows:

enum <enumerationName> ( integer "<enumeration text>" ... )

where

enum keyword specifying an enumeration declaration.

<enumerationName>

name of the enumeration. An enumeration name has a maximum length of 64 characters.

integer "<enumeration text>" specifies the mapping between an enumeration value and the <enumeration text> describing that member of the enumeration. An enumeration may contain up to 20 members. Each <enumeration text> has a maximum length of 64 characters.

For example, the following enumeration defines a boolean:

enum boolean ( 0 "False" 1 "True" )

11.3.5 Defining a Group and Table

A group or table description consists of the group or table name, optional descriptive text, and a list of attributes. Group and table descriptions have the following syntax:

{ group | table } <groupname> [ description "<descriptive text>" ] ( <attribute description> ... )

where

{ group | table }

keyword that specifies a group or table.

<groupname>

user-defined group or table name. This name is put into a namespace unique to this agent. Group and table names within a single agent description must be unique. A group or table name can have a maximum length of 64 characters.

description

keyword introducing descriptive text about a group or table.

"<descriptive text>" describes the group or table and can have a maximum length of 1024 characters.

<attribute description>

list of attribute descriptions. See the discussion in Section 11.3.6, "Defining an Attribute."

The following example shows the agent and group/table sections from the example sync agent schema. The attribute definitions are indicated with an ellipsis (..).

agent sync description "synchronous interface stats" serial 1 rpcid 100104 ( table mode description "synchronous interface" ( ... ) table data description "I/O statistics" ( ... )

11.3.6 Defining an Attribute

An attribute description consists of an attribute type specification (see Table 11-1 on page 11-3), the attribute name, and optional descriptive text. Attribute descriptions have the following syntax:

read/write <type name> [ description "<descriptive text>" ] [ units <unit type> ]

where

read/write
  specifies the read/write status of the attribute. The four possible read/write
  parameter values are:

. readonly or ro	the attribute can be read
. readwrite or rw	the attribute can be read or set
. writeonly or wo	the attribute can only be set
. notaccessible or na	the attribute cannot be read or set

Either the full word or the abbreviation can be used. If no read/write parameter is present in an attribute definition, the attribute is assumed to be readonly.

<type>

is an agent schema type listed in Table 11-1 on page 11-3. String and octet types require a length specifier to declare the maximum size of the string.

An enumerated type is specified with the keyword enum followed by the enumeration type.

<name>

is the user-defined name of this attribute. Each group or table defines its own namespace in which names must be unique. However, the same name may occur in different groups or tables. A name has a maximum length of 64 characters.

description

keyword that introduces descriptive text providing documentary information about an attribute.

"<descriptive text>" describes the attribute and can have a maximum length of 1024 characters.

units

keyword identifying a unit for a particular attribute.

<unit type>

optional clause specifying the units for a particular attribute. Currently this field is not used by the Console. It is described here for other manager applications. The maximum length is 1024 characters.

Below are some example attributes taken from the sync agent schema.

string[32] ifname description "interface name" enum tx txclock description "transmit clock source" int iutil% description "input utilization" units "percent"

11.3.7 Defining an Agent Error

If an agent wishes to return agent-specific errors, they should be defined in the agentErrors section of the agent schema. This section defines a table of error numbers and associated error messages specific to a particular agent. The error numbers are represented by integers and the error messages are descriptive text enclosed in double quotes. Defining errors in the schema file localizes error messages to aid in making agents multinational.

The agentErrors section has the following syntax:

agentErrors ( <integer> "<error text>" ... )

where

agentErrors

is the keyword that identifies agent-specific errors.

<integer> "<error text>"

specifies a mapping between an agent-specific error code <integer> and <error text>. The error text has a maximum length of 1024 characters.

The following example shows the agentErrors excerpt from the sync agent schema.

agentErrors ( 1 "No synchronous interface on this host" 2 "Error in SIOCGIFCONG ioctl system call" 3 "This key is not a synchronous interface" )

11.4Schema File Conventions

By convention, the agent schema normally resides in the same directory as the agent. To be loaded by the Console, the agent schema file name must end with .schema.

At start-up time the Console may be instructed to reinitialize its runtime management database. A step in doing this is to load all agent schema. The schemas keyword in /etc/the snm.conf file contains a list of schema file directories. (The snm.conf file is located in the /etc directory on SunOS 4.x machines and in /etc/opt/SUNWconn/snm in Solaris 2.x environments.) Any file ending with .schema in those directories is assumed to be an agent schema and is loaded into the runtime database.

Agent schema may also be read into the Console using the File button Load option.

11.5An Example Agent Schema

The following section contains an abbreviated example of the agent schema for the sync agent. This agent returns statistics on synchronous serial ports.

agent sync # Agent declaration description "synchronous interface stats" # serial 1 rpcid 100104 ( enum tx ( # Agent specific 0 "incoming transmit clock" # enumeration declarations 1 "incoming receive clock" 2 "baud rate generator" 3 "phase-lock loop output" ) enum rx ( 0 "incoming receive clock" 1 "incoming transmit clock" 2 "baud rate" 3 "phase-lock loop" ) enum bool ( 0 "false" 1 "true" ) table mode # Group/table declarations description "synchronous interface table (key on ifname)" ( string[32] ifname description "interface name" enum tx txclock description "transmit clock source" enum rx rxclock description "receive clock source" enum bool loopback description "do internal loopback" unsigned int baudrate description "interface speed" )

table data description "I/O statistics table (key on ifname)" ( string[32] ifname description "interface name" long ipkts description "input packets" long opkts description "output packets" int ibytes description "input bytes" int obytes description "output bytes" int iutil% description "% input utilization in the last timeperiod" units "percent" int outil% description "% output utilization in the last time period" units "percent" long aborts description "aborts" long crcs description "crc errors" long over description "receiver overruns" long under description "transmitter underruns" ) agentErrors ( # Agent specific error 1 "No synchronous interface on this host" # declaration 2 "Error in SIOCGIFCONG ioctl system call" 3 "This key not a synchronous interface" ) )

11.6Mapping Feature

The following discussion describes mapping, an advanced feature for agent writers.

When a user makes a request, the Console builds a request record that sets the parameters for the request. The Console has a set of defaulting rules that it uses to build the request record. Because these rules might not be correct for some agents, the Console provides a mapping mechanism by which an agent writer may force one or more fields of the request to be set from fields in the element's properties. This is done by adding a map line into the agent schema file. The map line has the following syntax:

map "<req_obj_field1>=<prop_field1>[,<req_obj_field2>=<prop_field2>]"

where

map

keyword indicates one or more mappings are desired.

<req_obj_field>

name of a field in the request record.

<prop_field>

name of a field in the element properties.

Each map string can be a maximum of 1024 characters.

The map entry immediately follows the "agent description"--see the following example:

agent XYZagent description "An agent that talks to XYZ elements" map "_targetsystem=Real_Name" ( ... )

---

Note - The mapping occurs when the Property Sheet is brought up for a new request or when a "Quick Dump" request is launched. It does not occur when an existing request is modified.

---

For instance, consider an element of the following type:

record component.notASun ( string[32] Name # Name of the system string[32] Real_Name # Its real name )

If a request for the XYZ<agent> was launched from a element of type component.notASun, then the field <_targetsystem> in the request would be set from "Real_Name."

To understand how to use mapping, an agent writer must understand how the request record fields are used to build a request sent to the agent. There are two types of request records, one for data requests and the other for event requests. These fields are in the "dataRequest" and "eventRequest" records as defined in the file /snm.glue. (The snm.glue file is located in the directory /usr/snm/struct for the SunOS 4.x version of this product and in /opt/SUNWconn/snm/struct for the Solaris 2.x version.)

The next table shows the fields in the request record, describes how they are used to build an agent request, and describes their default values when no mapping is specified.

Field	Usage or Default Rule
Name	Provides the name of the request. The name is displayed below the request glyph. This field is not seen by the agent. The default is a name of the form: <agent-name>.<group-name>.<n> where <n> is a number
_targetsystem	Provides the <system> value for a request. By default, this field is set to the Name field from the request's element object. If the field <Proxy_System> is NULL, this field also provides the name of the system to contact (for example, the system on which the agent runs).
Key	Provides the <key> value for a request. By default, this field is set to NULL.
Options	If not NULL, provides the <options> value for a request. By default, this field is set to NULL.
Proxy_System	If not NULL, provides the name of the system on which the agent resides. By default, this field is set to NULL for agents that are not defined as proxy agents. For proxy agents, this field is set to the value of the <proxy> field in the proxy subrecord of the request's system object.