11 - Writing an Agent Schema

1. Convert the information into a set of attributes.

2. Choose a name and data type for each attribute.

3. Arrange the attributes into logically related sets.

Section 11.2, "Agent Schema Attributes ," describes agent schema attributes.

4. Write the agent schema.

This consists of defining the agent, defining any agent-specific enumerations, defining the groups/tables, defining the attributes, and defining any agent-specific errors.

Section 11.3, "Agent Schema Syntax ," describes the agent schema syntax.

5. Name the completed agent schema and place it in the appropriate directory so it can be used by the manager.

Section 11.4, "Schema File Conventions ," describes agent schema file name conventions.

11.1 What is an Agent Schema?

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

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 Data Types

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 string of length 4, in host byte order)1
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 octet string of length 4, in network byte order)1
objectid	NETMGT_OBJECT_IDENTIFIER	u_long[n]	RFC 1065 object identifier
counter	NETMGT_COUNTER	unsigned int	unsigned integer, only increments, wraps after maximum value (232-1)
gauge	NETMGT_GAUGE	unsigned int	unsigned integer, may either increment or decrement, latches at maximum value (232-1)
timeticks	NETMGT_TIMETICKS	unsigned int	unsigned integer, elapsed time since some referenced event (in hundredths of seconds)

¹ 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.3 Agent Schema Syntax

• 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

• 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

• 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

{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).

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.

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

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.)

keyword that indicates that the RPC program number follows.

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/sn m in Solaris 2.x installations).

keyword that indicates that the serial number follows.

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.

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

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

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

agent sync				 

  description "synchronous interface stats" 

  serial 1 

  rpcid 100104 

( 

	... 

"

11.3.4 Defining an Agent Enumeration

enum <enumerationName> ( 

integer "<enumeration text>" 

	... 

) 

where

enum

keyword specifying an enumeration declaration.

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

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.

enum boolean ( 

	0	"False" 

	1	"True" 

) 

11.3.5 Defining a Group and Table

{ group | table } <groupname> 

[ description "<descriptive text>" ] 

( 

	<attribute description> 

	... 

) 

where

{ group | table }

keyword that specifies a group or table.

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.

keyword introducing descriptive text about a group or table.

describes the group or table and can have a maximum length of 1024 characters.

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

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

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.

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.

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.

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

describes the attribute and can have a maximum length of 1024 characters.

keyword identifying a unit for a particular attribute.

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.

11.3.7 Defining an Agent Error

The agentErrors section has the following syntax:

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

where

agentErrors

is the keyword that identifies agent-specific errors.

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

11.4 Schema File Conventions

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.5 An Example Agent Schema

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.6 Mapping Feature

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.

name of a field in the request record.

name of a field in the element properties.

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.

---

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.

Copyright 1996 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All Rights Reserved