'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SMF_TEMPLATE 5 "Nov 10, 2008"
.SH NAME
smf_template \- service management framework support for service metadata
.SH DESCRIPTION
.sp
.LP
Templates are defined by service developers to describe metadata about a
service in general or individual configuration properties on a service,
including human-consumable descriptions as well as definitions of valid
configuration.
.sp
.LP
Administrators are provided access to templates through SMF commands that
describe configuration values and validate configuration against templates.
.sp
.LP
Tool developers can use templates to provide more helpful user interfaces for
service configuration.
.SS "Template Data"
.sp
.LP
Service metadata is defined in the template as part of the service manifest.
.SS "Consuming Template Data"
.sp
.LP
The \fBsvcs -lv\fR and \fBsvccfg describe\fR commands can be used to access
metadata about properties in a human-readable format.
.sp
.LP
\fBsvccfg\fR(1M)'s \fBvalidate\fR subcommand can be used to validate a service
instance or manifest against template data. A set of \fBlibscf\fR(3LIB)
interfaces is available to access template data.
.SS "Template Definition"
.sp
.LP
The sole interface to define templates is the service manifest.
.sp
.LP
Service authors should provide template metadata including \fBcommon_names\fR,
\fBdescriptions\fR, \fBchoices\fR and \fBconstraints\fR 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.
.sp
.LP
See the \fBEXAMPLES\fR section for an example of authoring a template
definition for a service.
.SS "Template Composition"
.sp
.LP
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.
.sp
.LP
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 typical 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.
.sp
.LP
Restarter authors can define templates in their manifest that apply to any
service which uses their restarter, which is also known as a \fBdelegate\fR.
SMF framework authors have defined templates for property groups with
well-known meanings to the entire SMF framework in the manifest for
\fBsvc:/system/svc/global\fR.
.sp
.LP
Templates defined globally or by the restarter and re-defined by the service or
instance are flagged as a validation error. Service authors can avoid these
errors by creating templates only for property groups specific to their service
and not consumed by the SMF framework.
.sp
.LP
Property group templates can also be wildcarded by name or type. Only the most
specific template definition applicable to a property group is honored.
.SS "Template Details"
.SS "Service and Instance Templates"
.sp
.LP
The \fBtemplate\fR element defines the start of a template block. All further
definitions below can be included in a template block. A \fBtemplate\fR element
can be contained in either a \fBservice\fR or \fBinstance\fR element. If it is
contained in the \fBservice\fR element, it applies to the service and all
instances of that service. If it is contained in the \fBinstance\fR element, it
applies to only that instance of the service.
.sp
.LP
Whenever possible, we recommend defining the template data for the entire
service.
.sp
.in +2
.nf
<service ... >
   <template>
   </template>
</service>
.fi
.in -2

.SS "Service and Instance Common Names"
.sp
.LP
The entire service or instance can define a common name to describe the purpose
of the service/instance.
.sp
.in +2
.nf
<template>
  <common_name>
      <loctext xml:lang='C'>console login</loctext>
  </common_name>
<template>
.fi
.in -2

