2573N/A.. The contents of this file are subject to the terms of the
2573N/A Common Development and Distribution License (the "License").
2573N/A You may not use this file except in compliance with the License.
2573N/A See the License for the specific language governing permissions
2573N/A and limitations under the License.
2573N/A.. When distributing Covered Code, include this CDDL HEADER in each
2573N/A If applicable, add the following below this CDDL HEADER, with the
2573N/A fields enclosed by brackets "[]" replaced with your own identifying
2573N/A information: Portions Copyright [yyyy] [name of copyright owner]
2573N/A.. Copyright (c) 2011, Oracle
and/or its affiliates. All rights reserved.
2585N/ACausing System Change With SMF
2585N/A..............................
2585N/AThis chapter explains how to use the Service Management Facility (SMF) to
2585N/Aautomatically handle any necessary system changes that should occur as a result
2585N/AThe package developer must determine which actions, when initially installed,
2585N/Aupdated or removed should cause a change to the system. For each of those
2585N/Aactions, the package developer needs to determine which existing service
2585N/Aprovides the desired system change, or write a new service which provides the
2585N/Aneeded functionality and ensure that service is delivered to the system.
2573N/AWhen the set of actions has been determined, those actions must be tagged in
2585N/Athe package manifest with the correct *actuator* in order to cause that system
2585N/AAs discussed in *Chapter 1*, some system changes are needed to employ the
2585N/A*software self-assembly* concept used by Oracle Solaris and IPS, but system
2585N/Achanges are not limited to this role.
2573N/AWe'll discuss the available actuators in the next section and then provide some
2573N/AThe following tags can be added to any action in a manifest:
2585N/AThis actuator takes the value ``true`` or ``false``. This actuator declares
2585N/Athat installation, removal or update of the tagged action requires a
2585N/Areboot when IPS is operating on a live image.
2573N/AThe following actuators are related to SMF services, and are the ones we will
2585N/ASMF actuators take a single SMF FMRI as a value, possibly including globbing
2573N/Acharacters to match multiple FMRIs. If the same FMRI is tagged by multiple
2573N/Aactions, possibly across multiple packages being operated on, IPS will only
2585N/AThe following list of SMF actuators describes the effect on the service FMRI
2585N/Athat is the value of each named actuator:
2585N/A The given service should be disabled prior to the package operation
2585N/A The given service should be refreshed after the package operation has
2585N/A The given service should be restarted after the package operation has
2585N/A The given service should be temporarily suspended prior to the package
2573N/A operation and enabled once it has completed
2585N/AA package that delivers a new SMF service usually needs a system change. The
2585N/Apackage delivers the SMF manifest file and method script, and the packaged
2585N/Aapplication requires that the SMF service it delivers must be available
2585N/AIn older Oracle Solaris releases, SVR4 post-install scripting would run an SMF
2573N/AThe actuator ensures that when the manifest is added, updated, or removed, the
2585N/A``manifest-import`` service is restarted, causing the service delivered by that
2573N/ASMF manifest to be added, updated, or removed.
2573N/AIf the package is added to a live-system, this action is performed once all
2573N/Apackages have been added to the system during that packaging operation. If the
2573N/Apackage is added to an alternate boot environment, this action is performed
2573N/Aduring the first boot of that boot environment.
2585N/AAnother common example is a system change that performs one-time configuration
2585N/Aof the new software environment.
2585N/AIn the package delivering our application, we would include the following
2585N/AThe SMF method script for the service could contain anything that is needed to
2585N/Afurther configure our application, or modify the system so that our application
2585N/Aruns efficiently. In this example, we'll just have it write a simple log
2585N/AGenerally, we also want to ensure that the SMF service only performs work if the
2585N/Aapplication has not already been configured.
2585N/AAnother approach would be to package the service separate from the application
2585N/Aitself, then have the method script remove the package that contains the
2585N/A if [ "$assembled" == "true" ] ; then
2585N/A svccfg -s $SMF_FMRI refresh
2585N/A echo "This is output from our run-once method script"
2585N/AWhen testing a method script, it is advisable to run ``pkg verify``
2585N/Abefore and after installing the package that runs the actuator.
2585N/ACompare the output of each run to ensure that the script doesn't attempt to
2585N/Amodify any files that are not marked as editable.
2585N/AOur SMF service manifest is::
2585N/A <service_bundle type='manifest' name='MyApplication:run-once'>
2585N/A name='myapplication_self-assembly-complete'
2585N/A <instance enabled='true' name='default'>
2585N/A <property_group name='startd' type='framework'>
2585N/A <propval name='duration' type='astring' value='transient' />
2585N/A <property_group name='config' type='application'>
2585N/A <propval name='assembled' type='boolean' value='false' />
2585N/AAlso note that it adds itself as a dependency to the ``self-assembly-complete``
2585N/AHere are some additional hints when writing SMF methods to support
2585N/AIn an SMF method script, it can be efficient to use the output of ``ls -t`` on a
2585N/Adirectory of packaged configuration file fragments, using ``head -1`` to select
2585N/Athe most recently changed version. The timestamp of this file can be compared
2585N/Awith the timestamp of the unpackaged configuration file which is compiled from
2585N/Athose fragments. This comparison can be used when deciding whether the service
2585N/Aneeds to recompile the configuration file.
2585N/AThis can be useful if the process of compiling a configuration file from those
2585N/Afragments is expensive to perform each time the method script runs.
2585N/AIn the example SMF service used in this chapter, we had a ``timeout_seconds``
2585N/Avalue of ``0`` for the start method. This means that SMF will wait indefinitely
2585N/Afor self-assembly to complete.
2585N/ADepending on circumstances, developers might want to impose a finite timeout on
2585N/Atheir self-assembly processes, enabling SMF to drop the service to
2585N/A``maintenance`` if something goes wrong. This can assist the developer when