# Appendix E

| # URL Specifications

> This appendix covers the following topics:

- Uniform Resource Locator (URL)--page 623
- SNMP URLs--page 624
- Shadow Operations--page 627

## Uniform Resource Locator (URL)

> The Uniform Resource Locators (URLs) schemes employed in Sun Management Center software comply with the general URL format defined in the RFCs pertaining to URLs.

>     <scheme>://<net_loc>/<path>;<params>?<query>#<fragment>

> URLs are used by Sun Management Center components to access and interface with various resources. URLs are used to do the following:

- Access values and attributes of managed objects and properties in the Sun Management Center agent MIB via SNMP
- Interface with standard I/O file descriptors
- Interface with regular and circular log files
- Interface with other processes using pipes, UNIX, TCP and UDP sockets
- Interface with the UNIX system logging service (for example, syslog).

> The discussion of URLs is divided into SNMP URLs and interface URLs.

> > Note - Refer to the Client API chapter for information on Raw Data API and Create URL method on procedures of how to use these methods to build correct URLs within Client API programs. Refer to the Modules Appendix to get more information on converting OID URL to a valid OID.

## SNMP URLs

> The Sun Management Center components employ URLs to uniquely identify values and qualifiers of managed objects and properties in Sun Management Center agent MIBs. SNMP URLs permit a more readable representation of SNMP object identifiers (OIDs). These URLs can be resolved to the actual OID by querying the finder object residing in all Sun Management Center agents.

> For example, SNMP URLs can be used to access the value of a managed property stored in a Sun Management Center agent MIB such as the MIB-II system description.

> SNMP URLs can also access qualifiers associated with managed properties and managed objects. These qualifiers are also referred to as shadow attributes and the act of accessing these qualifiers are known as shadow operations. For example, the refresh attributes of a managed property like `refreshcommand` or `refreshinterval` can be accessed through shadow operations.

### SNMP URL Format

> The general format of the SNMP URL is shown below:

>     snmp://<host>[:<port>]/<type>/<spec>[?<query>][#<instance>]

> where

> snmp specifies the SNMP scheme

> <host> specifies the host on which the SNMP agent resides

> <port> specifies the port the SNMP agent is listening on

> <type> specifies the SNMP URL type which can be one of oid, sym, or mod

> <spec> will vary according to the type and specifies the data element being identified

> <query> specifies the shadow attribute being accessed

> <instance> specifies the managed property instance being accessed

### SNMP URL Types

> The following SNMP URL types are supported in Sun Management Center:

- Numeric type (oid) uses object identifiers (OIDs) to identify the MIB object
- Symbolic type (sym) uses the logical names to identify the MIB object
- Module type (mod) uses module, instance, and logical names to identify the MIB object Numeric

> Numeric SNMP URLs are specified using the oid type and are comprised of the subidentifiers (subIDs) of the MIB object they represent. Numeric SNMP URLs are easily converted to a SNMP request packet since they contain the object identifier (OID) specifications required to construct SNMP PDUs.

> These URLs have the following form:

>     snmp://<host>[:<port>]/oid/<subid1>[.../<subidN>] [?<query>][#<instance>]

> > Note - The separators between subIDs can be either slashes "/" or dots ".".

> For example, the value of the system description managed property in the MIB-II module can be accessed using the following numeric SNMP URL:

>     snmp://manila/oid/1/3/6/1/2/1/1/1#0
>     snmp://manila/oid/1.3.6.1.2.1.1.1#0

> Symbolic

> Symbolic SNMP URLs are specified using the sym type and are comprised of the hierarchical name of MIB object they represent. The objects named in the hierarchy can be from the root of the MIB tree (.iso) or relative to the base of the enterprises MIB object (.iso.org...private.enterprises).

> They have the following form:

>     snmp://<host>[:<port>]/sym/<name1>[.../<nameN>][?<query>][#<instance>]

