Using svcbundle to Create SMF Manifests and Profiles in Oracle Solaris 11

by Glynn Foster

This articles covers a new utility introduced in Oracle Solaris 11.1, svcbundle, and shows how developers and administrators can use it to integrate their applications with SMF more quickly.


Published October 2012

With the introduction of svcbundle in Oracle Solaris 11.1, the creation of manifests and profiles is even easier, allowing you to take advantage of the benefits of automatic application restart without requiring you to have full knowledge of the XML file format that is used when integrating with the Service Management Facility (SMF).

"Better a witty fool than a foolish wit." Even Will Shakespeare thinks you should take a crack at writing up your favorite sysadmin or developer how-to's. Become an OTN member and get paid for publishing your article on OTN.

SMF, first introduced in Oracle Solaris 10, is a feature of the operating system for managing system and application services, and it replaces the legacy init scripting start-up mechanism common to prior releases of Oracle Solaris and other UNIX operating systems. SMF improves the availability of a system by ensuring that essential system and application services run continuously even in the event of any hardware or software failures. SMF is one of the components of the wider Oracle Solaris Predictive Self Healing capability.

This articles covers a new utility that was introduced in Oracle Solaris 11.1 called svcbundle, and it shows how you can use this utility to integrate your applications with SMF more quickly. If you are unfamiliar with SMF, it is recommended you read " Introducing the Basics of Service Management Facility (SMF) on Oracle Solaris 11" and " Advanced Administration with the Service Management Facility (SMF) on Oracle Solaris 11" as prerequisite articles.

An Overview of Service Bundles

At the core of SMF is the concept of a service bundle, an XML-based file that is used to describe everything about a service or an instance of a service—including its configuration—prior to it being imported into the SMF configuration repository and used on a running system. Service bundles are used to deliver services into Oracle Solaris, but they also act as a useful way for you to deliver custom configuration across a variety of systems.

There are two types of service bundles used in SMF: manifests and profiles.

  • Manifests are used to describe services and instances of a service, along with any properties associated with those services. Manifests are usually located in /lib/svc/manifest and they are automatically imported into the SMF configuration repository during system reboot, or they can be manually imported by restarting the svc:/system/manifest-import:default service.
  • Profiles are similar to manifests, but they are typically used to provide customization of a service or service instance from what was provided in the manifest. Customizations include whether an instance of a service should be enabled or disabled, or they include any modifications to service configuration properties. Profiles are usually located in /etc/svc/profile and applied during system reboot, or they can be applied again manually by restarting the svc:/system/manifest-import:default service.

Integrating an Application into SMF Using svcbundle

"How to Migrate Control of System Services from Scripts to the Service Management Facility" covers how SMF manifests can be written from scratch (or copied from an existing system manifest and modified) according to the XML DTD found in /usr/share/lib/xml/dtd/service_bundle.dtd.1. In Oracle Solaris 11.1, however, the new easy-to-use svcbundle command-line utility is available to help you create an SMF manifest or system profile without having knowledge of the XML file format.

svcbundle allows you to create and, optionally, install a manifest or system profile for common scenarios. As a result, svcbundle makes a number of simple assumptions to deal with common scenarios:

  • Generated manifests are intended to be used with the master restarter, svc.startd.
  • An automatic dependency on the svc:/milestone/multi-user service ensures that the service is not started too early in the system boot process.
  • The timeout for the start and restart exec methods defaults to 60 seconds.

You provide a series of name-value pairings to svcbundle that are used to define different elements of a manifest or profile, for example, the service instance name; whether it should be enabled or disabled; different property values; start, stop, and refresh methods; and what type of service it should be. The utility can also help to facilitate the conversion of a legacy RC (run control) script to SMF.

As with many command-line utilities, it's easier to see by example, so we will show two uses of svcbundle:

  • How to create a manifest for starting Nagios, the open source system monitoring application
  • How to create a system profile to provide customization across Oracle Solaris systems installed in a data center environment

Using svcbundle to Create an SMF Manifest

In this example, we will use svcbundle to create an SMF manifest to automatically start Nagios upon reboot. Nagios is not currently packaged in the Oracle Solaris 11 package repository, so you must first download it from http://www.nagios.org and then preform a a simple installation.

In this example, we have installed Nagios into the /usr/local/nagios prefix and modified the Apache Web server configuration file to be aware of the Nagios installation. We can start the Nagios daemon directly, as follows, using the -d option and providing it the location of the configuration file:

# /usr/local/nagios/bin/nagios -d /usr/local/nagios/etc/nagios.cfg

We can now check that it's successfully running by navigating to http://localhost/nagios in a browser, as shown in Figure 1:

Figure 1

Figure 1. Nagios

Once we have a working Nagios installation, the next step is to integrate this application into SMF so that it will start up during a system boot or restart if any software failure occurs. To do this, we will use svcbundle to generate an SMF manifest for it, as follows:

# svcbundle -o nagios.xml -s service-name=application/nagios -s model=daemon \
  -s start-method="/usr/local/nagios/bin/nagios -d /usr/local/nagios/etc/nagios.cfg"

