Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

fmri (7)

Name

fmri - Fault Management Resource Identifier

Description

Oracle Solaris subsystems such as the Service Management Facility, the Fault Management Daemon, Boot Environment Management, and the Image Packaging System, identify each element they manage using a fault managed resource identifier, abbreviated as FMRI. See smf(7), fmd(8), fmadm(8), beadm(8), and pkg(7) for more information on these subsystems.

FMRIs are used to identify both hardware resources and software resources and abstractions. For hardware resources the FMRIs are usually an implementation detail, and when a component is diagnosed as faulty it is the FRU (field replaceable unit) location label which is used to identify it. If no FRU label is available, the FMRI is used. For software abstractions such as SMF services, Boot Environments, or software packages, the FMRI (often in string form) is the one and only means of naming the managed resource (abbreviations aside).

All FMRIs include an indication of the FMRI scheme adhered to, and the version of that FMRI scheme in use. Once the scheme and version are known, the remainder of the FMRI is interpreted as specified in the formal definition of that FMRI scheme version. Schemes exists for svc, pkg, cpu, hc (hardware component), dev (device), and a number of others.

The formal definition of a given version of a particular FMRI scheme is specified as an unordered series of FMRI members specified as (member-name, data-type, data-semantics) tuples. An instance of an FMRI is a series of (name, type, value) tuples wherein the name and type match the FMRI specification and the value provided is a value of the given type and derived and interpreted according to the semantics described in the formal FMRI definition for that scheme and version. In Oracle Solaris C library APIs such as libfmevent(3LIB), FMRIs are represented as nvlists using the libnvpair(3LIB) library.

It is often more convenient to represent a given FMRI instance as a string, such as in command line interaction or in command output. The specification of each FMRI scheme version includes rules for formatting an FMRI of that scheme and version as a string instead of an name-value pair list, and given an FMRI string those same rules can be applied in reverse to recover the more-formal FMRI form. In some cases the string form of an FMRI can include a reduced amount of information as compared to the formal form, but still provide enough information to identify the resource for administrative purposes. The string form of an FMRI usually does not include the FMRI version number, and so the version is understood to be that whose formal FMRI-to-string formatting rules the given FMRI string matches. The string form of an FMRI is not unlike a URI as outlined in RFC 2396 which we use as a syntactical model. In particular, we reserve the same set of characters :, ;, =, @, /, &, ', $, and , and require the same escaped encoding conventions should these characters appear in an FMRI member value that is rendered in the string.

FMRI Members

The formal definition of a given version of a particular FMRI scheme is specified as an unordered series of:

(member-name, data-type, data-semantics)

tuples, some of which are required and some of which are optional. The formal definition also specifies how to render the FMRI in string form.

member-name

This associates a name with the FMRI member, with characters drawn from the following alphabet:

A-Z
a-z
'_' (underscore)
'-' (hyphen)
'.' (period)
data-type

This specifies the data type for this member. Legal primitive datatypes are listed in the following table, and for all primitive types we also define an array of that type as a legal datatype. The primitive integer and double datatypes are defined as in C, and we add boolean value and string primitive datatypes:


Primitive Datatype   Description
---------------------------------------------
boolean_value        Values can be 0 or 1
string               ASCII string
[u]int8              (Un)signed 8-bit integer
[u]int16             (Un)signed 16-bit integer
[u]int32             (Un)signed 32-bit integer
[u]int64             (Un)signed 64-bit integer
double               Double precision floating point

For each primitive datatype we form an aggregate datatype that is an ordered array of the primitive type:


Primitive Datatype    Description
----------------------------------------------
boolean_value array   Array of boolean_value
string array          Array of ASCII strings
[u]int8 array         Array of (un)signed 8-bit integer
[u]int16 array        Array of (un)signed 16-bit integer
[u]int32 array        Array of (un)signed 32-bit integer
[u]int64 array        Array of (un)signed 64-bit integer
double array          Array of double

A further aggregate datatype is defined - the nvlist (name-value list). An nvlist is an unordered list of (list-member-name, list-member-datatype) in which list-member-name names the member using the same alphabet as for member-name above, and list-member-datatype is any primitive or aggregate datatype including nvlist itself. We term the members of an nvlist: nvpairs (name-value pairs).

A special type of nvlist is an fmri which is an nvlist that conforms to one of the FMRI scheme versions defined below.


Synthetic Datatype    Description
---------------------------------------------------------
nvlist                Unordered list of nvpairs
nvlist array          Array of nvlist
fmri                  An nvlist that specifies an FMRI
                      scheme and version and includes other
                      members so as to be a valid FMRI
                      in that scheme version.

data-semantics

The data semantics for a given member in an FMRI definition specify how the values for that member should be interpreted, that is, their meaning. The data semantics can constrain the set of legal values that the member can assume to a subset of those representable by the member data type.

Stabilities

Some FMRI schemes, such as svc for SMF, are administrator-facing while others are more of a private implementation detail. Correspondingly, the definition of some FMRI schemes constitute a Committed interface, while the definition of others form a Private interface. See attributes(7). As with all Private interfaces the definition of Private FMRI components is subject to possibly incompatible change at any time, and you should not consume such interfaces nor rely on the presence or assumed semantics of private FMRI members.

