Developing System Services in Oracle^® Solaris 11.4

Creating an SMF Service Using the Service Bundle Generator Tool

You can use the svcbundle service bundle generator tool to create a simple service or to start a more complex service. For more information, see the svcbundle(8) man page. You can use the service bundle DTD and other service manifests to complete a more complex service.

How to Create an SMF Service Using svcbundle

1. Determine the service model.

   By default, svcbundle creates a transient service. Determine whether the start method script for this service starts any long-running daemon and therefore this service is a contract service. See Service Models in Managing System Services in Oracle Solaris 11.4 and the model and startd/duration properties in the svcbundle(8) man page for information about service models.

2. Copy the script to the standard location.

   The service in this example uses a custom script named ex-svc as the start method. Copy this script to /lib/svc/method/ex-svc.

3. Create an initial manifest.

   Because this is a custom service, the service name should start with site. The name of this service is site/ex-svc.

   This service is a transient service and does not need a stop method.

   The default method timeout is 60 seconds. The start method in this example takes longer than 60 seconds to complete. To prevent the service from failing simply because the start method has not finished, this example specifies a longer timeout for the start method. Specifying the timeout option instead of start-timeout would set the timeout for all methods. Specifying timeout in addition to start-timeout would set the timeout for the refresh and stop methods.

   $ svcbundle -o /tmp/ex-svc.xml -s service-name=site/ex-svc \
   > -s start-method=/lib/svc/method/ex-svc -s start-timeout=120

   If this service were a contract service, you would specify contract or daemon as the value of the model or duration property, as in -s model=contract.

   By default, the instance that is created is named default and is enabled. If you want the instance to have a different name, specify the instance-name property. You can also specify instance-property, service-property, enabled, and other properties on the svcbundle command line. See the svcbundle(8) man page for descriptions.

4. Make any necessary changes to the manifest.

   The /tmp/ex-svc.xml manifest is shown in Example 1, Example Service Manifest.

   Verify that the content of the manifest is what you need. You might need to edit the manifest to add a dependency or make some other change.

   Edit the manifest to add common_name and description information in the template data area. You can also add documentation and other template data.

5. Verify that the manifest is valid.

   $ svccfg validate /tmp/ex-svc.xml

6. Copy the manifest to the standard directory.

   $ cp /tmp/ex-svc.xml /lib/svc/manifest/site/ex-svc.xml

7. Import the manifest and start the service.

   $ svcadm restart manifest-import

8. List the new service.

   Verify that the new service exists and is in the expected state.

   $ svcs ex-svc

Example 1  Example Service Manifest

The example in this procedure produced the following manifest:

<?xml version="1.0" ?>
<!DOCTYPE service_bundle
  SYSTEM '/usr/share/lib/xml/dtd/service_bundle.dtd.1'>
<!--
    Manifest created by svcbundle (2020-Oct-01 18:16:58-0700)
-->
<service_bundle name="site/ex-svc" type="manifest">
    <service name="site/ex-svc" version="1" type="service">
        <!--
            The following dependency keeps us from starting until the
            multi-user milestone is reached.
        -->
        <dependency name="multi_user_dependency" grouping="require_all"
            restart_on="none" type="service">
            <service_fmri value="svc:/milestone/multi-user"/>
        </dependency>
        <exec_method name="start" type="method" timeout_seconds="120"
            exec="/lib/svc/method/ex-svc"/>
        <!--
            The exec attribute below can be changed to a command that SMF
            should execute to stop the service.  Use svcbundle -s
            stop-method to set the attribute.
        -->
        <exec_method name="stop" type="method" timeout_seconds="60"
            exec=":true"/>
        <!--
            The exec attribute below can be changed to a command that SMF
            should execute when the service is refreshed.  Use svcbundle -s
            refresh-method to set the attribute.
        -->
        <exec_method name="refresh" type="method" timeout_seconds="60"
            exec=":true"/>
        <property_group name="startd" type="framework">
            <propval name="duration" type="astring" value="transient"/>
        </property_group>
        <instance name="default" enabled="true"/>
        <template>
            <common_name>
                <!--
                    Replace loctext content with a short name for the
                    service.
                -->
                <loctext xml:lang="C">
                        site/ex-svc
                </loctext>
            </common_name>
            <description>
                <!--
                    Replace loctext content with a brief description of the
                    service
                -->
                <loctext xml:lang="C">
                        The site/ex-svc service.
                </loctext>
            </description>
        </template>
    </service>
</service_bundle>

Example 2  Automatically Installing a Generated Manifest

If you do not need to make any changes to the new service manifest, you can use the -i option to install the manifest as soon as it is created. The svcbundle command will write the manifest to /lib/svc/manifest/site and restart the manifest-import service. Any existing file with the same name in the /lib/svc/manifest/site directory will be overwritten.

$ svcbundle -i -s service-name=site/ex-svc -s start-method=/lib/svc/method/ex-svc