Delivering an SMF Service

To deliver a new SMF service, create a package that delivers the SMF manifest file and method script.

This section first discusses the general case of delivering any new SMF service, and then discusses the specific case of delivering a service that runs once. Finally, this section presents some tips for self-assembly of these service packages.

Delivering a New SMF Service

A package that delivers a new SMF service usually needs a system change.

In SVR4 packaging, post-install scripting ran an SMF command to restart the svc:/system/manifest-import:default service.

In IPS, the action that delivers the manifest file into lib/svc/manifest or var/svc/manifest should be tagged with the following actuator:

restart_fmri=svc:/system/manifest-import:default

This actuator ensures that when the manifest is added, updated, or removed, the manifest-import service is restarted, causing the service delivered by that SMF manifest to be added, updated, or removed.

If the package is added to a live system, this action is performed once all packages have been added to the system during that packaging operation. If the package is added to an alternate boot environment, this action is performed during the first boot of that boot environment.

Delivering a Service that Runs Once

A package that needs to perform a one-time configuration of the new software environment should deliver an SMF service to perform that configuration.

The package that delivers the application should include the following actions:

file path=opt/myapplication/bin/run-once.sh owner=root group=sys mode=0755
file path=lib/svc/manifest/application/myapplication-run-once.xml owner=root group=sys \
mode=0644 restart_fmri=svc:/system/manifest-import:default

The SMF method script for the service can contain anything that is needed to further configure the application or modify the system so that the application runs efficiently. In this example, the method script writes a simple log message:

#!/usr/bin/sh
. /lib/svc/share/smf_include.sh
assembled=$(/usr/bin/svcprop -p config/assembled $SMF_FMRI)
if [ "$assembled" == "true" ] ; then
    exit $SMF_EXIT_OK
fi
svccfg -s $SMF_FMRI setprop config/assembled = true
svccfg -s $SMF_FMRI refresh
echo "This is output from our run-once method script"

Generally, the SMF service should only perform work if the application has not already been configured. This example method script checks config/assembled. An alternative approach is to package the service separately from the application, and then use the method script to remove the package that contains the service.

When testing a method script, run pkg verify before and after installing the package that runs the actuator. Compare the output of each run to ensure that the script does not attempt to modify any files that are not marked as editable.

The following shows the SMF service manifest for this example:

<?xml version="1.0"?>
<!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">
<service_bundle type='manifest' name='MyApplication:run-once'>
<service
    name='application/myapplication/run-once'
    type='service'
    version='1'>
    <single_instance />
    <dependency
        name='fs-local'
        grouping='require_all'
        restart_on='none'
        type='service'>
            <service_fmri value='svc:/system/filesystem/local:default' />
    </dependency>
    <dependent
        name='myapplication_self-assembly-complete'
        grouping='optional_all'
        restart_on='none'>
        <service_fmri value='svc:/milestone/self-assembly-complete' />
    </dependent>
    <instance enabled='true' name='default'>
        <exec_method
            type='method'
            name='start'
            exec='/opt/myapplication/bin/run-once.sh'
            timeout_seconds='0'/>
        <exec_method
            type='method'
            name='stop'
            exec=':true'
            timeout_seconds='0'/>
        <property_group name='startd' type='framework'>
            <propval name='duration' type='astring' value='transient' />
        </property_group>
        <property_group name='config' type='application'>
            <propval name='assembled' type='boolean' value='false' />
        </property_group>
    </instance>
</service>
</service_bundle>

Note that the SMF service has a startd/duration property set to transient so that svc.startd(1M) does not track processes for this service. Also note that the service adds itself as a dependency to the self-assembly-complete system milestone.

Supporting Package Self-Assembly in SMF Methods

This section provides some additional tips to support package self-assembly when writing SMF methods.

Testing Whether a Configuration File Recompile Is Necessary

If compiling a configuration file from packaged configuration file fragments is expensive to perform each time the method script runs, consider using the following test in the method script.

Run ls -t on a directory of packaged configuration file fragments, and then use head -1 to select the most recently changed version. Compare the time stamp of this file with the time stamp of the unpackaged configuration file that is compiled from those fragments to determine whether the service needs to recompile the configuration file.

Limiting the Time To Wait for Self-Assembly To Complete

The example SMF service manifest shown above defines timeout_seconds='0' for the start method. This means that SMF will wait indefinitely for self-assembly to complete.

To assist in debugging, you might want to impose a finite timeout on self-assembly processes, enabling SMF to drop the service to maintenance if something goes wrong.