Standards, Environments, and Macros smf_template(5)
NAME
smf_template - service management framework support for ser-
vice metadataDESCRIPTION
Templates are defined by service developers to describemetadata 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 DataThe 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 DefinitionThe sole interface to define templates is the service mani-
fest. Service authors should provide template metadata includingcommon_names, 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 metadatafor 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: 18 Mar 2010 1
Standards, Environments, and Macros smf_template(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 itsinstances, 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 havedefined 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 templateblock. 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.Service and Instance Common Names The entire service or instance can define a common name to describe the purpose of the service/instance. SunOS 5.11 Last change: 18 Mar 2010 2
Standards, Environments, and Macros smf_template(5)
console login
common_name is a free-form string, but is intended to be
used as a label in a GUI or CLI. Use the following guidelines when defining a common name: o Be brief. A word or two is usually appropriate. Limit a name to under 40 characters. o Be clear. The service, property group, or property name might not be helpful for humans, butcommon_name should help clarify the purpose of the
entity.o No punctuation. common_name 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 theproperty group, suitable for a status line or a tool-tip:
Provide the text login prompt on console. SunOS 5.11 Last change: 18 Mar 2010 3
Standards, Environments, and Macros smf_template(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 pg_pattern 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 delegatedto 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: 18 Mar 2010 4
Standards, Environments, and Macros smf_template(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 pg_pattern defini-
tion, the pg_pattern is applied to all property groups that
have the specified type. Property Group NamesThe common_name element contains the localized, human-
readable name for the property group:
start method
common_name is a free-form string, but is intended to be
used as a label in a GUI or CLI.See the guidelines for common_name under "Service Instance
and Common Names," above. Property Group Description The description element contains a longer description of theproperty group, suitable for a status line or a tool-tip:
A required method which starts the service.
See the guidelines for specifying a description under "Ser-
vice and Instance Descriptions," above. PropertiesThe prop_pattern element contains the definitions for a
specific property:
SunOS 5.11 Last change: 18 Mar 2010 5
Standards, Environments, and Macros smf_template(5)
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 common_name element contains the localized, human-
readable name for the property:common_name is a free-form string field, but is intended to
be used as a label in a GUI or CLI.
retry interval
See the guidelines for common_name under "Service Instance
and Common Names," above. Property unitsThe units element contains the localized, human-readable
units for a numerical property:
seconds units Guidelines
SunOS 5.11 Last change: 18 Mar 2010 6
Standards, Environments, and Macros smf_template(5)
o Be brief. Strive to use only a single word or label. The plural form is usually the most appropriate.o No punctuation. units is not a sentence or a para-
graph. It should not contain clauses or phrases.Punctuation should be present only to meet trade-
mark requirements. Property description The description element contains a longer description of theproperty, suitable for a status line or a tool-tip:
The number of seconds to wait before retry.
See the guidelines for specifying a description under "Ser-
vice and Instance Descriptions," above. 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 theproperty 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 GUIdisplay. Hidden properties is visible in full-disclosure
modes of many commands and UIs. Property formatThe cardinality and internal_separators elements constrain
the structure of a property:SunOS 5.11 Last change: 18 Mar 2010 7
Standards, Environments, and Macros smf_template(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,
nality/> is the same as the default, zero or more values. internal_separators 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.include_values 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: 18 Mar 2010 8
Standards, Environments, and Macros smf_template(5)
range and value include ranges and individual values as they do for constraints.
include_values 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 elementcontains localized, human-readable descriptions for specific
property values:
blue
SunOS 5.11 Last change: 18 Mar 2010 9
Standards, Environments, and Macros smf_template(5)
name='multi-user'
type='service'grouping='require_all'
restart_on='none'
type='method' name='start' exec='/opt/foo/food' timeout_seconds='60'>
type='method' name='stop' exec=':kill' timeout_seconds='60'>
value='/opt/foo/foo.conf' />
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 configura-
tion.
all-purpose demonstration
SunOS 5.11 Last change: 18 Mar 2010 10
Standards, Environments, and Macros smf_template(5)
FILES
required='true'> Basic configuration for foo.
required='false'> Only listen to local connection requests.
required='true'> Configuration file for foo.
required='false'> Plugin modules for foo. /description>Allow foo to access the bar. Allow foo to access baz functions. Allow foo to access qux functions.
/usr/share/lib/xml/dtd/service_bundle.dtd.1
SunOS 5.11 Last change: 18 Mar 2010 11
Standards, Environments, and Macros smf_template(5)
SEE ALSO
svcs(1), svccfg(1M), libscf(3LIB), service_bundle(4), smf(5)
SunOS 5.11 Last change: 18 Mar 2010 12