A stencil file defines a mapping between SMF properties and flat text files. The Service Management Facility, described in smf (5) , uses stencil 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 expressions 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:
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 undefined 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 replaced with <replace>.
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 reserved characters (see smf (5) ).
Retrieve a marked sub-expression from a regular expression.
Name a regular expression such that it can be used else where in the stencil.
Recall a previously defined regular expression $ %define name /regular_expression/ { <sub_elements> }. In this case, the set of transform characters is limited to ^, ' and ".
Name a macro such that it can be used elsewhere in the stencil.
Retrieve the text associated with a macro argument.
Recall a previously defined macro (as in VI).
Retrieve the value of an environment variable represented by a method token described in smf_method (5) .
Arbitrary text can be freely interspered throught the stencil without any denotative markers.
A line that starts with a ;, ignoring leading whitespace, is considered 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 expanded into endlines and tab characters respectively. Any non-special character preceded by \ (backslash) will emit only the character following the slash. Thus \g will be translated to g.
$%{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 indicates 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.
$%/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 (5) ), and supports 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 expression includes the substring :properties, the expression is parsed for the service and/or instance where those properties reside. Once those properties are fetched, the regu- lar expression is matched only against that set. If the regular expression does not contain that substring, the only properties matched are those associated with the operating instance.
$%<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 adjusted relative to the index of the last subexpression of the containing 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>
...
$%define name /regular_expression/ { <sub_elements> }
For example,
$%define getProp //(.*)/ {dolor sit amet}
This element follows the same basic rules as in the expression $%/regular_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 immediately follows. Additionally, This element cannot be a child to any other.
$%[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 special 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 interally adjusted so that they do not collide with the outer regular expression context. Second, a subset of the transformations from expression $%{property_fmri[:<transform><transform_string>]} are allowed. These transforms operate on relative FMRIs within the inserted element. Absolute FMRIs are left untouched. This allows a stencil author to do useful things like prepend to the FMRI in order to express logical property nesting. Here's an example:
$%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 result of the prepend transform applied during substitution, the string $%1/ is prepended to both the regular expression (since regular expressions match FMRIs) as well as to the element of the expression $%/regular_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.
$%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 substituted where appropriate. See the elements below for more details.
$%<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}
}
$%[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 necssary to escape 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
$%<method_token>
For example,
$%s
Each of the single-character method tokens described in smf_method (5) 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 experssion $%define name /regular_expression/ { <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 expaned 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.
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 emitted without modification. The examples above make limited use of literal 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.
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
The following example creates a configuration file that lists some details 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 exmaple 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}
}
See attributes (5) for descriptions of the following attributes:
|
svcio (1) , sh (1) , regex (5) , svcs (1) , svcprop (1) , svcadm (1M) , svccfg (1M) , svc.startd (1M) , libscf (3LIB) , smf (5)