svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
smf_stencil(5)
smf_stencil(5) File Formats smf_stencil(5)
NAME
smf_stencil - defines the relationship between SMF properties and a
flat configuration file
DESCRIPTION
A stencil file defines a mapping between SMF properties and flat text
files. The Service Management Facility, described in smf(7), uses sten‐
cil files in conjunction with the svcio(1) utility, to generate text-
based configuration files from SMF properties by invoking svcio(1). It
must be invoked before the start() and refresh() methods of a property
configured service are run.
The language understood by svcio(1) is comprised of a small set of ex‐
pressions that can be combined to concisely describe the structure of a
configuration file and how to populate that file with data from the SMF
repository. The expressions comprising the language are listed below:
$%{property_fmri[:<transform><transform_expression>]}
Retrieve and emit the values associated with a property.
transform can be one of the following characters, which define how
to handle transform_expression:
- Emit transform_expression if the property is not defined.
+ Emit transform_expression if the property is defined.
? The transform_expression is of the form <true>[/<false>]. If
the boolean property is true, then emit <true>, otherwise
emit <false>.
, Emit transform_expression as a delimiter between values in
multi-valued properties.
^ The transform_expression is of the form <p>[/<s>] where <p>
is used as a prefix and <s> is used as a suffix when emitting
property values.
^* Same as ^, but nothing is emitted if the property is unde‐
fined or empty.
' The transform_expression takes the form <pattern>/<replace>,
where <pattern> is a shell pattern style glob (for details,
see the File Name Generation section of sh(1)). The first
substring to match <pattern> is replaced with <replace>.
'' Same as ', but every substring that matches <pattern> is re‐
placed with <replace>.
$%/regular_expression/ { <sub_elements> }
Process sub_elements for each property FMRI and property group FMRI
that matches regular_expression. As the property group and property
is specified as an FMRI they must be encoded if they contain re‐
served characters (see smf(7)) or if the property group is nested
within another property group.
$%<number>
Retrieve a marked sub-expression from a regular expression.
$%define name /regular_expression/ { <sub_elements> }
Name a regular expression such that it can be used else where in
the stencil.
$%[regex_name[:<transform><transform_expression]]
Recall a previously defined regular expression $ %define name /reg‐
ular_expression/ { <sub_elements> }. In this case, the set of
transform characters is limited to ^, ' and ".
$%define name arg 1 arg 2 ... argN { <sub_elements> }
Name a macro such that it can be used elsewhere in the stencil.
Note -
In the text above, [ and ] denote the macro delimiters rather
than optional parameters as they do in expression $%{prop‐
erty_fmri[:<transform><transform_expression>]} and
$%[regex_name[:<transform><transform_expression]].
$%<arg_name>
Retrieve the text associated with a macro argument.
$%[name foo bar ... baz]
Recall a previously defined macro (as in VI).
$%<method_token>
Retrieve the value of an environment variable represented by a
method token described in smf_method(7).
Literal Text
Arbitrary text can be freely interspersed throughout the stencil
without any denotative markers.
;comments
A line that starts with a ;, ignoring leading whitespace, is con‐
sidered a comment and not processed along with the rest of the
file.
Any of the special characters above can be escaped by preceding them
with a backslash (\) character. Also, the \n and \t sequences are ex‐
panded into endlines and tab characters respectively. Any non-special
character preceded by \ (backslash) will emit only the character fol‐
lowing the slash. Thus \g will be translated to g.
DETAILS
Expression 1
$%{property_fmri[:<transform><transform_string>]}
For example,
$%{general/enabled:?on/off}
$%{svc:/srv:inst/:properties/pg/prop}
This element will fetch the value (or values) of a property and emit a
string subject to the transform, the transform string, and the values
themselves. transform is a one- or two- character identifier that indi‐
cates how to modify a property value before emitting it, subject to
transform_string, as explained above.
Nesting is allowed. If you want to print the value of foo/b if foo/a is
defined, but 'blueberry' if it is not. This could be accomplished using
the following:
$%{foo/a:?$%{foo/b}/blueberry}
For the purposes of resolving FMRIs into values, a few shortcuts are
allowed. Since svcio command is always run against a specific instance,
properties from that instance can be shortened to pg or prop rather
than a fully qualified FMRI. To reference properties that are not part
of the instance, the full svc:/service:instance/:properties/pg/prop is
required.
Expression 2
$%/regular_expression/ { <sub_elements> }
For example,
$%/pg/(.*)/ {lorem ipsum}
This element defines a regular expression to match against the entire
set of property FMRIs on a system. For each property FMRI that matches,
the subelements are evaluated. When evaluating subelements, svcio(1)
iterates over matching properties in lexicographical order. svcio(1)
uses the POSIX extended regular expression set (see regex(7)), and sup‐
ports saving subexpressions via parentheses. Finally, as a convenience
svcio will surround the regular expression with ^ and $ characters. If
you want your expression to match the middle of strings, prepend and
append .*.
Since both properties associated with the operating instance as well as
properties from other services or instances, regular expressions are
only matched against a subset of FMRIs on the system. If a regular ex‐
pression includes the substring :properties, the expression is parsed
for the service and/or instance where those properties reside. Once
those properties are fetched, the regular expression is matched only
against that set. If the regular expression does not contain that sub‐
string, the only properties matched are those associated with the oper‐
ating instance.
Note -
The end of a regular expression is denoted by / { so it is not neces‐
sary to escape slash characters within the regular expression.
Expression 3
$%<number>
For example,
$%3
This element emits the value from a stored subexpression in a preceding
regular expression. Using this element outside the context of a regular
expression is an error. A valid use would be as follows:
$%/foo/(.*)/ {
$%1 = $%{foo/$%1}
}
In the preceding example, every property in property group foo would be
emitted as property_name = property_value.
Since arbitrary subelements are allowed within a regular expression
block, nested regular expressions have their subexpression indices ad‐
justed relative to the index of the last subexpression of the contain‐
ing expression. For example:
;([a-zA-Z_-]*) is $%1
$%/([a-zA-Z_-]*)/ {
[$%1]
;(.*) becomes $%2
$%/$%1/(.*)/ {
$%2 = $%{$%1/$%2}
}
}
In the preceding example, every property group for an instance would be
emitted in blocks as follows:
[property_group]
prop1 = <prop1_value>
prop2 = <prop2_value>
...
Expression 4
$%define name /regular_expression/ { <sub_elements> }
For example,
$%define getProp //(.*)/ {dolor sit amet}
This element follows the same basic rules as in the expression $%/regu‐
lar_expression/ { <sub_elements> }, but stores the element as a named
regular expression that can be invoked later in the stencil file. Named
regular expressions are not matched unless they are referenced as per
expression $%[regex_name:<transform><transform_string>], which immedi‐
ately follows. Additionally, This element cannot be a child to any
other.
Expression 5
$%[regex_name:<transform><transform_string>]
For example,
$%[getProp:^restarter]
This inserts a previously defined regular expression, along with all
its subelements into the stencil as though the definition were copy and
pasted. Since the insertion is performed literally, there are some spe‐
cial rules that govern how the insertion is done in order to allow such
an element to be meaningful at many levels of expression nesting. First
of all, all subexpression indices are internally adjusted so that they
do not collide with the outer regular expression context. Second, a
subset of the transformations from expression $%{property_fmri[:<trans‐
form><transform_string>]} are allowed. These transforms operate on rel‐
ative FMRIs within the inserted element. Absolute FMRIs are left un‐
touched. This allows a stencil author to do useful things like prepend
to the FMRI in order to express logical property nesting. Here's an ex‐
ample:
$%define PROPERTY /(.*)/ { $%1 = $%{$%1} }
$%/([a-zA-Z_-]*)/ {
[$%1]
$%[PROPERTY:^$%1/]
}
When the insertion is done, the expression will function as follows:
$%/([a-zA-Z_-]*)/ {
[$%1]
$%/$%1/(.*)/ {
$%2 = $%{$%1/$%2}
}
}
This is equivalent to the example for the expression $%<number>.
It ends up this way because the rebasing during substitution changes
the $%1 to $%2, since $%1 occurs in the outer expression. And as a re‐
sult of the prepend transform applied during substitution, the string
$%1/ is prepended to both the regular expression (since regular expres‐
sions match FMRIs) as well as to the element of the expression $%/regu‐
lar_expression/ { <sub_elements> }, allowing it resolve to a full
pg/property specifier. The subset of allowed transforms is ^, ', and
''. Using other transforms is an error.
Expression 6
$%define macroName arg1 arg2 ... argN { <sub_elements> }
For example,
$%define defaultHost { myMachine }
$%define getGeneral prop { $%{general/$%prop} }
Macros provide simple text substitution with respect to the arguments
defined for the macro. When called subsequent to definition, the text
of the sub-elements is emitted with the text of the arguments substi‐
tuted where appropriate. See the elements below for more details.
Expression 7
$%<argName>
For example,
$%prop
This element emits the corresponding value passed into the macro that
uses argName as an argument. For example:
$%define someMacro someArg someOtherArg {
$%someArg = $%{pg/$%someOtherArg}
}
Expression 8
$%[macroName arg1 arg2 ... argN]
For example,
$%[getGeneral enabled]
After a macro has been defined, the sub-elements it contains can be
substituted into other parts of the stencil by using the form above.
When invoking a macro, spaces are used to delimit arguments. In order
to use a space within the value of an argument, it is necessary to es‐
cape that space with a ''. For example, if we have the macro:
$%define theMacro variable value {
$%variable = $%value
}
We can then use this form to substitute that text else where in the
stencil. For example, we can call it as follows:
$%[theMacro ciphers elGamal\ 3DES\ AES\ Blowfish]
And the resulting text in the output file would be:
ciphers = elGamal 3DES AES Blowfish
Expression 9
$%<method_token>
For example,
$%s
Each of the single-character method tokens described in smf_method(7)
are available in stencils. In particular $%r, $%m, $%s, $%i, $%f, and
$%% are understood and expanded. Due to the high chance of collision
with macro variables (in the expression $%define name /regular_expres‐
sion/ { <sub_elements> }), macro variables have precedence over method
tokens when expansion occurs. This means that if the macro variable
$%someVar is encountered, it will be expanded to the value of $%someVar
rather than service-nameomeVar. If output such as service-nameomeVar is
desired, simply escape a character in the macro variable as in
$%s\omeVar.
Expression 10
Literal text
For example,
Lorem ipsum dolor sit amet, consectetur adipisic-
ing elit, sed do eiusmod tempor incididunt ut
labore et dolore magna aliqua.
Literal text can be freely interspersed within the stencil and is emit‐
ted without modification. The examples above make limited use of lit‐
eral text. Text appearing inside a regular expression is emitted for
each match, but is not emitted if there are no matches. Text appearing
outside all the preceding expression types is emitted in all cases.
Expression 11
Comments
For example,
;this is a comment
;so is this
\;this text will appear in the output file
so will this, even with the ';' character
To begin a comment, start the line with a ';' character (not including
whitespace). The comment continues until the end of the line. If having
comments in the resulting output file is desired, simply escape the ';'
with a '\' character.
Expression 12
$%[$%[macro]:<transform><transform_string>]
For example,
$%{$%[foo]:,\n}
Simple definitions may be provided through a service manifest by creat‐
ing a defines property group nested within the configfile property
group. These name/value pairs may then be referenced in a stencil using
the macro syntax. Such defines may also be embedded within a property
expression allowing the property group and property name to be provided
through a manifest rather than in the stencil.
In the example expression foo might be provided by the manifest:
<property_group type="configfile" name="my.conf">
<propval type="astring" name="mode" value="0644" />
<propval type="astring" name="stencil" value="my.stencil" />
<property_group type="application" name="defines">
<propval type="astring" name="foo" value="bar/baz" />
</property_group>
</property_group>
When the stencil is processed the foo macro will be resolved as
bar/baz, and bar/baz will be used as the property to lookup and use in
the property expression.
EXAMPLES
Example 1 Creating a configuration file that lists some details of the
service
The following example creates a configuration file that lists some de‐
tails of the service
;The following example creates a 'configuration file'
;that lists some details of the service
$%define author {Alice}
$%define reviewer {Bob}
This file was written by $%[author] and verified by $%[reviewer].
Preferences are:
$%{preferences/validated:+validated!}
The following is a .ini style listing of all the properties of service
$%s and instance $%i:
;display a property in the form
;' prop_name = prop_value'
$%define display_property prop
{\t$%prop = $%{/$%prop}\n}
;invokes display_property macro for each
;property matched
$%define property //(.*)/ {$%[display_property $%1]}
;matches all property groups (lack of '/' prevents
;matching properties) and emits the property group
;name in brackets, with each property listed underneath.
;The expression '^$%1' means prepend all relative FMRIS
;in the regular expression named 'property' with the
;property group that satisfies this regular expression
$%/([a-zA-Z0-9_-]*)/ {
[$%1]
$%[property:^$%1]
}
Suppose we have a service Foo with just the default instance and the
following properties:
pg1/prop1 = val1
pg1/prop2 = va2
pg2/prop1 = val3 val4
pg2/prop2 = val5
preferences/validated = yes
Using svcio(1) to the example stencil with service Foo would result in
the following text:
This file was written by Alice and verified by Bob
Preferences are validated!
The following is a .ini style listing of all the properties of service
Foo and instance default:
[pg1]
prop1 = val1
prop2 = val2
[pg2]
prop1 = val3 val4
prop2 = val5
[properties]
validated = yes
It is also possible to rewrite the example stencil more tersely, as
shown below:
$%define author {Alice}
$%define reviewer {Bob}
This file was written by $%[author] and verified by $%[reviewer].
Preferences are:
$%{preferences/validated:+validated!}
The following is a .ini style listing of all the properties of service
$%s and instance $%i:
$%/([a-zA-Z0-9_-]*)/ {
[$%1]
$%/$%1/(.*)/ {\t$%2 = $%{$%1/$%1}\n}
}
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Availabilitysystem/core-os _ StabilityCommitted
SEE ALSO
sh(1), svcio(1), svcprop(1), svcs(1), libscf(3LIB), regex(7), smf(7),
svc.startd(8), svcadm(8), svccfg(8)
HISTORY
Support for SMF Stencils was added to Solaris in the Oracle Solaris
11.2.0 release.
Oracle Solaris 11.4 14 Dec 2023 smf_stencil(5)