> > Note - The separators between names can be either slashes (/) or dots (.). Also, a single slash (/) or a double slash (//) can follow the SNMP URL type, for example:
> > `snmp://<host>[:<port>]/sym//<name1>[.../<nameN>][?<query>][#<instance>]`
> > is the same as:
> > `snmp://<host>[:<port>]/sym/<name1>[.../<nameN>][?<query>][#<instance>]`

> The value of the system description managed property in the MIB-II module can be accessed using the following symbolic SNMP URL:

>     snmp://manila/sym/iso/org/dod/internet/mgmt/mib-2/system/sysDescr#0
>     snmp://manila/sym/iso.org.dod.internet.mgmt.mib-2.system.sysDescr#0

> The logical names must be resolved before an SNMP request packet is constructed. The names can be resolved to OIDs by performing a lookup in an URL/OID cache or by sending a finder request to the target agent. Once the symbolic SNMP URL is mapped to a numeric SNMP URL, the SNMP request packet can be built and sent.

> Module

> Module SNMP URLs are specified using the mod type and are comprised of the module specification and the hierarchical name of MIB object relative to the root of the module. The module specification consists of the module name and an optional instance specification, separated by a `+' sign.

> They have the following form:

>     snmp://<host>[:<port>]/mod/<module>[+<inst>]/<name1>[.../<nameN>] [?<query>][#<instance>]

> > Note - The separators between names can be either slashes "/" or dots ".".

> For example, the value of the system description managed property in the MIB-II module can be accessed using the following module SNMP URL:

>     snmp://manila:161/mod/mib2-instr/system/sysDescr#0

> The module names, instances names, and logical names must be resolved to OIDs before an SNMP request packet can be constructed. The names can be resolved to OIDs by performing a lookup in an URL/OID cache or by sending a finder request to the target agent. Once the module SNMP URL is mapped to a numeric SNMP URL, the SNMP request packet can be built and sent.

## Shadow Operations

> In addition to getting and setting the value of managed properties, SNMP URLs can also be used to access additional attributes of managed properties and managed objects, known as qualifiers.

> The set of qualifiers accessible through SNMP includes such things as alarm limits, refresh attributes, descriptions, and so forth. The complete list of available qualifiers for each managed object or property is listed in the file `base-shadowmap-d.x`.

> The shadow map is specified in a URL in the ?<query> specification.

> Some shadow map attributes support the specification of an index to access a specific instance of the shadow map attribute. For example, the status list shadow map allows the list of statuses associated with a managed object or property to be accessed. Specifying`?statuslist` alone as the query accesses the entire list. To access specific elements in the status list, `?statuslist.`N can be specified to access the Nth status. If the specified status instance does not exist, nothing is returned.

### SNMP URL Examples

> Examples of SNMP URLs for values of managed property and qualifiers of managed objects and properties are provided in this section. Each example is represented using numeric, symbolic (absolute and relative), and module type SNMP URLs.

> Managed Property Value (scalar)

> Managed properties represent the entities being monitored by the Sun Management Center agent. Managed properties that are scalars are specified by an instance specification of "#0".

> For example, the value of the Load Average Over The Last 1 Minute property in the Kernel Reader module can be accessed using the following URLs:

> Numeric SNMP URL

>     snmp://manila:161/oid/1.3.6.1.4.1.42.2.12.2.2.12.3.1#0

> Symbolic SNMP URL (absolute)

>     snmp://manila:161/sym/\
>     iso.org.dod.internet.private.enterprises.sun.prod.sunsymon.agent.modules.kernel
>     \Reader.load.avg_1min#0

> Symbolic SNMP URL (relative)

>     snmp://manila:161/sym/sun.prod.sunsymon.agent.modules.kernel-\
>     Reader.load.avg_1min#0

> Module SNMP URL

>     snmp://manila:161/mod/kernel-reader/load/avg_1min#0

Managed Property Value (vector)

> The Sun Management Center agent MIB can also model tabular entities. SNMP URLs support access to specific row entries in such tables through the use of instance specifications (for example, #<instance>).

> For example, the UFS Filesystem Usage statistics are represented by a table in the Kernel Reader module. Each file system partition constitutes a row in this table and partition's mount point name is used as the index. Thus, to access the value of the size (KB) managed property of `/cache` filesystem, the following URLs can be used:

> Numeric SNMP URL

>     snmp://manila:161/oid/1.3.6.1.4.1.42.2.12.2.2.12.6.1.1.1.4#/cache

> Symbolic SNMP URL

>     snmp://manila:161/sym/\
>     sun.prod.sunsymon.agent.modules.kernelReader.filesystem.ufsFilesystem.fileTable
>     \.fileEntry.ksize#/cache

> Module SNMP URL

>     snmp://manila:161/mod/kernel-reader/filesystem/ufsFilesystem/fileTable/\

>     fileEntry/ksize#/cache

Managed Property Qualifier (Scalar Property, Scalar Qualifier)

> Qualifiers associated with managed properties are also accessible using SNMP URLs. Managed property qualifiers are specified using the query specification (that is, ?<query>).

> For example, the refresh interval qualifier of the Load Average Over The Last 1 Minute property in the Kernel Reader module can be accessed using the following URLs:

> Numeric SNMP URL

>     snmp://manila:161/oid/\
>     1.3.6.1.4.1.42.2.12.2.2.12.3.1?refreshinterval#0

> Symbolic SNMP URL

>     snmp://manila:161/sym/\
>     iso.org.dod.internet.private.enterprises.sun.prod.sunsymon.\
>     agent.modules.kernelReader.load.avg_imin?refreshinterval#0

> Module SNMP URL

>     snmp://manila:161/mod/kernel-reader/load/\

>     avg_1min?refreshinterval#0

Managed Property Qualifier (Vector Property, Scalar Qualifier)

> Similarly, qualifiers associated with managed properties which are vectors are also accessible using SNMP URLs. These qualifiers are specified using the query
> (?<query>) and instance specifications (#<instance>).

> For example, the refresh interval qualifier of the size (KB) managed property for the /cache UFS partition in the Kernel Reader module can be accessed using the following URLs:

> Numeric SNMP URL

>     snmp://manila:161/oid/\
>     1.3.6.1.4.1.42.2.12.2.2.12.6.1.1.1.4?refreshinterval#/cache

> Symbolic SNMP URL

>     snmp://manila:161/sym/\
>     sun.prod.sunsymon.agent.modules.kernelReader.filesystem.ufsFile\
>     System.fileTable.fileEntry.ksize?refreshinterval#/cache

> Module SNMP URL

>     snmp://manila:161/mod/kernel-reader/filesystem/ufsFileSystem/\
>     fileTable/fileEntry/ksize?refreshinterval#/cache

Managed Property Qualifier (Vector Property, Vector Qualifier)

> Qualifiers associated with managed properties can themselves be vectors. Specific elements of the qualifier's vector list are specified using ?<query>.N to access the Nth element.

> For example, the alarm limit qualifier of managed properties is a vector since multiple alarm limits can be specified (for instance. info, warning, error). To access the first alarm limit of the UFS file system Percent Used managed property for the `/cache` partition in the Kernel Reader module, the following URLs can be used:

> Numeric SNMP URL

>     snmp://manila:161/\
>     1.3.6.1.4.1.42.2.12.2.2.12.6.1.1.1.7?alarmlimits.0#/cache

> Symbolic SNMP URL

>     snmp://manila:161/sym/\
>     iso.org.dod.internet.private.enterprises.sun.prod.sunsymon.\
>     agent.modules.kernelReader.filesystem.ufsFileSystem.fileTable.\
>     fileEntry.kpctUsed?alarmlimits.0#/cache

> Module SNMP URL

>     snmp://manila:161/mod/kernel-reader/filesystem/ufsFileSystem/\
>     fileTable/fileEntry/kpctUsed?alarmlimits.0#/cache

Managed Object Qualifier (Scalar Qualifier)

> Qualifiers associated with managed object are also accessible using SNMP URLs. Managed object qualifiers are also specified using the query specification (that is, ?<query>).

> For example, the refresh interval of the System Load Statistics managed object in the Kernel Reader modules can be accessed using the following URLs:

> Numeric SNMP URL

>     snmp://manila:161/oid/\
>     1.3.6.1.4.1.42.2.12.2.2.12.3?refreshinterval

> Symbolic SNMP URL

>     snmp://manila:161/sym/\
>     iso.org.dod.internet.private.enterprises.sun.prod.sunsymon.\
>     agent.modules.kernelReader.load?refreshinterval

> Module SNMP URL

>     snmp://manila:161/mod/kernel-reader/load?refreshinterval

Managed Object Qualifier (Vector Qualifier)

> Qualifiers associated with managed objects can themselves be vectors. Specific elements of the qualifier's vector list are specified using ?<query>.N to access the Nth element.

> For example, the status list qualifier of managed objects is a vector since multiple status messages can be generated by the managed properties associated with the managed object.

> For example, to access the first status message of the Filesystem Usage managed object in the Kernel reader module, the following URLs can be used:

> Numeric SNMP URL

>     snmp://manila:161/oid/1.3.6.1.4.1.42.2.12.2.2.12.6?statuslist.0

> Symbolic SNMP URL

>     snmp://manila:161/sym/\
>     sun.prod.sunsymon.agent.modules.kernelReader.filesystem?\
>     statuslist.0

> Module SNMP URL

>     snmp://manila:161/mod/kernel-reader/filesystem?statuslist.0

Copyright © 2000 Sun Microsystems, Inc. All Rights Reserved.