The Service Management Facility guide is all new for the Oracle Solaris 11.2 release, with much more information including an example of creating a pair of services that start and stop an Oracle Database instance and an examination of the Puppet stencil service.
For more information about stencil services, see Solaris SMF Weblog, and see the svcio.1 and smf_stencil.4 man pages below.
Managing System Services in Oracle Solaris 11.2
Chapter 1, "Introduction to the Service Management Facility"
Chapter 2, "Getting Information About Services"
- Service states and contract processes
- Service dependencies and dependents
- New -L option to show service log files
- Property values in layers, snapshots, and customizations
Chapter 3, "Administering Services"
- Starting, restarting, stopping
- Re-reading configuration
- Configuring notification
Chapter 4, "Configuring Services"
- Setting and adding property values
- Adding service instances
- Using profiles to configure multiple systems
Chapter 5, "Using SMF to Control Your Application"
- Creating a service to start or stop an Oracle Database instance
- Using a stencil to create a configuration file
Appendix A, "SMF Best Practices and Troubleshooting"
- Repairing an instance that is in maintenance
- Diagnosing and repairing repository problems
- How to investigate problems starting services at system boot
User Commands svcio(1)
NAME
svcio - create text files based on service configuration
properties
SYNOPSIS
/lib/svc/bin/svcio [-alux] [-f FMRI-instance] [-g group]
[-i file] [-m mode] [-o file] [-O owner]
[-R dir [-L opts [-p]]] [-S dir]
DESCRIPTION
The svcio utility reads a template known as a stencil and
emits text based on that file in conjunction with the pro-
perties from a service instance. In the typical case, svcio
is used to generate application-specific configuration files
for services that are managed by, but are not able to read
their configurations from, SMF.
If the stencil itself contains any errors, svcio will pro-
vide a snippet of text along with a line number and the
cause of the error. Unless the error would prevent further
progress, each error is printed in the order it occurs in
the file.
Error messages are printed to the standard error stream.
OPTIONS
The following options are supported:
-a
Process all files configured for an instance.
Specifically, svcio will look at all property groups
with the type "configfile" and determine which stencil
to use and where to write the resulting file by examing
the values of the properties "path" and "stencil" within
that property group. For example, if property group
"conf1" is of the appropriate type then svcio will use
the value of "conf1/stencil" as the path of the stencil
file and "conf1/path" as the path of the file to which
to write the output. Additionally, the optional proper-
ties "owner" and "group" can be used to set the owner
and group of the output file respectively. If the pro-
perty group name or property name contains a reserved
character (see smf(5)) then it must be encoded.
-f FMRI-instance
The FMRI of a service instance to run the stencil
against.
-g group
The group to associate the output files with
-i file
The path to the stencil file (default is stdin). This
option cannot be used with -a.
-l
Rather than outputting a text file, simply list all pro-
perties that would be referenced were a file to be out-
put.
-L opts
Specify options to be passed to mount(2) when loopback
mounting output files. If this option is not specified,
output files will not be loopback mounted. The -R
switch is required with this option. A regular file
will be written to the specified output path, rooted at
prefix. This file will be loopback mounted to the speci-
fied output path, rooted at / or the value of the -R-fR
option.
-m mode
Set the mode for any output file (default is 644).
-o file
The path to the output file (default is stdout). This
option cannot be used with -a.
-O owner
Set the owner of the output files
-R prefix
Set the root prefix for all output files.
-p
Create nonexistent intermediate directories in the out-
put file path rooted at the value of the -R option.
Note: This option will not create directories that are
missing in the path to the mount point.
-S dir
Look for stencils in this directory rather than the
default.
-u
Unlink output files and undo loopback mounting. No out-
put files will be created.
-x
Terminate svcio on the first error rather than continu-
ing to the next stencil.
OPERANDS
The following operands are supported:
FMRI
A fault management resource identifier (FMRI) that
specifies one or more instances (see smf(5)). FMRIs can
be abbreviated by specifying the instance name, or the
trailing portion of the service name. For example, given
the FMRI:
svc:/network/smtp:sendmail
The following are valid abbreviations:
sendmail
:sendmail
smtp
smtp:sendmail
network/smtp
The following are invalid abbreviations:
mail
network
network/smt
If the FMRI specifies a service, then the command
applies to all instances of that service, except when
used with the -D option.
Abbreviated forms of FMRIs are unstable, and should not
be used in scripts or other permanent tools.
FMRI-instance
An FMRI that specifies an instance.
EXAMPLES
Example 1 Processing All Configuration Files for an Instance
This example processes all configured configuration files
for an instance:
example% svcio -a -f svc:/service:instance
Example 2 Removing All Configuration Files for an Instance
This example unlinks and unmounts all configured configura-
tion files for an instance:
example% svcio -au -f svc:/service:instance
Example 3 Using an Unconfigured Stencil for an Instance
This example produces an output file based on a stencil
that has not been configured:
example% svcio -o /etc/svc.conf -i ~/svc.stencil \
-f svc:/service1:instance
EXIT STATUS
The following exit values are returned:
0
Successful command invocation.
1
A fatal error occurred as a result of a failed system
call.
2
Invalid command line options were specified.
3
A fatal error occurred as a result of an unexpected SMF
error.
4
An error occurred parsing a stencil.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | system/core-os |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
SEE ALSO
smf_stencil(4), svcs(1), svcprop(1), svcadm(1M), svccfg(1M),
svc.startd(1M), stat(2), libscf(3LIB), smf(5)
File Formats smf_stencil(4)
NAME
smf_stencil - defines the relationship between SMF proper-
ties 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(5), uses stencil files in conjunction with the
svcio(1) utility to generate text-based configuration files
from SMF properties by invoking svcio(1) 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:
I. $%{property_fmri[:<transform><transform_expression>]}
Retrieve and emit the value(s) 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
? <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
^ <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
' <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>
II. $%/regular_expression/ { <sub_elements> }
Process <sub_elements> for each property FMRI and property
group FMRI that matches regular_expression. As the pro-
perty group and property is specified as an FMRI they must
be encoded if they contain reserved characters (see
smf(5)).
III. $%<number>
Retrieve a marked subexpression from a regular expression.
Retrieve a marked subexpression from a regular expression.
IV. $%define name /regular_expression/ { <sub_elements> }
Name a regular expression such that it can be used else-
where in the stencil.
V. $%[regex_name[:<transform><transform_expression]]
Recall a previously defined regular expression (as in IV).
In this case, the set of transform characters is limited
to ^, ', and ''.
VI. $%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 del-
imiters rather than optional parameters as they do in I
and V.
VII. $%<arg_name>
Retrieve the text associated with a macro argument.
VIII. $%[name foo bar ... baz]
Recall a previously defined macro (as in VI).
IX. $%<method_token>
Retrieve the value of an environment variable represented
by a method token describe in smf_method(5).
X. Literal Text
Arbitrary text can be freely interspersed throughout the
stencil without any denotative markers.
XI. ;comments
A line that starts with a ';', ignoring leading whi-
tespace, 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 blackslash (\) character. Addition-
ally, the '\n' and '\t' sequences are expanded into endlines
and tab characters respectively. Any non-special character
preceded by '\' will emit only the character following the
slash. Thus '\g' will be translated to 'g'.
DETAILS
I. $%{property_fmri[:<transform><transform_string>]}
Example: $%{general/enabled:?on/off}
$%{svc:/srv:inst/:properties/pg/prop}
This element will fetch the value (or values) of a pro-
perty 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.
Note that nesting is allowed. Imagine we want to print
the value of foo/b if foo/a is defined, but 'blueberry' if
it is not. This could be accomplished via the following:
it is not. This could be accomplished via the following:
$%{foo/a:?$%{foo/b}/blueberry}
For the purposes of resolving FMRIs into values, a few
shortcuts are allowed. Since svcio is always run against
a specific instance, properties from that instance can be
shortened to "pg/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.
II. $%/regular_expression/ { sub_elements> }
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 match-
ing 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. Should 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 proper-
ties 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.
Note that the end of a regular expression is denoted by '/
{' so it is not necessary to escape slash characters
within the regular expression.
III. $%<number>
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]
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>
...
IV. $%define name /regular_expression/ { <sub_elements> }
Example: $%define getProp //(.*)/ {dolor sit amet}
This element follows the same basic rules as element II,
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 element V, which immediately follows. Additionally,
This element cannot be a child to any other.
V. $%[regex_name:<transform><transform_string>]
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 element I 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 in element III.
It ends up this way because the rebasing during substitu-
This is equivalent to the example in element III.
It ends up this way because the rebasing during substitu-
tion 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 type
II, allowing it resolve to a full pg/property specifier.
The subset of allowed transforms is ^,',''. Using other
transforms is an error.
VI. $%define macroName arg1 arg2 ... argN { <sub_elements> }
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 subse-
quent to definition, the text of the sub-elements is emit-
ted with the text of the arguments substituted where
appropriate. See the elements below for more details.
VII. $%<argName>
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}
}
VIII. $%[macroName arg1 arg2 ... argN]
Example: $%[getGeneral enabled]
After a macro has been defined, the sub-elements in con-
tains 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 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 fol-
lows:
$%[theMacro ciphers elGamal\ 3DES\ AES\ Blowfish]
And the resulting text in the output file would be:
ciphers = elGamal 3DES AES Blowfish
IX. $%<method_token>
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 (element VII), macro variables have precedence
over method tokens when expansion occurs. This means that
variables (element VII), 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.
X. Literal text
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.
XI. Comments
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.
EXAMPLE
;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 proper-
ties 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]
}
RESULT
}
RESULT
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 proper-
ties 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(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | system/core-os |
|_____________________________|_____________________________|
| Stability | Committed |
|_____________________________|_____________________________|
SEE ALSO
svcio(1), sh(1), regex(5), svcs(1), svcprop(1), svcadm(1M),
svccfg(1M), svc.startd(1M), libscf(3LIB), smf(5)