Appendix E |
URL Specifications |
This appendix covers the following topics:
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:
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.
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.
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
The following SNMP URL types are supported in Sun Management Center:
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#0Symbolic
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.
ModuleModule 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.
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.
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 URLManaged Property Value (vector)
snmp://manila:161/mod/kernel-reader/load/avg_1min#0
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 URLManaged Property Qualifier (Scalar Property, Scalar Qualifier)
snmp://manila:161/mod/kernel-reader/filesystem/ufsFilesystem/fileTable/\
fileEntry/ksize#/cache
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 URLManaged Property Qualifier (Vector Property, Scalar Qualifier)
snmp://manila:161/mod/kernel-reader/load/\
avg_1min?refreshinterval#0
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 URLManaged Property Qualifier (Vector Property, Vector Qualifier)
snmp://manila:161/mod/kernel-reader/filesystem/ufsFileSystem/\ fileTable/fileEntry/ksize?refreshinterval#/cache
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 URLManaged Object Qualifier (Scalar Qualifier)
snmp://manila:161/mod/kernel-reader/filesystem/ufsFileSystem/\ fileTable/fileEntry/kpctUsed?alarmlimits.0#/cache
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 URLManaged Object Qualifier (Vector Qualifier)
snmp://manila:161/mod/kernel-reader/load?refreshinterval
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