SMF Template Extensions
Liane Praza
08/10/09
1. Summary
This case extends existing SMF templates to provide a general mechanism
for describing service configuration metadata. It includes DTD
extensions for service manifests, libscf calls, and command extensions.
It seeks Patch binding, as no incompatible interfaces are introduced.
(There are no current plans to backport this work to Solaris 10.)
Additional materials mentioned throughout this document are in
the materials subdirectory.
2. Details
In an smf(5) service manifest, we have carved out a region for holding
service metadata called the "template". It currently only holds things
like man/web page references and a localizable service name. We've long
hoped to grow this section to encompass more information.
This project extends the template metadata significantly, and modifies
a number of existing services, and a few existing commands to take
advantage of this metadata. These template extensions let us do things
like specify human-readable names and descriptions for properties and
values, let us indicate when a property isn't something a user should
see or modify, let us put some basic constraints on the values a
property can take on, and do so in a way that can be wildcarded across
classes of property groups, services, or instances.
2.1 DTD extensions
Templates are defined through a set of DTD extensions for service
manifests. An updated DTD and diffs are provided in the case
directory. In addition, smf_template(5) (provided also in the
case directory) extensively describes the new tags available to
service authors and offers guidelines for their use.
A quick overview is offered here for the options available, though
the provided smf_template(5) is more descriptive and detailed.
Property group patterns describe a property group, allowing
wildcarding on name and type (through omission in the definition),
and scoping to instance, service, restarter, or global.
short name
A longer description of the property group.
pg_patterns elements may also describe specific properties.
short name
units, if appropriate
A longer description of the property.
,
prop_patterns may describe constraints and choices for the
individual values, as well as descriptions of those values.
blue
The color between green and indigo.
2.2 libscf calls
Two new sets of new libscf calls provide composed access to the template
data. One set allows access to the extended template descriptions and
metadata. The other validates that configuration meets the constraints
defined by templates (allowing exploration of any constraint violations
encountered).
Additionally, we document and stabilize convenience functions to
convert from property type to a string, and string to property type.
Full manpages for these functions are included in the case materials,
and a list of functions introduced is included in the interface
table below.
No changes to existing libscf(3lib) calls are currently proposed.
Auditing is handled normally by configd.
2.3 Command updates
While there are a number of modifications and additions to the
existing SMF commands possible using the templates data, we've
explored a few basic changes as part of this project. We expect
more in the future, though are not pursuing them as part of this case.
2.3.1 svccfg import and validation
The existing svccfg validate subcommand is enhanced to validate
property groups and properties either in the repository or in
a manifest file against template data in the manifest itself, as
well as applicable data already in the repository. Template
validation confirms that required property groups and properties
are present, property groups and properties match their templated
definitions, and that any defined constraints on those properties
have been satisfied.
The existing svccfg import subcommand will now import template
information defined in the service manifest. It is also extended
to validate against templates during import. It emits warnings
during normal operation, and we introduce an optional -V option to
fail import if template validation fails.
2.3.2 Displaying templates
We wish to allow display of templates data both as extended
information about existing settings, as well as to provide
information about potential settings.
The -l option to svcs is extended to allow combination with
the existing -v option. In this mode, property groups of
type "application" that are not templated as 'hidden' are
displayed along with 'basic' template data.
e.g. the information added for "svcs -lv console-login" would be:
ttymon (application)
ttymon/device (astring) = /dev/console
The terminal device to be used for the console login prompt.
ttymon/label (astring) = console
The appropriate entry from /etc/ttydefs.
ttymon/modules (astring) = ldterm,ttcompat
Modules to be pushed on the terminal.
ttymon/nohangup (boolean) = true
Force hangup by temporarily setting line speed to 0.
ttymon/prompt (astring) = "`uname -n` console login:"
Prompt to be printed on console.
ttymon/terminal_type (astring) = ""
The initial value of the TERM environment variable.
ttymon/timeout (count) = 0
Delay after printing prompt before ttymon should exit.
In addition, we introduce a "describe" subcommand to svccfg
to allow exploration of template data.
describe [-v] [-t] [propertygroup/property]
It allows display of either the template data which applies to the
existing settings (by default), or of the template data only (with
the -t option).
2.4 Guidance update
The SMF ARC policy will be updated to recommend service authors
define template metadata for service-specific property groups and
properties.
2.5 Manifest updates
As part of the initial integration of the Templates project, we will
provide a set of updated manifests, including updated manifests to
describe the global and restarter generic properties.
The svc:/system/svc/global service is newly introduced to define
SMF-wide templates and settings.
2.6 Repository representation
Template data is stored in the repository in an extension to the
existing templates data, which is simply modelled as a set of
property groups and properties on the service. All template
repository representation is private.
Property groups are less indented than the properties contained in
them in the next few sections.
2.6.1 Existing Template Definitions
For reference, the repository representation for the templates
elements supported in Solaris 10 is as follows.
tm_common_name template
C ustring
US-ENG ustring
UK-ENG ustring
tm_description template
C ustring
tm_man_ template
manpath astring
section astring
title astring
2.6.2 Property Layout For New Template Information
tm_pgpatnt_<name> template_pg_pattern
tm_pgpatn_<name> template_pg_pattern
tm_pgpatt_<type> template_pg_pattern
tm_pgpat_ template_pg_pattern
name astring optional: default wildcard
property group's name
type astring optional: default wildcard
property group's type
(remember that property group types may
be service-author defined.)
required boolean optional: default 'false'
target astring optional: default 'this'
this|instance|delegate|all
common_name_<lang> ustring optional
short, localized, human readable name
description_<lang> ustring optional
localized, longer description
tm_proppat_<pg_pattern_unique>_<name> template_prop_pattern
where <pg_pattern_unique> is the part of the pg_pattern's property
group name to the right of tm_pgpat.
pg_pattern astring required
name of property group for pg_pattern
name astring required
name of property
required boolean optional: default 'false'
type astring optional: default wildcard
type is optional only if required is false.
property group's type, list of types
common_name_<lang> ustring optional
short, localized, human readable name
units_<lang> ustring optional
localized, human-readable units
description_<lang> ustring optional
localized, longer description
visibility astring optional
hidden|readonly|readwrite
cardinality_min astring count
non-negative integers
cardinality_max astring count
non-negative integers
internal_separators astring[] optional
list of separator characters for values
constraint_name astring[] optional
possible prop value or list of values
constraint_range astring optional
min,max
choices_range astring optional
min,max
choices_name astring[] optional
possible prop value or list of values
choices_include_values astring optional
[constraints|values]
values_name astring[] optional
names of value elements
value_<BASE32 name>_common_name_<lang> ustring optional
short, localized
A BASE32 encoding of
the value name is required
because the value name may
not be suitable for
property-name inclusion.
value_<BASE32 name>_description_<lang> ustring optional
localized, longer description
A BASE32 encoding of
the value name is required
because the value name may
not be suitable for
property-name inclusion.
3. Interface Table
template DTD extensions Committed
templates repository representation Private
svc:/system/svc/global Uncommitted
svccfg validate Committed
svccfg import -V Committed
svccfg describe (invocation) Committed
svccfg describe (output) Not-an-interface
svcs -lv (invocation) Committed
svcs -lv (output) Not-an-interface
scf_type_to_string() Committed
scf_string_to_type() Committed
scf_tmpl_pg_create() Committed
scf_tmpl_pg_reset() Committed
scf_tmpl_pg_destroy() Committed
scf_tmpl_get_by_pg_name() Committed
scf_tmpl_get_by_pg() Committed
scf_tmpl_iter_pgs() Committed
scf_tmpl_prop_create() Committed
scf_tmpl_prop_reset() Committed
scf_tmpl_get_by_prop() Committed
scf_tmpl_prop_destroy() Committed
scf_tmpl_iter_props() Committed
scf_tmpl_pg_name() Committed
scf_tmpl_pg_target() Committed
scf_tmpl_pg_type() Committed
scf_tmpl_pg_required() Committed
scf_tmpl_pg_common_name() Committed
scf_tmpl_pg_description() Committed
scf_tmpl_prop_name() Committed
scf_tmpl_prop_type() Committed
scf_tmpl_prop_required() Committed
scf_tmpl_prop_common_name() Committed
scf_tmpl_prop_description() Committed
scf_tmpl_prop_units() Committed
scf_tmpl_prop_visibility() Committed
scf_tmpl_visibility_to_string() Committed
scf_tmpl_prop_cardinality() Committed
scf_tmpl_prop_internal_seps() Committed
scf_tmpl_value_name_constraints() Committed
scf_count_ranges_destroy() Committed
scf_int_ranges_destroy() Committed
scf_tmpl_value_count_range_constraints() Committed
scf_tmpl_value_int_range_contraints() Committed
scf_tmpl_value_name_choices() Committed
scf_values_destroy() Committed
scf_tmpl_value_count_range_choices() Committed
scf_tmpl_value_int_range_choices() Committed
scf_tmpl_value_common_name() Committed
scf_tmpl_value_description() Committed
scf_tmpl_value_in_constraint() Committed
scf_tmpl_validate_fmri() Committed
scf_tmpl_errors_destroy() Committed
scf_tmpl_next_error() Committed
scf_tmpl_reset_errors() Committed
scf_tmpl_strerror() Committed
scf_tmpl_error_type() Committed
scf_tmpl_error_source_fmri() Committed
scf_tmpl_error_pg_tmpl() Committed
scf_tmpl_error_pg() Committed
scf_tmpl_error_prop_tmpl() Committed
scf_tmpl_error_prop() Committed
scf_tmpl_error_value() Committed
4. References
PSARC/2002/547 Greenline
PSARC/2004/524 smf(5) clarifications
5. Additional Materials
New manpages and diffs for existing manpages are available in the
case directory under the 'materials' subdirectory.