Standards, Environments, and Macros smftemplate(5)
NAME
smftemplate - service management framework support for ser-
vice metadata
DESCRIPTION
Templates are defined by service developers to describe
metadata about a service in general or individual configura-
tion properties on a service, including human-consumable
descriptions as well as definitions of valid configuration.
Administrators are provided access to templates through SMF
commands that describe configuration values and validate
configuration against templates.
Tool developers can use templates to provide more helpful
user interfaces for service configuration.
Template Data
Service metadata is defined in the template as part of the
service manifest.
Consuming Template Data
The svcs -lv and svccfg describe commands can be used to
access metadata about properties in a human-readable format.
svccfg(1M)'s validate subcommand can be used to validate a
service instance or manifest against template data. A set of
libscf(3LIB) interfaces is available to access template
data.
Template Definition
The sole interface to define templates is the service mani-
fest.
Service authors should provide template metadata including
commonnames, descriptions, choices and constraints for
service-specific property groups and properties which they
introduce. At a minimum, service authors must provide
descriptions for property groups and properties in the C
locale. Service authors should not provide template metadata
for framework-delivered property groups such as methods and
dependencies.
See the EXAMPLES section for an example of authoring a tem-
plate definition for a service.
SunOS 5.11 Last change: 10 Nov 2008 1
Standards, Environments, and Macros smftemplate(5)
Template Composition
All template interfaces search for template data about a
property group first on the instance, then on the service,
then on the service's restarter, and finally globally.
A property group template is defined by its author to apply
to a specific instance, to a service and all of its
instances, to a restarter's delegates, or globally. A typi-
cal service author defines the template on an instance or on
a service. A template defined on an instance is applied to
that instance only, and can override a template for that
property group defined on the service. A template defined on
the service is applied to all instances of that service.
Restarter authors can define templates in their manifest
that apply to any service which uses their restarter, which
is also known as a delegate. SMF framework authors have
defined templates for property groups with well-known mean-
ings to the entire SMF framework in the manifest for
svc:/system/svc/global.
Templates defined globally or by the restarter and re-
defined by the service or instance are flagged as a valida-
tion error. Service authors can avoid these errors by creat-
ing templates only for property groups specific to their
service and not consumed by the SMF framework.
Property group templates can also be wildcarded by name or
type. Only the most specific template definition applicable
to a property group is honored.
Template Details
Service and Instance Templates
The template element defines the start of a template block.
All further definitions below can be included in a template
block. A template element can be contained in either a ser-
vice or instance element. If it is contained in the service
element, it applies to the service and all instances of that
service. If it is contained in the instance element, it
applies to only that instance of the service.
Whenever possible, we recommend defining the template data
for the entire service.
SunOS 5.11 Last change: 10 Nov 2008 2
Standards, Environments, and Macros smftemplate(5)
Service and Instance Common Names
The entire service or instance can define a common name to
describe the purpose of the service/instance.
console login
commonname is a free-form string, but is intended to be
used as a label in a GUI or CLI.
The following guidelines are recommended:
o Be brief. A word or two is usually most appropri-
ate. Limit the name to under 40 characters.
o Be clear. The service, property group, or property
name might not be helpful for humans, but
commonname should help clarify the purpose of the
entity.
o No punctuation. commonname is not a sentence or a
paragraph. It should not contain clauses or
phrases. Punctuation should only be present to meet
trademark requirements.
o Capital letters must be used only for acronyms or
proper names. For locales other than English, use
appropriate capitalization for a sentence fragment.
Service and Instance Descriptions
The description element contains a longer description of the
property group, suitable for a status line or a tool-tip:
Provide the text login prompt on console.
SunOS 5.11 Last change: 10 Nov 2008 3
Standards, Environments, and Macros smftemplate(5)
description Guidelines
o Use proper grammar. description is a sentence meant
to be read by humans.
o Be brief. A few sentences are usually most
appropriate.
Documentation
Documentation for this service can be defined explicitly, so
that when the service is experiencing issues, or a consumer
of the service wants more information on it, they can find
it easily.
Documentation can include man pages or references to stable
URLs for reference documentation.
Property Groups
The pgpattern element contains the definitions for a pro-
perty group:
name is the property group's name, and type is the property
group's type.
target specifies what the target of this definition is.
"this" would refer to the defining service or instance.
"instance" can only be used in a service's template block,
and means the definition applies to all instances of this
service. "delegate" can only be used in a restarter's tem-
plate block, and applies to all instances that are delegated
to that restarter. "all", only usable by the master restar-
ter, would refer to all services on the system. The default
value of target is "this".
SunOS 5.11 Last change: 10 Nov 2008 4
Standards, Environments, and Macros smftemplate(5)
required indicates whether this property group is required
or not. The default value of required is false. If required
is true, both name and type must be specified.
name and/or type can be omitted. If either of these attri-
butes is omitted it is treated as a wildcard. For instance,
if the name attribute is omitted from the pgpattern defini-
tion, the pgpattern is applied to all property groups that
have the specified type.
Property Group Names
The commonname element contains the localized, human-
readable name for the property group:
startt method
commonname is a free-form string, but is intended to be
used as a label in a GUI or CLI.
The following guidelines are recommended:
o Be brief. A word or two is usually most appropri-
ate.
o Be clear. The service, property group, or property
name might not be helpful for humans, but
commonname should help clarify the purpose of the
entity.
o No punctuation. commonname is not a sentence or a
paragraph. It should not contain clauses or
phrases. Punctuation should only be present to meet
trademark requirements.
o Capital letters must be used only for acronyms or
proper names. For locales other than English, use
appropriate capitalization for a sentence fragment.
Property Group Description
The description element contains a longer description of the
property group, suitable for a status line or a tool-tip:
SunOS 5.11 Last change: 10 Nov 2008 5
Standards, Environments, and Macros smftemplate(5)
A required method which starts the service.
description Guidelines
o Use proper grammar. description is a sentence meant
to be read by humans.
o Be brief. A few sentences are usually most
appropriate.
Properties
The proppattern element contains the definitions for a
specific property:
name is the property's name, and type is the property's
type.
required indicates whether this property is required. The
default value of required is false.
name is always required. type is optional only if required
is false.
Property Names
The commonname element contains the localized, human-
readable name for the property:
commonname is a free-form string field, but is intended to
be used as a label in a GUI or CLI.
retry interval
SunOS 5.11 Last change: 10 Nov 2008 6
Standards, Environments, and Macros smftemplate(5)
The following guidelines are recommended:
o Be brief. A word or two is usually most appropri-
ate.
o Be clear. The service, property group, or property
name might not be helpful for humans, but
commonname should help clarify the purpose of the
entity.
o No punctuation. commonname is not a sentence or a
paragraph. It should not contain clauses or
phrases. Punctuation should only be present to meet
trademark requirements.
o Capital letters must be used only for acronyms or
proper names. For locales other than English, use
appropriate capitalization for a sentence fragment.
Property units
The units element contains the localized, human-readable
units for a numerical property:
seconds
units Guidelines
The following guidelines are recommended:
o Be brief. Strive to use only a single word or
label. The plural form is usually most appropriate.
o No punctuation. units is not a sentence or a para-
graph. It should not contain clauses or phrases.
Punctuation should only be present to meet trade-
mark requirements.
Property description
The description element contains a longer description of the
property, suitable for a status line or a tool-tip:
SunOS 5.11 Last change: 10 Nov 2008 7
Standards, Environments, and Macros smftemplate(5)
The number of seconds to wait before retry.
description Guidelines
o Use proper grammar. description is a sentence meant
to be read by humans.
o Be brief. A few sentences are usually most
appropriate.
Property visibility
The visibility element specifies whether simplified views in
higher level software might want to display this property.
Some properties are internal implementation details and
should not be presented as a configuration setting. Others
might merely be read-only. This property is used to specify
these restrictions. A value of hidden indicates that the
property shouldn't be displayed, readonly means that the
property isn't intended to be modified, and readwrite indi-
cates the property is modifiable.
This is not a security mechanism, it is solely intended to
help prevent the user from shooting himself in the foot, and
to remove unnecessary clutter from CLI output or a GUI
display. Hidden properties is visible in full-disclosure
modes of many commands and UIs.
Property format
The cardinality and internalseparators elements constrain
the structure of a property:
,
SunOS 5.11 Last change: 10 Nov 2008 8
Standards, Environments, and Macros smftemplate(5)
cardinality indicates the acceptable number of property
values. min is the minimum number, and max is the maximum
number. Both are optional. If neither is specified, is the same as the default, zero or more values.
internalseparators specify the separator characters used
for those property values into which multiple real values
are packed.
Value constraints
The constraints element specifies what values are acceptable
for a property:
The value element includes a possible property value. range
includes an integer range.
value and range can be used in any combination, as restrict-
ing their use would prohibit many valid descriptions. If no
value constraints are specified, the property can take on
any value.
includevalues includes all values specified by the values
block (see Value Descriptions section).
Value choices
The choices block indicates which values a UI should offer
the user:
SunOS 5.11 Last change: 10 Nov 2008 9
Standards, Environments, and Macros smftemplate(5)
range and value include ranges and individual values like
they do for constraints.
includevalues includes all values specified by either the
constraints block or the values block (see next section).
Value Descriptions
Like property names, the values a property can take on can
also have inscrutable representations. The values element
contains localized, human-readable descriptions for specific
property values:
blueloctext xml:lang='C'>blue>
name='multi-user'
type='service'
grouping='requireall'
restarton='none'
SunOS 5.11 Last change: 10 Nov 2008 11
Standards, Environments, and Macros smftemplate(5)
That service could define some basic templates data to help
an administrator using this service inside of the tags. The most helpful things are to document the
purpose of the service itself and the service-specific
configuration.
all-purpose demonstration
/commonname>
Basic configuration for foo.
Only listen to local connection requests.
Configuration file for foo.
Plugin modules for foo.
/description>
Allow foo to access the bar.
Allow foo to access baz functions.
Allow foo to access qux functions.
SunOS 5.11 Last change: 10 Nov 2008 12
Standards, Environments, and Macros smftemplate(5)
FILES
/usr/share/lib/xml/dtd/servicebundle.dtd.1
SEE ALSO
svcs(1), svccfg(1M), libscf(3LIB), servicebundle(4), smf(5)
SunOS 5.11 Last change: 10 Nov 2008 13
|