In defining an FMRI scheme below we list a series of (member-name, data-type, data-semantics), specify which members are required and which are optional, and the rules for rendering an FMRI in string form. In terms of stability assignments, there are two stability levels associated with each member:

  • Stability of the (member-name, data-type) pair

  • Stability of the corresponding data-semantics

The default in both cases is Private. When the stability of both aspects of a member are identical (the common case) we write the stability level just once. When they differ then we write the member name and data type stability first, followed by a comma and the data semantics stability level. Today the only stability levels employed in FMRIs are Committed, Private, and Not An Interface but others are allowed. The semantics of a Committed FMRI component do not change incompatibly for given scheme and version thereof.

FMRI Scheme and Version Identification

All FMRI definitions are required to include members for the scheme name and major version thereof. The name/datatype and data semantics stabilities are Committed, thus all FMRI definitions are required to begin as follows:


Member Name      Data Type    Stability
----------------------------------------
scheme           string       Committed
version          uint8        Committed

scheme

Names this FMRI scheme

version

Scheme major version

Together these select the set of rules (as below) by which the given FMRI should be interpreted. A small number of scheme names are defined to cope with identifying resources within differing subsystems, and each scheme is versioned starting at version number 0.

When using the informal string representation of an FMRI, the scheme is always written but the scheme version in use is usually not included. The version in use is understood to be the latest for which the given FMRI string matches the FMRI-to-string conversion rules.

FMRI Authority

A further required, although implicitly present in some cases, FMRI member is authority:


Member Name   Data Type  Stability
----------------------------------------
[authority]   nvlist     Committed, (Varies)

Every FMRI includes authority information, either explicitly with the authority nvlist if present in the FMRI or implicitly that of the local fault management domain if not present. Authority information has two flavors:

  • High-level authority information, such as to identify the platform and hostname within which a particular resource that is the subject of an FMRI is located

  • Leaf-level authority information, providing identity information for the specific resource that is the subject of the FMRI

For example, an FMRI identifying a disk can have high-level authority information detailing the platform (host name, product name, chassis serial) in which the disk resides, and leaf-level authority information detailing the individual disk part number, serial, and so forth.

It is an unfortunate fact that some FMRI schemes have evolved to include leaf-level authority information outside of the authority nvlist as standalone FMRI members, and written as part of the path component in string form.

In their string representation, both high-level and leaf-level, FMRI authority information is prefaced with a colon (:), for example:

hc://:chassis-serial=12345/<string>

“:chassis-serial=12345” is a string represented authority member.

There are two versions of the high level authority (version 0 and version 1). Following are the descriptions for each.

The leaf-level authority members are described in the scheme specific sections below.

Version 0

Member Name   Data Type   Stability
-----------------------------------------------------
[server-id]   string      Committed, Not an Interface
[chassis-id]  string      Committed, Not an Interface
[product-sn]  string      Committed, Not an Interface
[product-id]  string      Committed, Not an Interface
[domain-id]   string      Committed, Not an Interface
[host-id]     string      Committed, Not an Interface
[server-id]

The hostname (uname –n) string for the entity on which the fault manager is running. Not invariant.

[chassis-id]

This is a serial number identifying the chassis within which the resource resides. Some large systems can include multiple distinct chassis components.

[product-sn]

In some cases chassis-id alone does not fully identify the system, for example, for service entitlement keyed by a product serial number and where the product can comprise multiple chassis elements. Invariant.

[product-id]

The product name string, such as Sun-Fire-X4600. Invariant.

[domain-id]

Identifies a particular hardware domain in the case of hardware that supports this feature. Not invariant.

[host-id]

The hostid(1) string in Oracle Solaris is not generally used. Not necessarily invariant.

Version 1

Member Name           Data Type    Stability
---------------------------------------------------------------
[system-mfg]            string      Committed, Not an Interface
[system-name]           string      Committed, Not an Interface
[system-part]           string      Committed, Not an Interface
[system-serial]         string      Committed, Not an Interface
[sys-comp-mfg]          string      Committed, Not an Interface
[sys-comp-name]         string      Committed, Not an Interface
[sys-comp-part]         string      Committed, Not an Interface
[sys-comp-serial]       string      Committed, Not an Interface
[sys-comp-fw-mfg]       string      Committed, Not an Interface
[sys-comp-fw-version]   string      Committed, Not an Interface
[sys-comp-fw-release]   string      Committed, Not an Interface
[chassis-mfg]           string      Committed, Not an Interface
[chassis-name]          string      Committed, Not an Interface
[chassis-part]          string      Committed, Not an Interface
[chassis-serial]        string      Committed, Not an Interface
[chassis-alias]         string      Committed, Not an Interface
[server-name]           string      Committed, Not an Interface
[domain-name]           string      Committed, Not an Interface
[host-id]               string      Committed, Not an Interface
[system-mfg]

The manufacturer of the top-level product. In a complex product the system-* members contain the service entitlement data. In a simple standalone rack system the system-*, sys-comp-*, and chassis-* data is duplicated. Invariant.

