New in SMF Documentation for Oracle Solaris 11.2

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)

Comments:

Post a Comment:
  • HTML Syntax: NOT allowed
About

The Observatory is a blog for users of Oracle Solaris. Tune in here for tips, tricks and more as we explore the Solaris operating system from Oracle.

Connect with Oracle Solaris:


Search

Archives
« February 2015
SunMonTueWedThuFriSat
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
       
       
Today