1smf_template(5) Standards, Environments, and Macros smf_template(5)
2
6 smf_template - service management framework support for service meta‐
7 data
8
10 Templates are defined by service developers to describe metadata about
11 a service in general or individual configuration properties on a ser‐
12 vice, including human-consumable descriptions as well as definitions of
13 valid configuration.
14 Administrators are provided access to templates through SMF commands
17 that describe configuration values and validate configuration against
18 templates.
19 Tool developers can use templates to provide more helpful user inter‐
22 faces for service configuration.
23 Template Data
25 Service metadata is defined in the template as part of the service man‐
26 ifest.
27 Consuming Template Data
29 The svcs -lv and svccfg describe commands can be used to access meta‐
30 data about properties in a human-readable format.
31 svccfg(1M)'s validate subcommand can be used to validate a service
34 instance or manifest against template data. A set of libscf(3LIB)
35 interfaces is available to access template data.
36 Template Definition
38 The sole interface to define templates is the service manifest.
39 Service authors should provide template metadata including com‐
42 mon_names, descriptions, choices and constraints for service-specific
43 property groups and properties which they introduce. At a minimum, ser‐
44 vice authors must provide descriptions for property groups and proper‐
45 ties in the C locale. Service authors should not provide template meta‐
46 data for framework-delivered property groups such as methods and depen‐
47 dencies.
48 See the EXAMPLES section for an example of authoring a template defini‐
51 tion for a service.
52 Template Composition
54 All template interfaces search for template data about a property group
55 first on the instance, then on the service, then on the service's
56 restarter, and finally globally.
57 A property group template is defined by its author to apply to a spe‐
60 cific instance, to a service and all of its instances, to a restarter's
61 delegates, or globally. A typical service author defines the template
62 on an instance or on a service. A template defined on an instance is
63 applied to that instance only, and can override a template for that
64 property group defined on the service. A template defined on the ser‐
65 vice is applied to all instances of that service.
66 Restarter authors can define templates in their manifest that apply to
69 any service which uses their restarter, which is also known as a dele‐
70 gate. SMF framework authors have defined templates for property groups
71 with well-known meanings to the entire SMF framework in the manifest
72 for svc:/system/svc/global.
73 Templates defined globally or by the restarter and re-defined by the
76 service or instance are flagged as a validation error. Service authors
77 can avoid these errors by creating templates only for property groups
78 specific to their service and not consumed by the SMF framework.
79 Property group templates can also be wildcarded by name or type. Only
82 the most specific template definition applicable to a property group is
83 honored.
84 Template Details
86 Service and Instance Templates
87 The template element defines the start of a template block. All further
88 definitions below can be included in a template block. A template ele‐
89 ment can be contained in either a service or instance element. If it is
90 contained in the service element, it applies to the service and all
91 instances of that service. If it is contained in the instance element,
92 it applies to only that instance of the service.
93 Whenever possible, we recommend defining the template data for the
96 entire service.
97 <service ... >
99 <template>
100 </template>
101 </service>
102 Service and Instance Common Names
105 The entire service or instance can define a common name to describe the
106 purpose of the service/instance.
107 <template>
109 <common_name>
110 <loctext xml:lang='C'>console login</loctext>
111 </common_name>
112 <template>
113 common_name is a free-form string, but is intended to be used as a
117 label in a GUI or CLI.
118 The following guidelines are recommended:
121 o Be brief. A word or two is usually most appropriate. Limit
123 the name to under 40 characters.
124 o Be clear. The service, property group, or property name
126 might not be helpful for humans, but common_name should help
127 clarify the purpose of the entity.
128 o No punctuation. common_name is not a sentence or a para‐
130 graph. It should not contain clauses or phrases. Punctuation
131 should only be present to meet trademark requirements.
132 o Capital letters must be used only for acronyms or proper
134 names. For locales other than English, use appropriate capi‐
135 talization for a sentence fragment.
136 Service and Instance Descriptions
138 The description element contains a longer description of the property
139 group, suitable for a status line or a tool-tip:
140 <template>
142 <description>
143 <loctext xml:lang='C'>Provide the text login prompt on console.
144 </lcotext>
145 </description>
146 <template>
147 description Guidelines
151 o Use proper grammar. description is a sentence meant to be
153 read by humans.
154 o Be brief. A few sentences are usually most appropriate.
156 Documentation
158 Documentation for this service can be defined explicitly, so that when
159 the service is experiencing issues, or a consumer of the service wants
160 more information on it, they can find it easily.
161 Documentation can include man pages or references to stable URLs for
164 reference documentation.
165 <template>
167 <documentation>
168 <manpage title='ttymon' section='1M' manpath='/usr/share/man' />
169 <doc_link name='docs.sun.com' uri='http://docs.sun.com' />
170 </documentation>
171 </template>
172 Property Groups
175 The pg_pattern element contains the definitions for a property group:
176 <template>
178 <pg_pattern name="pgname" type="pgtype" target="this" required="true">
179 </pg_pattern>
180 </template>
181 name is the property group's name, and type is the property group's
185 type.
186 target specifies what the target of this definition is. "this" would
189 refer to the defining service or instance. "instance" can only be used
190 in a service's template block, and means the definition applies to all
191 instances of this service. "delegate" can only be used in a restarter's
192 template block, and applies to all instances that are delegated to that
193 restarter. "all", only usable by the master restarter, would refer to
194 all services on the system. The default value of target is "this".
195 required indicates whether this property group is required or not. The
198 default value of required is false. If required is true, both name and
199 type must be specified.
200 name and/or type can be omitted. If either of these attributes is omit‐
203 ted it is treated as a wildcard. For instance, if the name attribute is
204 omitted from the pg_pattern definition, the pg_pattern is applied to
205 all property groups that have the specified type.
206 Property Group Names
208 The common_name element contains the localized, human-readable name for
209 the property group:
210 <pg_pattern ...>
212 <common_name>
213 <loctext xml:lang='C'>startt method</loctext>
214 </common_name>
215 </pg_pattern>
216 common_name is a free-form string, but is intended to be used as a
220 label in a GUI or CLI.
221 The following guidelines are recommended:
224 o Be brief. A word or two is usually most appropriate.
226 o Be clear. The service, property group, or property name
228 might not be helpful for humans, but common_name should help
229 clarify the purpose of the entity.
230 o No punctuation. common_name is not a sentence or a para‐
232 graph. It should not contain clauses or phrases. Punctuation
233 should only be present to meet trademark requirements.
234 o Capital letters must be used only for acronyms or proper
236 names. For locales other than English, use appropriate capi‐
237 talization for a sentence fragment.
238 Property Group Description
240 The description element contains a longer description of the property
241 group, suitable for a status line or a tool-tip:
242 <pg_pattern ...>
244 <description>
245 <loctext xml:lang='C'>A required method which starts the service.
246 </loctext>
247 </description>
248 </pg_pattern>
249 description Guidelines
253 o Use proper grammar. description is a sentence meant to be
255 read by humans.
256 o Be brief. A few sentences are usually most appropriate.
258 Properties
260 The prop_pattern element contains the definitions for a specific prop‐
261 erty:
262 <pg_pattern ...>
264 <prop_pattern name="propname" type="proptype" required="true">
265 </prop_pattern>
266 </pg_pattern>
267 name is the property's name, and type is the property's type.
271 required indicates whether this property is required. The default value
274 of required is false.
275 name is always required. type is optional only if required is false.
278 Property Names
280 The common_name element contains the localized, human-readable name for
281 the property:
282 common_name is a free-form string field, but is intended to be used as
288 a label in a GUI or CLI.
289 <prop_pattern ...>
291 <common_name>
292 <loctext xml:lang='C'>retry interval</loctext>
293 </common_name>
294 </prop_pattern>
295 The following guidelines are recommended:
299 o Be brief. A word or two is usually most appropriate.
301 o Be clear. The service, property group, or property name
303 might not be helpful for humans, but common_name should help
304 clarify the purpose of the entity.
305 o No punctuation. common_name is not a sentence or a para‐
307 graph. It should not contain clauses or phrases. Punctuation
308 should only be present to meet trademark requirements.
309 o Capital letters must be used only for acronyms or proper
311 names. For locales other than English, use appropriate capi‐
312 talization for a sentence fragment.
313 Property units
315 The units element contains the localized, human-readable units for a
316 numerical property:
317 <prop_pattern ...>
319 <units>
320 <loctext xml:lang='C'>seconds</loctext>
321 </units>
322 </prop_pattern>
323 units Guidelines
327 The following guidelines are recommended:
330 o Be brief. Strive to use only a single word or label. The
332 plural form is usually most appropriate.
333 o No punctuation. units is not a sentence or a paragraph. It
335 should not contain clauses or phrases. Punctuation should
336 only be present to meet trademark requirements.
337 Property description
339 The description element contains a longer description of the property,
340 suitable for a status line or a tool-tip:
341 <prop_pattern ...>
343 <description> <loctext xml:lang='C'>
344 The number of seconds to wait before retry.
345 </loctext> </description>
346 </prop_pattern>
347 description Guidelines
351 o Use proper grammar. description is a sentence meant to be
353 read by humans.
354 o Be brief. A few sentences are usually most appropriate.
356 Property visibility
358 The visibility element specifies whether simplified views in higher
359 level software might want to display this property.
360 <prop_pattern ...>
362 <visibility value="hidden | readonly | readwrite"/>
363 </prop_pattern>
364 Some properties are internal implementation details and should not be
368 presented as a configuration setting. Others might merely be read-only.
369 This property is used to specify these restrictions. A value of hidden
370 indicates that the property shouldn't be displayed, readonly means that
371 the property isn't intended to be modified, and readwrite indicates the
372 property is modifiable.
373 This is not a security mechanism, it is solely intended to help prevent
376 the user from shooting himself in the foot, and to remove unnecessary
377 clutter from CLI output or a GUI display. Hidden properties is visible
378 in full-disclosure modes of many commands and UIs.
379 Property format
381 The cardinality and internal_separators elements constrain the struc‐
382 ture of a property:
383 <prop_pattern ...>
385 <cardinality min="1" max="1"/>
386 <internal_separators>,<internal_separators>
387 </prop_pattern>
388 cardinality indicates the acceptable number of property values. min is
392 the minimum number, and max is the maximum number. Both are optional.
393 If neither is specified, <cardinality/> is the same as the default,
394 zero or more values.
395 internal_separators specify the separator characters used for those
398 property values into which multiple real values are packed.
399 Value constraints
401 The constraints element specifies what values are acceptable for a
402 property:
403 <prop_pattern ...>
405 <constraints>
406 <value name="blue" />
407 <range min="1" max="7"/>
408 <include_values type="values"/>
409 </constraints>
410 </prop_pattern>
411 The value element includes a possible property value. range includes an
415 integer range.
416 value and range can be used in any combination, as restricting their
419 use would prohibit many valid descriptions. If no value constraints are
420 specified, the property can take on any value.
421 include_values includes all values specified by the values block (see
424 Value Descriptions section).
425 Value choices
427 The choices block indicates which values a UI should offer the user:
428 <prop_pattern ...>
430 <choices>
431 <range min="1" max="3"/>
432 <value name="vt100" />
433 <value name="xterm" />
434 <include_values type="constraints"/>
435 <include_values type="values"/>
436 </choices>
437 </prop_pattern>
438 range and value include ranges and individual values like they do for
442 constraints.
443 include_values includes all values specified by either the constraints
446 block or the values block (see next section).
447 Value Descriptions
449 Like property names, the values a property can take on can also have
450 inscrutable representations. The values element contains localized,
451 human-readable descriptions for specific property values:
452 <prop_pattern>
454 <values>
455 <value name="blue">
456 <common_name>
457 <loctext xml:lang='C'>blueloctext xml:lang='C'>blue>
458 </common_name>
459 <description>
460 <loctext xml:lang='C>
461 The color between green and indigo.
462 </loctext>
463 </description>
464 </value>
465 </values>
466 </prop_pattern>
467 common_name is a free-form string field, but is intended to be used as
471 a label in a GUI or CLI.
472 The following guidelines are recommended:
475 o Be brief. A word or two is usually most appropriate.
477 o Be clear. The service, property group, or property name
479 might not be helpful for humans, but common_name should help
480 clarify the purpose of the entity.
481 o No punctuation. common_name is not a sentence or a para‐
483 graph. It should not contain clauses or phrases. Punctuation
484 should only be present to meet trademark requirements.
485 o Capital letters must be used only for acronyms or proper
487 names. For locales other than English, use appropriate capi‐
488 talization for a sentence fragment.
489 description Guidelines
492 o Use proper grammar. description is a sentence meant to be
494 read by humans.
495 o Be brief. A few sentences are usually most appropriate.
497
499 Assuming a basic service which wants to define basic templates data
500 looks like this:
501 <?xml version="1.0"?
503 <!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">
504 <service_bundle type='manifest' name='FOOfoo:foo'>
505 <service name='system/foo' type='service' version='1'>
506 <dependency>
507 name='multi-user'
508 type='service'
509 grouping='require_all'
510 restart_on='none'
511 <service_fmri value='svc:/milestone/multi-user' />
512 </dependency>
513 <exec_method
514 type='method'
515 name='start'
516 exec='/opt/foo/food'
517 timeout_seconds='60'>
518 </exec_method>
519 <exec_method
520 type='method'
521 name='stop'
522 exec=':kill'
523 timeout_seconds='60'>
524 </exec_method>
525 <property_group name='config' type='application'>
526 <propval name='local_only' type='boolean' value='false' />
527 <propval name='config_file' type='astring'
528 value='/opt/foo/foo.conf' />
529 <property name='modules' type='astring'>
530 <astring_list>
531 <value_node value='bar'/>
532 <value_node value='baz'/>
533 </astring_list>
534 </property>
535 </property_group>
536 <instance name='default' enabled='false' />
538 </service_bundle>
539 </service>
540 That service could define some basic templates data to help an admin‐
544 istrator using this service inside of the <service> tags. The most
545 helpful things are to document the purpose of the service itself and
546 the service-specific configuration.
547 <template>
549 <common_name> <loctext xml:lang='C'>
550 all-purpose demonstration
551 </loctext> /common_name>
552 <documentation>
553 <manpage title='food' section='1M'
554 manpath='/opt/foo/man' />
555 </documentation>
556 <pg_pattern name='config' type='application' target='this'
558 required='true'>
559 <description> <loctext xml:lang='C'>
560 Basic configuration for foo.
561 </loctext> </description>
562 <prop_pattern name='local_only' type='boolean'
563 required='false'>
564 <description> <loctext xml:lang='C'>
565 Only listen to local connection requests.
566 </loctext> </description>
567 </prop_pattern>
568 <prop_pattern name='config_file' type='astring'
569 required='true'>
570 <cardinality min='1' max='1'/>
571 <description> <loctext xml:lang='C'>
572 Configuration file for foo.
573 </loctext> </description>
574 </prop_pattern>
575 <prop_pattern name='modules' type='astring'
576 required='false'>
577 <description> <loctext xml:lang='C'>
578 Plugin modules for foo.
579 </loctext> /description>
580 <values>
581 <value name='bar'>
582 <description> <loctext xml:lang='C'>
583 Allow foo to access the bar.
584 </loctext> </description>
585 </value>
586 <value name='baz'>
587 <description> <loctext xml:lang='C'>
588 Allow foo to access baz functions.
589 </loctext> </description>
590 </value>
591 <value name='qux'>
592 <description> <loctext xml:lang='C'>
593 Allow foo to access qux functions.
594 </loctext> </description>
595 </value>
596 </values>
597 <choices>
598 <include_values type='values'/>
599 </choices>
600 <prop_pattern>
601 </pg_pattern>
602 </template>
603
606 /usr/share/lib/xml/dtd/service_bundle.dtd.1
607
609 svcs(1), svccfg(1M), libscf(3LIB), service_bundle(4), smf(5)
610SunOS 5.11 10 Nov 2008 smf_template(5)