[system-name]

The model name of the top-level product. Invariant.

[system-part]

The part number of the top-level product. Invariant.

[system-serial]

The serial number of the top-level product. Invariant.

[sys-comp-mfg]

The manufacturer of the component system-level product. Invariant.

[sys-comp-name]

The model name of the component system-level product. Invariant.

[sys-comp-part]

The part number of the component system-level product. Invariant.

[sys-comp-serial]

The serial number of the component system-level product. Invariant.

[sys-comp-fw-mfg]

The manufacturer or vendor, of the system firmware stack. Invariant.

[sys-comp-fw-version]

The version of the system component firmware. If there is more than one component of the firmware stack (for example, SPARC), their versions will be represented individually, delimited by a comma (,), in a single string.

[sys-comp-fw-release]

The release date of the system component firmware. If there is more than one component of the firmware stack (for example, SPARC), their release dates will be represented individually, delimited by a comma (,), in a single string.

[chassis-mfg]

The manufacturer of the chassis within which the resource resides. Some large systems can include multiple distinct chassis components. Invariant.

[chassis-name]

The model name of the chassis. Invariant.

[chassis-part]

The part number of the chassis. Invariant.

[chassis-serial]

The serial number of the chassis. Invariant.

In some cases a single set of *-name/*-part/*-serial alone does not fully identify the system, for example, for service entitlement keyed by the product serial number and where the product can comprise multiple chassis elements. Invariant.

[chassis-alias]

This is the Chassis Receptacle Occupant alias value assigned to this chassis via `fmadm add-alias`. Not invariant.

[server-name]

The hostname (uname –n) string for the entity on which the fault manager is running. Not invariant.

[domain-name]

Identifies a particular hardware domain in the case of hardware that supports this feature. Not invariant.

[host-id]

The hostid(1) string in Oracle Solaris); not generally used. Not necessarily invariant.

Logical vs. Universal FMRI Schemes

A logical FMRI scheme defines FMRIs that can only meaningfully be interpreted within the fault management domain (typically an Oracle Solaris instance) in which they were generated. Identical FMRIs of a logical scheme that are native to distinct fault management domains do not necessarily identify the same actual resource. For example a cpu identified as cpu id 1 using the cpu scheme must be interpreted in the Oracle Solaris instance that generated the FMRI (that is, its native context), and many other Oracle Solaris instances also have a logical processor id number 1 but all such FMRIs do not identify the same actual processor. The native fault management domain is identified by its high-level authority information which is typically not captured in an FMRI instance but instead understood to be that of the local Oracle Solaris instance.

A universal FMRI scheme identifies resources in a universally unique manner, and two identical FMRIs in a universal scheme identify the same actual resource wherever they are interpreted. Such schemes are used when ambiguity must be avoided, such as in identifying hardware components that are faulted.

FMRI schemes do not include a member indicating whether the scheme is logical or universal.

FMRI Schemes and Versions

The following FMRI scheme versions are defined in the sections that follow:


Scheme     Version(s) Universal? Description
-------------------------------------------------------------
cpu        0, 1       No         Logical processor identification
dev        0          No         Device resources
fmd        0, 1       No         Fault Management Daemon modules
hc         0, 1       Yes        Hardware Components
mem        0          No         Memory modules and cache
mod        0          No         Kernel modules
pkg        0, 1       Yes        Software packages
svc        0          No         SMF services & service instances
sw         0          No         Software objects
zfs        0          No         zfs filesystem resources
location   0          No         FRU location
be         0          No         Global zone boot environments
zbe        0          No         Non-global zone boot environments

Of these, the svc, be, zbe, and pkg schemes are the most-likely to be encountered in day-to-day Oracle Solaris use, while the remainder are usually hidden behind command line interaction with the fault management subsystem when problems have been diagnosed.

SCHEME cpu VERSION 0

The cpu scheme is used to identify the logical Oracle Solaris processor resource that can be affected by a problem that has been diagnosed, and which can be offlined in response to that problem diagnosis. It does not necessarily identify the physical resource involved, and should not be used to identify parts for replacement.

The cpu scheme is a logical FMRI scheme; an FMRI in the cpu scheme is meaningful only within the fault management domain identified by the authority information.


Member Name   Data Type    Stability
------------------------------------
scheme        string       Committed, value "cpu"
version       uint8        Committed, value 0
cpuid         uint32       Committed
[serial]      uint64       Private

cpuid

The Oracle Solaris processor instance id of this logical execution unit, as listed by psradm(8) on the Oracle Solaris instance identified by the authority information.

[serial]

The semantics of this Private FMRI member are not documented.

String form:

cpu:///cpuid=<cpuid>[/serial=<hex-serial>]

<hex-serial> is the serial member written in hexadecimal with no 0x prefix.

SCHEME cpu VERSION 1

Version 1 of the cpu FMRI scheme has the same use as version 0, with some private FMRI member changes and additions.


Member Name   Data Type   Stability
------------------------------------------------
scheme        string      Committed, value "cpu"
version       uint8       Committed, value 1
cpuid         uint32      Committed
[serial]      string      Private
[cpumask]     uint8       Private
[cpufru]      string      Private
[cacheindex]  uint32      Private
[cacheway]    uint32      Private
[cachebit]    uint16      Private
[cachetype]   uint8       Private

cpuid

       As per cpu scheme version 0

[serial]
[cpumask]
[cpufru]
[cacheindex]
[cacheway]
[cachebit]
[cachetype]

The semantics of these Private FMRI members are not documented.

String form:

cpu:///cpuid=<cpuid>[/serial=<serial>]
         [/cacheindex=.../cacheway=.../
         cachebit=.../cachetype=...]

Members cpumask and cpufru do not appear in the string form.

SCHEME dev VERSION 0

The dev scheme is used to identify devices. It is not an invariant scheme. A dev scheme FMRI should be interpreted only in the fault management domain identified within the authority information.


Member Name        Data Type   Stability
-------------------------------------------------------------------
scheme             string      Committed, value "dev"
version            uint8       Committed, value 0
device-path        string      Committed
[devid]            string      Private
[target-port-l0id] string      Private


device-path

A filesystem path within the Oracle Solaris /devices tree that identifies a device node, such as pci@0, 0/pci108e, cb84@2, 1. Beyond this interpretation that this member identifies a /devices path, the internal structure of such paths, that is, the structure and node naming of the Oracle Solaris /devices tree is Not An Interface.

[devid]
[target-port-l0id]

The semantics of these Private FMRI members are not documented.

String form:

dev:///[:devid=<devid>]
    [:target-port-l0id=<target-port-l0id>]
    <device-path>

SCHEME fmd VERSION 0

This scheme is used to identify Oracle Solaris Fault Manager (fmd(8)) modules.

High-level authority:

Member Name  Data Type  Stability
---------------------------------
[server-id]  string     Committed, Not an Interface
[chassis-id] string     Committed, Not an Interface
[product-sn] string     Committed, Not an Interface
[product-id] string     Committed, Not an Interface
[domain-id]  string     Committed, Not an Interface

FMRI does not include any leaf-level authority information within the authority nvlist, instead it is featured as top-level members of the FMRI.


Member Name  Data Type  Stability
-----------------------------
scheme       string     Committed, value "fmd"
version      uint8      Committed, value 0
[authority]  nvlist     Committed, See above
mod-name     string     Committed, Not an Interface
mod-version  string     Committed, Not an Interface

mod-name

The fmd module name, an opaque string.

mod-version

The fmd module version, an opaque string.

String form:

fmd:///module/mod-name>

SCHEME fmd VERSION 1

This scheme is used to identify Oracle Solaris Fault Manager (fmd(8)) modules.

High-level authority:

Member Name             Data Type  Stability
--------------------------------------------------------------
[system-mfg]            string     Committed, Not an Interface
[system-name]           string     Committed, Not an Interface
[system-part]           string     Committed, Not an Interface
[system-serial]         string     Committed, Not an Interface
[sys-comp-mfg]          string     Committed, Not an Interface
[sys-comp-name]         string     Committed, Not an Interface
[sys-comp-part]         string     Committed, Not an Interface
[sys-comp-serial]       string     Committed, Not an Interface
[sys-comp-fw-mfg]       string     Committed, Not an Interface
[sys-comp-fw-version]   string     Committed, Not an Interface
[sys-comp-fw-release]   string     Committed, Not an Interface
[server-name]           string     Committed, Not an Interface
[domain-name]           string     Committed, Not an Interface
[host-id]               string     Committed, Not an Interface

As with version 0 the FMRI does not contain leaf-level authority information within the authority nvlist. Instead it is featured as top-level members of the FMRI.

Member Name       Data Type  Stability
--------------------------------------
scheme            string     Committed, value "fmd"
version           uint8      Committed, value 1
[authority]       nvlist     Committed, See above
mod-name          string     Committed, Not an Interface
mod-version       string     Committed, Not an Interface
mod-name

The fmd module name, an opaque string.

mod-version

The fmd module version, an opaque string.

String form:
fmd:///module/<mod-name>
SCHEME legacy-hc VERSION 0

The hc scheme is used to identify hardware components. In most cases these FMRIs should remain as an internal implementation detail, and where a hardware component is diagnosed as faulty it is identified (for example, in fmadm(8)) by its FRU label or location label.

There is only one version of the hc scheme in use (version 0) but we differentiate two minor versions, distinguished by the presence or absence of a member named component. An hc scheme FMRI that includes a component member is an instance of the obsoleted legacy hc scheme.

Obsolete legacy hc variant:

Member Name  Data Type  Stability
-------------------------------------------------------------------
scheme       string      Committed, value "hc"
version      uint8       Committed, value 0
component    string      Committed
component

The FRU label for the resource.

String form for legacy hc:
hc:///component=<component>
SCHEME hc VERSION 0

The authority nvlist is the high-level authority information concerned with identifying the fault management domain in which a given FMRI was generated. Thus it includes members for the hostname, product name, chassis serial number and so on. Some of these members are invariant (such as platform serial number) and serve uniquely to identify some element, while others (such as hostname) are a soft identification which could change over time (albeit infrequently).


Member Name   Data Type   Stability
-----------------------------------------------------
[server-id]   string      Committed, Not an Interface
[chassis-id]  string      Committed, Not an Interface
[product-sn]  string      Committed, Not an Interface
[product-id]  string      Committed, Not an Interface
[domain-id]   string      Committed, Not an Interface
[host-id]     string      Committed, Not an Interface

While all members are listed as optional, as many as make sense for a given FMRI should be included. If the authority nvlist is absent in an FMRI then the authority is understood to be the local fault management domain; if an hc scheme FMRI is transmitted outside of its native domain it should include explicit high-level authority information.

The Not an Interface stability for the data semantics of each means that the value can be treated as an opaque string only and any internal structure to the string is not an interface. For example a serial number can be matched using string compare, but the length of the serial number string and the meaning of individual characters therein is not an interface.

String form:

These authority members, those that are present in a given FMRI, can be written in string form as an unordered series of colon-separated name=value pairs. We'll define this as authstr, to be used in the specification of the string form for individual FMRI schemes below which import the default authority information.

authstr = server-id=<server-id>
                [:chassis-id=<chassis-id>]
                [:product-sn=<product-sn>]
                [:product-id=<product-id>]
                [:domain-id=<domain-id>]
                [:host-id=<host-id>]
                [:devid=<devid>]

There is no leaf-level authority/identity information included in the authority nvlist - instead such information (serial and part numbers) feature as top-level members of the FMRI.


Member Name    Data Type    Stability
------------------------------------------------------
scheme         string       Committed, value "hc"
version        uint8        Committed, value 0
[authority]    nvlist       Committed, See above
[serial]       string       Committed, Not-an-Interface
[devid]        string       Private
[part]         string       Committed, Not-an-Interface
[revision]     string       Committed, Not-an-Interface
[hc-root]      string       Private
hc-list-sz     uint32       Private
hc-list        nvlist array Private
[facility]     nvlist       Private
[hc-specific]  nvlist       Private

[serial]

The serial number string of the hardware component identified in this FMRI. This is an opaque string whose internal structure is not an interface.

[devid]

The semantics of these Private FMRI members are not documented.

[part]

The part number string of the hardware component identified in this FMRI. This is an opaque string whose internal structure is not an interface.

[revision]

The revision of the part number, as a string. Again this is an opaque string.

[hc-root]

The semantics of this Private FMRI member are not documented.

hc-list-sz

The semantics of this Private FMRI member are not documented.

hc-list

The semantics of this Private FMRI member are not documented, however we enumerate the structure of the content (subject to incompatible change). Each member of the (ordered) nvlist array has the following structure:


Member Name    Data Type   Stability
------------------------------------
hc-name        string      Private
hc-id          string      Private

[facility]

The semantics of this Private FMRI member are not documented, however we enumerate the structure of the content (subject to incompatible change). The facility nvlist has members as follows:


Member Name    Data Type   Stability
------------------------------------
facility-type  string      Private
facility-name  string      Private

[hc-specific]

The semantics of this Private FMRI member are not documented.

String form:
authstr is defined above
hcauthstr = [:serial=<serial>]
                 [:devid=<devid>]
                 [:part=<part>]
                 [:revision=<revision>]

hc-path =<hc-list[0].hc-name>=<hc-list[0].hc-id>
               /<hc-list[1].hc-name>=<hc-list[1].hc-id>
               /<hc-list[2].hc-name>=<hc-list[2].hc-id>
               ...
hcspecstr = private string formed from hc-specific nvlist,
               of the form "/name=value"

facstr = <facility.facility-type>=<facility.facility-name>

hc://[authstr][hcauthstr]/[hc-root/]<hc-path>
                                     [<hcspecstr>]
                                     [?<facstr>]

The high-level authority information from the authority nvlist appears adjacent to the leaf-level authority information of serial and part number, all colon separated. The components of this authority string can appear in any order, with high-level and leaf authority elements interleaved. Parsing such a string is clumsy and relies on knowing in advance which components belong to which class of authority information.

SCHEME hc VERSION 1

Version 1 of the hc FMRI scheme has the same use as version 0, with some private FMRI member changes and additions.

Member Name     Data Type    Stability
--------------------------------------------------------
[chassis-mfg]     string      Committed, Not an Interface
[chassis-name]    string      Committed, Not an Interface
[chassis-part]    string      Committed, Not an Interface
[chassis-serial]  string      Committed, Not an Interface
[chassis-alias]   string      Committed, Not an Interface

String form:

The same semantics apply to the hc FMRI scheme version 1 string form as version 0.

authstr = [:chassis-mfg=<chassis-mfg>]
                [:chassis-name=<chassis-name>]
                [:chassis-part=<chassis-part>]
                [:chassis-serial=<chassis-serial>]
                [:chassis-alias=<chassis-alias>]

As with hc scheme version 0 there is no leaf-level authority/identity information included in the authority nvlist with version 1 - instead such information (for example, serial/revision/part numbers) feature as top-level members of the FMRI.

Member Name    Data Type    Stability
------------------------------------------------------
scheme         string       Committed, value "hc"
version        uint8        Committed, value 1
[authority]    nvlist       Committed, See above
[fru-mfg]      string       Committed, Not-an-Interface
[fru-serial]   string       Committed, Not-an-Interface
[fru-part]     string       Committed, Not-an-Interface
[fru-revision] string       Committed, Not-an-Interface
[devid]        string       Private
[hc-root]      string       Private
hc-list-sz     uint32       Private
hc-list        nvlist array Private
[facility]     nvlist       Private
[hc-specific]  nvlist       Private
[fru-mfg]

The manufacturer string of the hardware component identified in this FMRI. This is an opaque string whose internal structure is not an interface.

[fru-serial]

The serial number string of the hardware component identified in this FMRI. This is an opaque string whose internal structure is not an interface.

[fru-part]

The part number string of the hardware component identified in this FMRI. This is an opaque string whose internal structure is not an interface.

[fru-revision]

The revision of the part number, as a string. Again this is an opaque string.

[devid]

The semantics of these Private FMRI members are not documented.

[hc-root]

The semantics of this Private FMRI member are not documented.

hc-list-sz

The semantics of this Private FMRI member are not documented.

hc-list

The semantics of this Private FMRI member are not documented, however we enumerate the structure of the content (subject to incompatible change). Each member of the (ordered) nvlist array has the following structure:

Member Name    Data Type   Stability
------------------------------------
hc-name        string      Private
hc-id          string      Private

[facility]

The semantics of this Private FMRI member are not documented, however we enumerate the structure of the content (subject to incompatible change). The facility nvlist has members as follows:

Member Name    Data Type   Stability
------------------------------------
facility-type  string      Private
facility-name  string      Private

[hc-specific]

The semantics of this Private FMRI member are not documented.

String form:
authstr is defined above
hcauthstr = [:fru-mfg=<fru-mfg>]
                 [:fru-serial=<fru-serial>]
                 [:devid=<devid>]
                 [:fru-part=<fru-part>]
                 [:fru-revision=<fru-revision>]

hc-path =<hc-list[0].hc-name>=<hc-list[0].hc-id>
               /<hc-list[1].hc-name>=<hc-list[1].hc-id>
               /<hc-list[2].hc-name>=<hc-list[2].hc-id>
               ...
hcspecstr = private string formed from hc-specific nvlist,
               of the form "/name=value"

facstr = <facility.facility-type>=<facility.facility-name>

hc://[authstr][hcauthstr]/[hc-root/]<hc-path>
                                     [<hcspecstr>]
                                     [?<facstr>]

The high-level authority information from the authority nvlist appears adjacent to the leaf-level authority information of serial and part number, all colon separated. The components of this authority string can appear in any order, with high-level and leaf authority elements interleaved. Parsing such a string is clumsy and relies on knowing in advance which components belong to which class of authority information.

SCHEME mem VERSION 0

This scheme is used to identify memory modules and memory pages, although more recently these have been identified in the hc scheme. The mem scheme has also been used to identify cpu cache resources.


Member Name   Data Type    Stability
-------------------------------------------------
scheme        string       Committed, value "mem"
version       uint8        Committed, value 0
unum          string       Committed, Private
[serial]      string array Private
[physaddr]    uint64       Private
[offset]      uint64       Private
unum

This string identifies the memory module, generally as labeled on the platform silkscreens or service label. The presence of this member of type string is a Committed interface, but the internal structure of the unum string is a Private interface. Therefore, you can use the opaque unum string to identify a memory module, but the interpretation of the components of a unum string is platform dependent and Private.

A unum can identify a group (or bank) of memory modules. These should instead have been identified by multiple FMRIs, one for each memory module, but this is an historical anomaly from early implementations.

[serial]

A string array of the serial number(s) of the memory module(s) named by the unum member. The internal structure of a serial number string is not an interface so you can use only the opaque string value in matching serial number and not apply any further interpretation.

[physaddr]
[offset]

The semantics of these Private FMRI members are not documented.

String form:

mem:///unum=<unum>
        [/offset=<hex-offset> | /physaddr=<hex-physaddr>]
SCHEME mod VERSION 0

This scheme is used to identify Oracle Solaris kernel modules.

Member Name    Data Type    Stability
--------------------------------------------------
scheme         string       Committed, value "fmd"
version        uint8        Committed, value 0
mod-name       string       Committed
[mod-desc]     string       Committed
[mod-pkg]      fmri         (fmri)
mod-name

The module name, as in per modinfo(8).

[mod-desc]

The module description, again as per modinfo(8).

[mod-pkg]

A pkg scheme FMRI of the package which delivers this module.

String form:
mod:///mod-name=<mod-name>
SCHEME obj VERSION 0

This scheme is used to identify abstract objects when no other FMRI scheme is appropriate.

Member Name   Data Type   Stability
-------------------------------------------------------------------
scheme        string      Committed, value "obj"
version       uint8       Committed, value 0
id            string      Committed, Private
[token]       string      Committed, Private
id

Resource identifier string which is unique within the context of the detecting software.

[token]

Another form of optional resource identifier.

String form:
obj://[<authority>]/:id=<id>[:token=<token>]
SCHEME pkg VERSION 0

This version of the pkg scheme corresponds to legacy SVR4 packaging as used with pkgadd(8), pkginfo(1), pkgrm(8), and related utilities. This scheme is universal if package name and package version conventions are adhered to.

Member Name   Data Type   Stability
-------------------------------------------------------------------
scheme        string      Committed, value "pkg"
version       int8        Committed, value 0
pkg-name      string      Committed
pkg-basedir   string      Committed
pkg-inst      string      Committed
pkg-version   string      Committed
pkg-name

The package name.

pkg-basedir

BASEDIR as per pkginfo(1)

pkg-inst

PKGINST as per pkginfo(1)

pkg-version

VERSION as per pkginfo(1)

String form:
pkg:///<pkg-name>/:version=<pkg-version>
SCHEME pkg VERSION 1

This version of the pkg scheme corresponds to the Image Packaging System. See the Package FMRIs and Versions section of pkg(7). Such FMRIs are used in string form in the command line and its output, and the command line permits abbreviations of the FMRI string.

FMRIs in the pkg scheme version 1 are universal: the same FMRI interpreted in two distinct contexts (such as in distinct Oracle Solaris instances) identify the same actual package (or copies thereof).

The command line uses the string form of version 1 pkg FMRIs, and permits abbreviations of such strings.

Member Name   Data Type    Stability
-------------------------------------------------
scheme        string       Committed, value "pkg"
version       uint8        Committed, value 1
[authority]   nvlist       Committed
pkg-name      string       Committed
[pkg-version] nvlist       Committed
[authority]

The authority nvlist specifies the package publisher, per pkg publisher output:


Member Name    Data Type    Stability
-------------------------------------
publisher      string       Committed

publisher

The publisher of this package, such as Oracle Solaris.

pkg-name

The name (stem) of the package

[pkg-version]

Member Name    Data Type    Stability
---------------------------------------
release        string       Committed
[built-on]     string       Committed
[branch]       string       Committed
[timestamp]    string       Committed

release

The primary version of the component, written as a dot sequence string (an arbitrary-length, dot-separated series of non-zero-leading decimal digits).

built-on

The operating system version on which the component was built, again specified as a dot sequence.

branch

The vendor branch version, as a dot sequence.

timestamp

An ISO 8601 date string: yyyymmddThhmmssZ in which the T and Z are literals.

String form:

pkgauthstr = <authority.publisher>

pkg://[pkgauthstr]/<pkg-name>
    [@<release>[,<built-on>][-<branch>][:<timestamp>]

SCHEME svc VERSION 0

The svc scheme describes SMF services and service instances. See smf(7). In SMF command lines such as svcadm(8), svccfg(8), svcprop(1), svcs(1) and their output such FMRI are always written in their string form, and the SMF command lines permit abbreviations.

The svc scheme FMRI is a logical scheme, and, as such an FMRI should only be interpreted in the fault management domain (Oracle Solaris instance) in which it was generated.


Member Name    Data Type   Stability
-------------------------------------------------
scheme         string      Committed, value "svc"
version        uint8       Committed, value 0
svc-name       string      Committed
[svc-instance] string      Committed
[svc-scope]    string      Committed
[pg]           string      Committed
[property]     string      Committed
svc-name

The service name, such as network/smtp. See smf(7).

[svc-instance]

Used when identifying an instance of a service. Often default, but can also be things like the sendmail instance of service network/smtp.

[svc-scope]

As per smf(7), all service and instance objects are contained in a scope that represents a collection of configuration information. The configuration of the local Oracle Solaris instance is called the localhost scope, and is the only currently supported scope.

String form:
svc://[<svc-scope>]/<svc-name>[:<svc-instance>][/:properties/<pg>[/<property>]]

SMF subsystem commands such as svcadm(8) permit (or even require) abbreviations of the string form above. The indication of svc scheme at the start of the string is considered optional and implied by the SMF command line utility. When the svc scheme identifier is used, the authority component is also abbreviated to svc:/<svc-name> instead of the more-formal svc:///<svc-name>. For example, in SMF we write the examples in one of the following ways:

svc:/network/smtp:sendmail
svc:///network/smtp:sendmail
svc://localhost/network/smtp:sendmail
svc:/network/dns/client:default/:properties/config/nameserver

Furthermore, SMF permits further abbreviation if it identifies a unique service or instance. For example the instance name sendmail is unique and one can use svcs sendmail, svcadm restart sendmail, and so forth.

Such abbreviations are a convention of the SMF subsystem and not part of the formal FMRI definition. When a svc scheme FMRI is received in nvlist form (for example, in a libfmevent(3LIB) subscription it appears in the more formal form when rendered as a string.

SCHEME sw VERSION 0

This FMRI scheme is used to identify software resources such as executables, library objects, and core files. This is a logical FMRI scheme.


Member Name   Data Type   Stability
-----------------------------------------------
scheme        string      Committed, value "sw"
version       uint8       Committed, value 0
object        nvlist      See belowPrivate
[site]        nvlist      See belowPrivate
[context]     nvlist      See belowPrivate

The object, site, and context members are all Private and so subject to incompatible change, but their content is documented below for informational purposes.

object

This required member identifies the software object. At this time only objects resident within the filesystem are catered for.


Member     Type        Description
------------------------------------------------------------
path       string      Filesystem path to object
[root]     string      If present, real path to chroot root
                       directory
[pkg]      fmri        "pkg" scheme fmri of package that
                       delivers path
site

This optional member identifies a site within the object.


Member   Type    Description
------------------------------------------------------------
[token]  string  Vendor and subsystem unique publisher
                 token id
[module] string  Source module information
[file]   string  Source filename (translation unit)
[func]   string  Source function
[line]   int64   Source file line number

context

This optional member communicates runtime information.


Member             Type         Description
-------------------------------------------------------
[origin]           string       "userland" or "kernel"
[execname]         string       Executable name
[pid]              uint64       Process id
[thread-id]        uint64       Thread id
[os-instance-uuid] string       Solaris instance UUID
[zone]             string       Zone name, if not the global zone
[ctid]             uint64       Contract id
[stack]            string array Symbolic stack trace

String form:

sw://[<authority>]/
       [:root=<object.root]
       :path=<object.path>
       [#<fragment-identifier>]

Slash characters / in the root and object path are not escaped.

<fragment-identifier> is one of:

:token=<site.token>

or

:file=<site.file>[:func=<site.func>][:line=<site.line>]
SCHEME zfs VERSION 0

Member Name   Data Type    Stability
-------------------------------------------------------------------
scheme        string       Committed, value "zfs"
version       uint8        Committed, value 0
[pool-name]   string       Committed
pool          uint64       Committed
[vdev]        uint64       Private
[vdev-name]   string       Private
[pool-name]

The pool name, as per zpool list -o name

pool

The pool GUID as per zpool list -o guid

[vdev]

The semantics of this Private FMRI member are not documented

[vdev-name]

The semantics of this Private FMRI member are not documented.

String form:
hex-vdev = 'vdev' in hexadecimal with no '0x' prefix.
hex-pool = 'pool' in hexadecimal with no '0x' prefix.
zfs://[pool_name=<pool-name>/]pool=<hex-pool>
zfs://[pool_name=<zfs://[pool_name=<hex-pool>
[/vdev=<hex-vdev>][:vdev_name=<vdev-name>]

The <vdev-name> is written without escaping any / characters.

SCHEME location VERSION 0

This FMRI scheme is used to identify hardware resources by their location path.

Member Name    Data Type    Stability
-------------------------------------------------------------------
scheme         string       Committed, value "location"
version        uint8        Committed, value 0
location-path  string       Committed
location-path

The location of the resource, typically matching labels printed the hardware.

String form:
location:///<location-path>

The <location-path> is written without escaping any / characters.

SCHEME be VERSION 0

The be scheme is used to identify a boot environments(BE) or a BE snapshot in the global zone or non-global zone. The be scheme FMRI is a logical scheme. So, the FMRI is only interpreted by the BE management software in the Oracle Solaris instance.

Member Name	Data Type        Stability
-------------------------------------------------------------------
scheme            string           Committed, value "be"
version           uint8            Committed, value 0
[authority]       string           Committed
be-name           string           Committed
[authority]

The zpool in which the be-name resides. This is optional. If not specified, the default value is the zpool of the currently running BE.

be-name

The name of the BE or the name of the BE snapshot that resides in the zpool named in authority.

String form:
be://[authority]/be-name[@snapshot_name]

beadm(8) allows users to abbreviate the string form of this scheme to the be-name member only for identifying BEs or BE snapshots residing in the same zpool as the currently running BE. This abbreviation is a convention of beadm(8) and not part of the formal FMRI definition.

SCHEME zbe VERSION 0

The zbe scheme is used to identify a non-global zone boot environments(ZBE) or a ZBE snapshot in the global zone.

The zbe scheme FMRI is a logical scheme. So, the FMRI is only interpreted by the BE management software in the global zone of a Oracle Solaris instance. The zbe scheme is not valid in non-global zone instances.

Member Name	Data Type    Stability
-------------------------------------------------------------------
scheme	     string	Committed, value "zbe"
version	    uint8	 Committed, value 0
authority	  string	Committed
zbe-name	   string	Committed
authority

Name of the zone in which the zbe-name resides. The specified zone must be defined in the currently running global zone BE.

zbe-name

Name of the ZBE or the name of the ZBE snapshot that resides in zone named in authority.

String form:
zbe://zone_name/zbe-name[@snapshot]

See Also

beadm(8), hostid(1), pkginfo(1), svcprop(1), svcs(1), libfmevent(3LIB), libnvpair(3LIB), contract(5), attributes(7), pkg(7), smf(7), fmd(8), fmdump(8), pkgadd(8), pkgrm(8), psradm(8), svcadm(8), svccfg(8)

RFC 2396