Reformatting page.  Please Wait... done


Standards, Environments, and Macros               SMF_TEMPLATE(5)


NAME
     smf_template - 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
     common_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 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.


Illumos             Last change: Nov 10, 2008                   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 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.

       <service ... >
          <template>
          </template>


Illumos             Last change: Nov 10, 2008                   2


Standards, Environments, and Macros               SMF_TEMPLATE(5)


       </service>


  Service and Instance Common Names
     The entire service or instance can define a common  name  to
     describe the purpose of the service/instance.

       <template>
         <common_name>
             <loctext xml:lang='C'>console login</loctext>
         </common_name>
       <template>


     common_name 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
              common_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 the
     property group, suitable for a status line or a tool-tip:

       <template>
         <description>
            <loctext xml:lang='C'>Provide the text login prompt on console.
            </lcotext>
         </description>
       <template>


Illumos             Last change: Nov 10, 2008                   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.

       <template>
          <documentation>
             <manpage title='ttymon' section='1M' manpath='/usr/share/man' />
             <doc_link name='docs.sun.com' uri='http://docs.sun.com' />
           </documentation>
       </template>


  Property Groups
     The pg_pattern element contains the definitions for  a  pro-
     perty group:

       <template>
         <pg_pattern name="pgname" type="pgtype" target="this" required="true">
         </pg_pattern>
       </template>


     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".


Illumos             Last change: Nov 10, 2008                   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 Names
     The  common_name  element  contains  the  localized,  human-
     readable name for the property group:

       <pg_pattern ...>
         <common_name>
           <loctext xml:lang='C'>startt method</loctext>
         </common_name>
       </pg_pattern>


     common_name 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
              common_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.

  Property Group Description
     The description element contains a longer description of the
     property group, suitable for a status line or a tool-tip:

       <pg_pattern ...>
         <description>


Illumos             Last change: Nov 10, 2008                   5


Standards, Environments, and Macros               SMF_TEMPLATE(5)


           <loctext xml:lang='C'>A required method which starts the service.
          </loctext>
          </description>
       </pg_pattern>


     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 prop_pattern element  contains  the  definitions  for  a
     specific property:

       <pg_pattern ...>
         <prop_pattern name="propname" type="proptype" required="true">
         </prop_pattern>
       </pg_pattern>


     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.

       <prop_pattern ...>
       <common_name>
         <loctext xml:lang='C'>retry interval</loctext>
       </common_name>


Illumos             Last change: Nov 10, 2008                   6


Standards, Environments, and Macros               SMF_TEMPLATE(5)


       </prop_pattern>


     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
              common_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.

  Property units
     The units element  contains  the  localized,  human-readable
     units for a numerical property:

       <prop_pattern ...>
         <units>
           <loctext xml:lang='C'>seconds</loctext>
         </units>
       </prop_pattern>


     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:


Illumos             Last change: Nov 10, 2008                   7


Standards, Environments, and Macros               SMF_TEMPLATE(5)


       <prop_pattern ...>
          <description> <loctext xml:lang='C'>
           The number of seconds to wait before retry.
           </loctext> </description>
       </prop_pattern>


     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.

       <prop_pattern ...>
         <visibility value="hidden | readonly | readwrite"/>
       </prop_pattern>


     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 internal_separators  elements  constrain
     the structure of a property:

       <prop_pattern ...>
         <cardinality min="1" max="1"/>
         <internal_separators>,<internal_separators>
       </prop_pattern>


Illumos             Last change: Nov 10, 2008                   8


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, <cardi-
     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:

       <prop_pattern ...>
       <constraints>
              <value name="blue" />
              <range min="1" max="7"/>
              <include_values type="values"/>
       </constraints>
       </prop_pattern>


     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:

       <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>


Illumos             Last change: Nov 10, 2008                   9


Standards, Environments, and Macros               SMF_TEMPLATE(5)


     range and value include ranges and  individual  values  like
     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 element
     contains localized, human-readable descriptions for specific
     property values:

       <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>


     common_name is a free-form string field, 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
              common_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.


Illumos             Last change: Nov 10, 2008                  10


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.

EXAMPLES
     Assuming a basic service which wants to  define  basic  tem-
     plates   data looks like this:

       <?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>


Illumos             Last change: Nov 10, 2008                  11


Standards, Environments, and Macros               SMF_TEMPLATE(5)


     That service could define some basic templates data to  help
     an    administrator  using  this service inside of the <ser-
     vice> tags.  The  most helpful things are  to  document  the
     purpose  of  the  service    itself and the service-specific
     configuration.

       <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.


Illumos             Last change: Nov 10, 2008                  12


Standards, Environments, and Macros               SMF_TEMPLATE(5)


                                            </loctext> </description>
                                            </value>
                                </values>
                                <choices>
                                    <include_values type='values'/>
                                </choices>
                         <prop_pattern>
               </pg_pattern>
       </template>


FILES
     /usr/share/lib/xml/dtd/service_bundle.dtd.1

SEE ALSO
     svcs(1)svccfg(1M)libscf(3LIB)service_bundle(4)smf(5)


Illumos             Last change: Nov 10, 2008                  13