In the example shown in Listing 1, we define three name-value pairs. We define the -s service-name option as application/nagios, which will result in the service being called svc:/application/nagios:default. We define the -s model option as daemon so that SMF will track any processes for this service. We also define the -s start-method option to be the same value that we used a little earlier to start the Nagios daemon. We will output this manifest to the file nagios.xml, as defined by the -o option. SMF will automatically validate the resulting manifest.

# cat nagios.xml
<?xml version="1.0" ?>
<!DOCTYPE service_bundle
  SYSTEM '/usr/share/lib/xml/dtd/service_bundle.dtd.1'>
<!--
    Manifest created by svcbundle (2012-Sep-11 00:19:49+1200)
-->
<service_bundle type="manifest" name="application/nagios">
    <service version="1" type="service" name="application/nagios">
        <!--
            The following dependency keeps us from starting until the
            multi-user milestone is reached.
        -->
        <dependency restart_on="none" type="service"
            name="multi_user_dependency" grouping="require_all">
            <service_fmri value="svc:/milestone/multi-user"/>
        </dependency>
        <exec_method timeout_seconds="60" type="method" name="start"
            exec="/usr/local/nagios/bin/nagios -d /usr/local/nagios/etc/nagios.cfg"
        />
        <!--
            The exec attribute below can be charged to a command that SMF
            should execute to stop the service.  See smf_method(5) for more
            details.
        -->
        <exec_method timeout_seconds="60" type="method" name="stop"
            exec=":kill"/>
        <!--
            The exec attribute below can be changed to a command that SMF
            should execute when the service is refreshed.  Services are
            typically refreshed when their properties are changed in the
            SMF repository.  See smf_method(5) for more details.  It is
            common to retain the value of :true which means that SMF will
            take no action when the service is refreshed.  Alternatively,
            you may wish to provide a method to reread the SMF repository
            and act on any configuration changes.
        -->
        <exec_method timeout_seconds="60" type="method" name="refresh"
            exec=":true"/>
        ....
    </service>
</service_bundle>

Listing 1. Example Manifest

The next step is to take this manifest and install it into /lib/svc/manifest/site by restarting the svc:/system/manifest-import:default service. We will also restart the svc:/network/http:apache22 service, since we have modified the Apache configuration.

# svcadm restart apache22
# cp nagios.xml /lib/svc/manifest/site
# svcadm restart manifest-import
# svcs nagios
STATE          STIME    FMRI
online         2:13:01  svc:/application/nagios:default
# ps -ef | grep nagios
  nagios 25743     1   0 00:50:43 ?  0:06 /usr/local/nagios/bin/nagios -d /usr/local/nagios/etc/nagios.cfg

We could have also used the -i option (instead of the -o option) to install the generated SMF manifest directly into the system and automatically restart the svc:/system/manifest-import:default service.

This is a simple example of how we can quickly generate a simple SMF manifest using svcbundle. If you want to customize further, you can modify this template manifest once it has been generated.

Using svcbundle to Create an SMF System Profile

In this example, we will use svcbundle to generate an SMF system profile to customize the name server address configuration in the svc:/network/dns/client service. For this, we will need to use the service-property and bundle-type name-value pairs, as follows:

# svcbundle -o nameserver-config.xml -s service-name=network/dns/client \
  -s bundle-type=profile -s service-property="config:nameserver:net_address:192.168.0.1"

The default bundle type for svcbundle is manifest, so we define bundle-type to be profile. Service and service instance configuration properties are defined using a quadruple separated by colons: property group, property name, property type, and value. In Listing 2, we define the service-property name value to be config:nameserver:net_address:192.168.0.1.

# cat nameserver-config.xml
<?xml version="1.0" ?>
<!DOCTYPE service_bundle
  SYSTEM '/usr/share/lib/xml/dtd/service_bundle.dtd.1'>
<!--
    Manifest created by svcbundle (2012-Sep-11 02:33:16+1200)
-->
<service_bundle type="profile" name="network/dns/client">
    <service version="1" type="service" name="network/dns/client">
        <property_group type="application" name="config">
            <propval type="net_address" name="nameserver"
                value="192.168.0.1"/>
        </property_group>
    </service>
</service_bundle>

Listing 2. Example Profile

As before with the SMF manifest, we now need to take this SMF system configuration profile and install it onto the system. We achieve this by copying it to /etc/svc/profile/site/ and restarting the svc:/system/manifest-import:default service:

# cp nameserver-config.xml /etc/svc/profile/site
# svcadm restart manifest-import
# svcprop -p config/nameserver dns/client
192.168.0.1

As before, we could have used the -i option to directly install the profile onto the system.

This is a simple example just setting one property of a service. At this time, svcbundle supports creating a system configuration profile for only a single service or service instance, but more-complicated profiles can be constructed once these initial profiles have been created.

Summary

If you are managing system services and applications on Oracle Solaris 11, SMF provides a number of benefits including automatic service restart, consolidated service configuration, and integration into the fault management framework. A new tool, svcbundle, can help you to create SMF manifests and integrate critical services and applications into the SMF framework. It can also be used to create system profiles to provide customization across Oracle Solaris systems installed in the data center environment.

See Also

About the Author

Glynn Foster is a Principal Product Manager for Oracle Solaris and works on technology areas that include the Image Packaging System (IPS) and Service Management Facility (SMF). Glynn joined Oracle in 2010 as part of the Sun Microsystems acquisition.

Revision 1.1, 03/10/2014

facebook banner twitter banner