.sp
.LP
\fIcommon_name\fR is a free-form string, but is intended to be used as a label
in a GUI or CLI.
.sp
.LP
The following guidelines are recommended:
.RS +4
.TP
.ie t \(bu
.el o
Be brief. A word or two is usually most appropriate. Limit the name to under 40
characters.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Be clear. The service, property group, or property name might not be helpful
for humans, but \fIcommon_name\fR should help clarify the purpose of the
entity.
.RE
.RS +4
.TP
.ie t \(bu
.el o
No punctuation. \fIcommon_name\fR is not a sentence or a paragraph. It should
not contain clauses or phrases. Punctuation should only be present to meet
trademark requirements.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Capital letters must be used only for acronyms or proper names. For locales
other than English, use appropriate capitalization for a sentence fragment.
.RE
.SS "Service and Instance Descriptions"
.sp
.LP
The description element contains a longer description of the property group,
suitable for a status line or a tool-tip:
.sp
.in +2
.nf
<template>
  <description>
     <loctext xml:lang='C'>Provide the text login prompt on console.
     </lcotext>
  </description>
<template>
.fi
.in -2

.sp
.LP
\fIdescription\fR Guidelines
.RS +4
.TP
.ie t \(bu
.el o
Use proper grammar. \fIdescription\fR is a sentence meant to be read by humans.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Be brief.  A few sentences are usually most appropriate.
.RE
.SS "Documentation"
.sp
.LP
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.
.sp
.LP
Documentation can include man pages or references to stable URLs for reference
documentation.
.sp
.in +2
.nf
<template>
   <documentation>
      <manpage title='ttymon' section='1M' manpath='/usr/share/man' />
      <doc_link name='docs.sun.com' uri='http://docs.sun.com' />
    </documentation>
</template>
.fi
.in -2

.SS "Property Groups"
.sp
.LP
The \fBpg_pattern\fR element contains the definitions for a property group:
.sp
.in +2
.nf
<template>
  <pg_pattern name="pgname" type="pgtype" target="this" required="true">
  </pg_pattern>
</template>
.fi
.in -2

.sp
.LP
\fIname\fR is the property group's name, and \fItype\fR is the property group's
type.
.sp
.LP
\fItarget\fR specifies what the target of this definition is. \fB"this"\fR
would refer to the defining service or instance. \fB"instance"\fR can only be
used in a service's template block, and means the definition applies to all
instances of this service. \fB"delegate"\fR can only be used in a restarter's
template block, and applies to all instances that are delegated to that
restarter. \fB"all"\fR, only usable by the master restarter, would refer to all
services on the system. The default value of target is \fB"this"\fR.
.sp
.LP
\fBrequired\fR indicates whether this property group is required or not. The
default value of required is \fBfalse\fR. If \fBrequired\fR is \fBtrue\fR, both
\fIname\fR and \fItype\fR must be specified.
.sp
.LP
\fIname\fR and/or \fItype\fR can be omitted. If either of these attributes is
omitted it is treated as a wildcard. For instance, if the name attribute is
omitted from the \fBpg_pattern\fR definition, the \fBpg_pattern\fR is applied
to all property groups that have the specified type.
.SS "Property Group Names"
.sp
.LP
The \fIcommon_name\fR element contains the localized, human-readable name for
the property group:
.sp
.in +2
.nf
<pg_pattern ...>
  <common_name>
    <loctext xml:lang='C'>startt method</loctext>
  </common_name>
</pg_pattern>
.fi
.in -2

.sp
.LP
\fIcommon_name\fR is a free-form string, but is intended to be used as a label
in a GUI or CLI.
.sp
.LP
The following guidelines are recommended:
.RS +4
.TP
.ie t \(bu
.el o
Be brief. A word or two is usually most appropriate.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Be clear. The service, property group, or property name might not be helpful
for humans, but \fIcommon_name\fR should help clarify the purpose of the
entity.
.RE
.RS +4
.TP
.ie t \(bu
.el o
No punctuation. \fIcommon_name\fR is not a sentence or a paragraph. It should
not contain clauses or phrases. Punctuation should only be present to meet
trademark requirements.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Capital letters must be used only for acronyms or proper names. For locales
other than English, use appropriate capitalization for a sentence fragment.
.RE
.SS "Property Group Description"
.sp
.LP
The \fIdescription\fR element contains a longer description of the property
group, suitable for a status line or a tool-tip:
.sp
.in +2
.nf
<pg_pattern ...>
  <description>
    <loctext xml:lang='C'>A required method which starts the service.
   </loctext>
   </description>
</pg_pattern>
.fi
.in -2

.sp
.LP
\fIdescription\fR Guidelines
.RS +4
.TP
.ie t \(bu
.el o
Use proper grammar. description is a sentence meant to be read by humans.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Be brief. A few sentences are usually most appropriate.
.RE
.SS "Properties"
.sp
.LP
The \fIprop_pattern\fR element contains the definitions for a specific
property:
.sp
.in +2
.nf
<pg_pattern ...>
  <prop_pattern name="propname" type="proptype" required="true">
  </prop_pattern>
</pg_pattern>
.fi
.in -2

.sp
.LP
\fIname\fR is the property's name, and \fItype\fR is the property's type.
.sp
.LP
\fBrequired\fR indicates whether this property is required. The default value
of \fBrequired\fR is \fBfalse\fR.
.sp
.LP
\fIname\fR is always required. \fItype\fR is optional only if \fBrequired\fR is
\fBfalse\fR.
.SS "Property Names"
.sp
.LP
The \fIcommon_name\fR element contains the localized, human-readable name for
the property:
.sp
.in +2
.nf

.fi
.in -2

.sp
.LP
\fIcommon_name\fR is a free-form string field, but is intended to be used as a
label in a GUI or CLI.
.sp
.in +2
.nf
<prop_pattern ...>
<common_name>
  <loctext xml:lang='C'>retry interval</loctext>
</common_name>
</prop_pattern>
.fi
.in -2

.sp
.LP
The following guidelines are recommended:
.RS +4
.TP
.ie t \(bu
.el o
Be brief. A word or two is usually most appropriate.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Be clear. The service, property group, or property name might not be helpful
for humans, but \fIcommon_name\fR should help clarify the purpose of the
entity.
.RE
.RS +4
.TP
.ie t \(bu
.el o
No punctuation. \fIcommon_name\fR is not a sentence or a paragraph. It should
not contain clauses or phrases. Punctuation should only be present to meet
trademark requirements.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Capital letters must be used only for acronyms or proper names. For locales
other than English, use appropriate capitalization for a sentence fragment.
.RE
.SS "Property units"
.sp
.LP
The \fIunits\fR element contains the localized, human-readable units for a
numerical property:
.sp
.in +2
.nf
<prop_pattern ...>
  <units>
    <loctext xml:lang='C'>seconds</loctext>
  </units>
</prop_pattern>
.fi
.in -2

.sp
.LP
\fIunits\fR Guidelines
.sp
.LP
The following guidelines are recommended:
.RS +4
.TP
.ie t \(bu
.el o
Be brief. Strive to use only a single word or label. The plural form is usually
most appropriate.
.RE
.RS +4
.TP
.ie t \(bu
.el o
No punctuation. units is not a sentence or a paragraph. It should not contain
clauses or phrases. Punctuation should only be present to meet trademark
requirements.
.RE
.SS "Property description"
.sp
.LP
The \fIdescription\fR element contains a longer description of the property,
suitable for a status line or a tool-tip:
.sp
.in +2
.nf
<prop_pattern ...>
   <description> <loctext xml:lang='C'>
    The number of seconds to wait before retry.
    </loctext> </description>
</prop_pattern>
.fi
.in -2

.sp
.LP
\fIdescription\fR Guidelines
.RS +4
.TP
.ie t \(bu
.el o
Use proper grammar. \fIdescription\fR is a sentence meant to be read by humans.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Be brief. A few sentences are usually most appropriate.
.RE
.SS "Property visibility"
.sp
.LP
The \fIvisibility\fR element specifies whether simplified views in higher level
software might want to display this property.
.sp
.in +2
.nf
<prop_pattern ...>
  <visibility value="hidden | readonly | readwrite"/>
</prop_pattern>
.fi
.in -2

.sp
.LP
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, \fBreadonly\fR means that the property isn't
intended to be modified, and \fBreadwrite\fR indicates the property is
modifiable.
.sp
.LP
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.
.SS "Property format"
.sp
.LP
The \fIcardinality\fR and \fIinternal_separators\fR elements constrain the
structure of a property:
.sp
.in +2
.nf
<prop_pattern ...>
  <cardinality min="1" max="1"/>
  <internal_separators>,<internal_separators>
</prop_pattern>
.fi
.in -2

.sp
.LP
\fIcardinality\fR indicates the acceptable number of property values. \fImin\fR
is the minimum number, and \fImax\fR is the maximum number. Both are optional.
If neither is specified, \fB<cardinality/>\fR is the same as the default, zero
or more values.
.sp
.LP
\fIinternal_separators\fR specify the separator characters used for those
property values into which multiple real values are packed.
.SS "Value constraints"
.sp
.LP
The \fIconstraints\fR element specifies what values are acceptable for a
property:
.sp
.in +2
.nf
<prop_pattern ...>
<constraints>
       <value name="blue" />
       <range min="1" max="7"/>
       <include_values type="values"/>
</constraints>
</prop_pattern>
.fi
.in -2

.sp
.LP
The \fIvalue\fR element includes a possible property value. range includes an
integer range.
.sp
.LP
\fIvalue\fR and \fIrange\fR can be used in any combination, as restricting
their use would prohibit many valid descriptions. If no value constraints are
specified, the property can take on any value.
.sp
.LP
\fIinclude_values\fR includes all values specified by the values block (see
\fBValue Descriptions\fR section).
.SS "Value choices"
.sp
.LP
The choices block indicates which values a UI should offer the user:
.sp
.in +2
.nf
<prop_pattern ...>
<choices>
      <range min="1" max="3"/>
      <value name="vt100" />
      <value name="xterm" />
      <include_values type="constraints"/>
      <include_values type="values"/>
</choices>
</prop_pattern>
.fi
.in -2

.sp
.LP
range and value include ranges and individual values like they do for
constraints.
.sp
.LP
\fIinclude_values\fR includes all values specified by either the constraints
block or the values block (see next section).
.SS "Value Descriptions"
.sp
.LP
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:
.sp
.in +2
.nf
<prop_pattern>
<values>
      <value name="blue">
              <common_name>
                      <loctext xml:lang='C'>blueloctext xml:lang='C'>blue>
              </common_name>
              <description>
                      <loctext xml:lang='C>
                              The color between green and indigo.
                      </loctext>
              </description>
      </value>
</values>
</prop_pattern>
.fi
.in -2

.sp
.LP
\fIcommon_name\fR is a free-form string field, but is intended to be used as a
label in a GUI or CLI.
.sp
.LP
The following guidelines are recommended:
.RS +4
.TP
.ie t \(bu
.el o
Be brief. A word or two is usually most appropriate.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Be clear. The service, property group, or property name might not be helpful
for humans, but \fIcommon_name\fR should help clarify the purpose of the
entity.
.RE
.RS +4
.TP
.ie t \(bu
.el o
No punctuation. \fIcommon_name\fR is not a sentence or a paragraph. It should
not contain clauses or phrases. Punctuation should only be present to meet
trademark requirements.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Capital letters must be used only for acronyms or proper names. For locales
other than English, use appropriate capitalization for a sentence fragment.
.RE
.sp
.LP
description Guidelines
.RS +4
.TP
.ie t \(bu
.el o
Use proper grammar. description is a sentence meant to be read by humans.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Be brief. A few sentences are usually most appropriate.
.RE
.SH EXAMPLES
.sp
.LP
Assuming a basic service which wants to define basic templates   data looks
like this:
.sp
.in +2
.nf
<?xml version="1.0"?
<!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">
<service_bundle type='manifest' name='FOOfoo:foo'>
<service name='system/foo' type='service' version='1'>
      <dependency>
              name='multi-user'
              type='service'
              grouping='require_all'
              restart_on='none'
              <service_fmri value='svc:/milestone/multi-user' />
      </dependency>
      <exec_method
              type='method'
              name='start'
              exec='/opt/foo/food'
              timeout_seconds='60'>
      </exec_method>
      <exec_method
              type='method'
              name='stop'
              exec=':kill'
              timeout_seconds='60'>
      </exec_method>
      <property_group name='config' type='application'>
              <propval name='local_only' type='boolean' value='false' />
              <propval name='config_file' type='astring'
                  value='/opt/foo/foo.conf' />
      <property name='modules' type='astring'>
         <astring_list>
               <value_node value='bar'/>
               <value_node value='baz'/>
         </astring_list>
        </property>
      </property_group>

      <instance name='default' enabled='false' />
</service_bundle>
</service>
.fi
.in -2

.sp
.LP
That service could define some basic templates data to help an   administrator
using this service inside of the \fB<service>\fR tags.  The  most helpful
things are to document the purpose of the service   itself and the
service-specific configuration.
.sp
.in +2
.nf
<template>
       <common_name> <loctext xml:lang='C'>
           all-purpose demonstration
       </loctext> /common_name>
       <documentation>
                <manpage title='food' section='1M'
                         manpath='/opt/foo/man' />
       </documentation>

       <pg_pattern name='config' type='application' target='this'
           required='true'>
               <description> <loctext xml:lang='C'>
                   Basic configuration for foo.
                </loctext> </description>
                <prop_pattern name='local_only' type='boolean'
                    required='false'>
                       <description> <loctext xml:lang='C'>
                           Only listen to local connection requests.
                       </loctext> </description>
                </prop_pattern>
                <prop_pattern name='config_file' type='astring'
                     required='true'>
                        <cardinality min='1' max='1'/>
                        <description> <loctext xml:lang='C'>
                             Configuration file for foo.
                         </loctext> </description>
                 </prop_pattern>
                 <prop_pattern name='modules' type='astring'
                     required='false'>
                         <description> <loctext xml:lang='C'>
                             Plugin modules for foo.
                          </loctext> /description>
                          <values>
                                   <value name='bar'>
                                   <description> <loctext xml:lang='C'>
                                       Allow foo to access the bar.
                                    </loctext> </description>
                                    </value>
                                    <value name='baz'>
                                    <description> <loctext xml:lang='C'>
                                       Allow foo to access baz functions.
                                    </loctext> </description>
                                    </value>
                                    <value name='qux'>
                                    <description> <loctext xml:lang='C'>
                                       Allow foo to access qux functions.
                                     </loctext> </description>
                                     </value>
                         </values>
                         <choices>
                             <include_values type='values'/>
                         </choices>
                  <prop_pattern>
        </pg_pattern>
</template>
.fi
.in -2

.SH FILES
.sp
.LP
\fB/usr/share/lib/xml/dtd/service_bundle.dtd.1\fR
.SH SEE ALSO
.sp
.LP
\fBsvcs\fR(1), \fBsvccfg\fR(1M), \fBlibscf\fR(3LIB), \fBservice_bundle\fR(4),
\fBsmf\fR(5)