svcbundle

- create an SMF service bundle

Synopsis

svcbundle [-i | -o output_file] -s name=value...

svcbundle help [name]

Description

The svcbundle command is used to generate SMF manifests. The manifest is specified by multiple -s options. To generate a manifest, you must specify service-name and start-method. The other NV pairs are optional and allow the user to specify more details of the service. The svccfg(1M) validate command will be run on the generated manifest to detect any templating conflicts.

You can also use svcbundle to generate profiles. See bundle-type below.

The second synopsis prints a help message on standard out listing all legal names. Alternatively, you can specify help and a name to see a discussion of legal values for that name.

In order to reduce the burden on the user, svcbundle makes several simplifying assumptions when generating a manifest. You can edit the generated manifest if these assumptions are not correct for your application:

• The generated manifest is intended to be used with the master restarter, svc.startd(1M).

• A dependency on svc:/milestone/multi-user will be generated to keep the service from starting too early. See rc-script below for an exception to this.

• The bundle name will be the same as the value provided for service-name.

• Timeouts for all exec_methods will be 60 seconds.

By using the -i option, you can get svcbundle to do much of the work of installing the service. It will automatically save the generated manifest in /lib/svc/manifest/site or the profile in /etc/svc/profile/site. The name of the generated file will be the basename of the service name that is specified with -s service-name, and the file will have an .xml extension. Warning: svcbundle will overwrite any existing file with that name.

svcbundle will then restart the manifest-import service to process the newly created file and incorporate it into SMF. In the manifest case, svcbundle will then wait for the service to enter a final state -- one of online, disabled, or maintenance. At the start of this wait period, svcbundle will print:

svcbundle: waiting for service to reach final_state state

...where final_state is enabled or disabled. It is safe to interrupt svcbundle after this message appears.

Clearly, to use the -i option, you need sufficient authorizations to create the file in these restricted directories and to restart the manifest-import service. See smf_security(5).

Extended Description

This section discusses name/value (NV) pairs.

The generated bundle is entirely defined by the use of multiple -s options on the command line. Each NV pair is of the form name=value where name and name come from this list:

bundle-type

Type of service bundle to generate. Legal values are manifest and profile. manifest is the default.

duration

Synonym for model.

enabled

Indicates whether or not the instance should be enabled. Legal values are true and false. The default value is true.

model

Sets the service model. This is the value of the startd/duration property. Refer to svc.startd(1M). Model can be set to one of the following values:

• contract

• daemon — synonym for contract

• child

• wait — synonym for child

• transient

The default is transient.

instance-name

Name of the instance. The default value is default.

instance-property=pg_name:prop_name:prop_type:value

service-property=pg_name:prop_name:prop_type:value

These options are used to create a property group named pg_name in the instance or service, and it will have a type of application. The PG will have a single property named prop_name with a single value that is of type prop_type. Property groups with multiple properties can be created by invoking *-property multiple times. Zero or more *-property= declarations can be used.

The property type can be defaulted by using two consecutive colons. See “Examples,” below. For manifests, a default property type of astring will be used. Profiles do not require that the property be specified, since it can usually be determined from other sources of information.

rc-script=script_path:run_level

This NV pair causes svcbundle to emit a manifest that facilitates conversion of a legacy rc script to an SMF service. script_path is the path to the rc script and run_level is the run level (see init(1M)) where the rc script runs. script_path is used to generate the start and stop exec_method elements in the manifest. The exec attribute will be set to:

script_path %m

run_level is used to generate dependencies, so that the script runs at the appropriate time during booting.

refresh-method

The command to execute when a service is refreshed. Whitespace is allowed in the value. The value can include method tokens introduced by a percent sign (%), as documented in smf_method(5). The default value is :true.

service-name

Name of the service. This NV pair is required.

start-method

The command to execute when the service is started. Whitespace is allowed in the value. The method tokens that are introduced by % as documented in smf_method(5) are allowed and will be placed in the manifest for expansion by the restarter. :true is allowed. This NV pair is required for manifests unless the rc-script NV pair is specified. It is not required for profiles.

stop-method

The command to execute when the service is stopped. It accepts values like start-method and also accepts :kill. :true is the default value for transient services and :kill for contract and child services.

Options

The following command-line options are supported:

-i

Install the generated file. See “Description” for details.

-o output_file

Specifies the name of the file to be created.

-s name=value

Specifies a name/value pair. See “Extended Description” for details.

If neither -i nor -o are specified, the generated file will be written to stdout.

Examples

Example 1 Creating Manifest for Transient Service

The following command creates a manifest for a simple transient service. Since transient services are the default for svcbundle, you can specify the manifest with just two options.

# svcbundle -s service-name=site/sneezy \
-s start-method=/lib/svc/method/sneezy

Example 2 Creating Manifest for Daemon Service

The following command creates a manifest for a daemon service.

# svcbundle -s service-name=site/sneezy \
-s start-method=/lib/svc/method/sneezy \
-s model=daemon

Example 3 Creating Manifest for Daemon Service with Stop and Refresh Commands

The following command creates a manifest for a daemon service with stop and refresh commands.

# svcbundle -s service-name=site/sleepy \
-s start-method="/lib/svc/method/sleepy %m" \
-s stop-method="/lib/svc/method/sleepy %m" \
-s refresh-method="/lib/svc/method/sleepy %m" \
-s model=daemon

Example 4 Creating Manifest with Instance Properties

The following command creates a manifest with instance properties.

# svcbundle -s service-name=system/happy \
-s start-method=/lib/svc/method/happy \
-s instance-property=config:velocity:count:50 \
-s instance-property=config:color:astring:red

The generated manifest will create a service instance with a config property group containing two properties, velocity and color.

Example 5 Creating Manifest for rc Script Conversion

The following command creates a manifest to assist in converting an rc script. This example assumes that the rc script runs at the multiuser level and does not start a daemon.

# svcbundle -s service-name=doc \
-s rc-script=/etc/init.d/doc:2

The conscientious user will modify the rc script to include /lib/svc/share/smf_include.sh.

Example 6 Generating Profile to Modify Service Property

The following command generates a profile to set the nfsmapid_domain property of the grumpy service.

# svcbundle -s bundle-type=profile \
-s service-name=network/nfs/grumpy \
-s service-property=nfs-props:nfsmapid_domain:astring:grumpy

Example 7 Using the Default Property Type

The following command sets the property type for config/color defaults to astring.

# svcbundle -s service-name=system/happy \
-s start-method=/lib/svc/method/happy \
-s instance-property=config:color::red

Example 8 Installing the Manifest

The following command uses the -i option to install the manifest. In this example the generated manifest will be written to /lib/svc/manifest/site/bashful.xml, since bashful is the basename of the service name.

# svcbundle -i -s service-name=application/bashful \
-s start-method=/opt/bashful/start
svcbundle: waiting for application/bashful to reach enabled state

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

svcs(1), init(1M), svc.startd(1M), svccfg(1M), service_bundle(4), attributes(5), smf_method(5), smf_security(5), smf_template(5)