By Tom Whitten-Oracle on Jun 29, 2015
Many people state that one of the roadblocks to creating a new SMF service for Oracle Solaris is the need to write the service manifest in XML. The svcbundle(1M)program is intended to help you get by that roadblock. Based on the command line options svcbundle generates a valid service manifest or profile. In all but the simplist of cases, you will need to hand edit the generated file, but svcbundle gets you off to a good start. This is the first in a series of blogs that discusses what you can do with svcbundle.
svcbundle is driven by specifying multiple -s options on the command line. Each -s is followed by a name=value pair. If you type svcbundle help, you will get a list of items that you use in the name part of the name=value pair. Use of the various names is documented in the man page, or typing the name as an argument of the svcbundle help command gives you more information about it:
$ svcbundle help bundle-type -s bundle-type=type Specifies the type of bundle to generate. Legal values are "manifest" and "profile". The default is manifest.
A Simple Example
The simplest svcbundle command that you can type requires the service-name and start-method names. Most likely you'll want to use more name=value pairs to get a useful manifest, but I'll discuss that in a future blog. Let's look at what you get with just these two pairs.
$ svcbundle -s service-name=myservice \ -s start-method="/lib/svc/method/myservice %m"
Note the use of quotes to protect the white space in the start-method command. %m tells svc.startd to pass in the name of method being invoked to the myservice command. See smf_method(5) for details. I've captured the output and added line numbers so that we can talk about the generated manifest.
1 <?xml version="1.0" ?> 2 <!DOCTYPE service_bundle 3 SYSTEM '/usr/share/lib/xml/dtd/service_bundle.dtd.1'> 4 <!-- 5 Manifest created by svcbundle (2015-Jun-17 10:38:04-0700) 6 --> 7 <service_bundle type="manifest" name="myservice"> 8 <service version="1" type="service" name="myservice"> 9 <!-- 10 The following dependency keeps us from starting until the 11 multi-user milestone is reached. 12 --> 13 <dependency restart_on="none" type="service" 14 name="multi_user_dependency" grouping="require_all"> 15 <service_fmri value="svc:/milestone/multi-user"/> 16 </dependency> 17 <exec_method timeout_seconds="60" type="method" name="start" 18 exec="/lib/svc/method/myservice %m"/> 19 <!-- 20 The exec attribute below can be changed to a command that SMF 21 should execute to stop the service. See smf_method(5) for more 22 details. 23 --> 24 <exec_method timeout_seconds="60" type="method" name="stop" 25 exec=":true"/> 26 <!-- 27 The exec attribute below can be changed to a command that SMF 28 should execute when the service is refreshed. Services are 29 typically refreshed when their properties are changed in the 30 SMF repository. See smf_method(5) for more details. It is 31 common to retain the value of :true which means that SMF will 32 take no action when the service is refreshed. Alternatively, 33 you may wish to provide a method to reread the SMF repository 34 and act on any configuration changes. 35 --> 36 <exec_method timeout_seconds="60" type="method" name="refresh" 37 exec=":true"/> 38 <property_group type="framework" name="startd"> 39 <propval type="astring" name="duration" value="transient"/> 40 </property_group> 41 <instance enabled="true" name="default"/> 42 <template> 43 <common_name> 44 <loctext xml:lang="C"> 45 <!-- 46 Replace this comment with a short name for the 47 service. 48 --> 49 </loctext> 50 </common_name> 51 <description> 52 <loctext xml:lang="C"> 53 <!-- 54 Replace this comment with a brief description of 55 the service 56 --> 57 </loctext> 58 </description> 59 </template> 60 </service> 61 </service_bundle>
Editing the Manifests
Note that svcbundle includes comments in the generated manifest to guide you in edits that you might wish to make. Let's look at some places in the manifest where I suggest you consider making changes.
First consider the dependency declaration at lines 13-16. The default dependency generated by svcbundle makes the service dependent on the multi-user milestone. You may want to edit this so that your service is dependent on a different milestone or a specific service.
Next consider the declaration of the start method in lines 17-18. The default timeout_seconds of 60 seconds may be too short for your service, so you will want to increase it. We quite often find that service developers under estimate the amount of time that it takes to start a service. Think about what might happen if the service is running in a zone where many non-global zones are being started simultaneously.
Finally, you should always edit <common_name> (lines 43-50) and <description> (lines 51-58) of the template section. Replace the comments in the <common_name> and <description> sections of the template to provide meaningful data there.
svcbundle Provided Defaults
In the simple example svcbundle used default values for many entries in the manifest. I'd like to point out a few of these, just so that you will be aware of them. These are not items that you'll need to edit, though. If you don't like the defaults, you can change things with some of the other name options on the command line.
In lines 24-25 the stop method has been set to :true. In lines 38-39 the service has been declared as a transient service. See svc.startd(1M) for a discussion of service models. Finally, in line 41, the instance name is declared as default, and the instance is enabled. As we'll see in my next blog, you can change all of the default assignments by specifying more name=value pairs on the command line, so no need to edit