Invocation form

The form of a method invocation is not dictated by convention. In some cases, a method invocation might consist of the direct invocation of the daemon or other binary executable that provides the service. For cases in which an executable script or other mediating executable is used, the convention recommends the form:

/path/to/method_executable abbr_method_name

The abbr_method_name used for the recommended form is a supported method such as start or stop. The set of methods supported by a restarter is given on the related restarter page. The svc.startd(8) daemon supports start, stop, and refresh methods.

A restarter might define other kinds of methods beyond those referenced in this page. The conventions surrounding such extensions are defined by the restarter and might not be identical to those given here.

Environment Variables

The restarter provides four environment variables to the method that determine the context in which the method is invoked.

SMF_FMRI

SMF_METHOD

SMF_RESTARTER

SMF_ZONENAME

These variables should be removed from the environment prior to the invocation of any persistent process by the method. A convenience shell function, smf_clear_env, is given for service authors who use Bourne-compatible shell scripting to compose service methods in the include file described below.

The method context can cause other environment variables to be set as described below.

Method Definition

A method is defined minimally by three properties in a propertygroup of type method.

These properties are:

exec (astring)

timeout_seconds (count)

type (astring)

A Method Context can be defined to further refine the execution environment of the method. See the Method Context section for more information. If no Method Context is present then the service will be started as root (with user ID and group ID set to 0 and full privileges in effect) and in the system root directory, `/'. However, if a Method Context is used then the defaults described below in Method Context will apply. Note that in particular, for services started as root, this may cause a change of working directory to `/root'.

Method Tokens

When defined in the exec string of the method by the restarter svc.startd, a set of tokens are parsed and expanded with appropriate value. Other restarters might not support method tokens. The delegated restarter for inet services, inetd(8), does not support the following method expansions.

%%

%r

%m

%s

%i

%f

%{prop[:,]}

; & ( ) | ^ < > newline space tab    " '

Two explicit tokens can be used in the place of method commands.

:kill [-signal]

:true

Exiting and Exit Status

The required behavior of a start method is to delay exiting until the service instance is ready to answer requests or is otherwise functional.

The following exit status codes are defined in <libscf.h> and in the shell support file.

Use of a precise exit code allows the responsible restarter to categorize an error response as likely to be intermittent and worth pursuing restart or permanent and request administrative intervention.

Timeouts

Each method can have an independent timeout, given in seconds. The choice of a particular timeout should be based on site expectations for detecting a method failure due to non-responsiveness. Sites with replicated filesystems or other failover resources can elect to lengthen method timeouts from the default. Sites with no remote resources can elect to shorten the timeouts. Method timeout is specified by the timeout_seconds property.

If you specify 0 timeout_seconds for a method, it declares to the restarter that there is no timeout for the service. This setting is not preferred, but is available for services that absolutely require it.

-1 timeout_seconds is also accepted, but is a deprecated specification.

Shell Programming Support

A set of environment variables that define the above exit status values is provided with convenience shell functions in the file /lib/svc/share/smf_include.sh. This file is a Bourne shell script suitable for inclusion via the source operator in any Bourne-compatible shell.

To assist in the composition of scripts that can serve as SMF methods as well as /etc/init.d scripts, the smf_present() shell function is provided. If the smf(7) facility is not available, smf_present() returns a non-zero exit status.

One possible structure for such a script follows:

if smf_present; then


      # Shell code to run application as managed service


      ....


      smf_clear_env
else


      # Shell code to run application as /etc/init.d script


      ....
fi

This example shows the use of both convenience functions that are provided.

Method Context

The service management facility offers a common mechanism set the context in which the fork(2)-exec(2) model services execute.

The desired method context should be provided by the service developer. All service instances should run with the lowest level of privileges possible to limit potential security compromises.

A method context can contain the following properties:

use_profile

environment

profile

user

group

supp_groups

privileges

limit_privileges

working_directory

security_flags

corefile_pattern

project

resource_pool

The method context can be set for the entire service instance by specifying a method_context property group for the service or instance. A method might override the instance method context by providing the method context properties on the method property group.

Invalid method context settings always lead to failure of the method, with the exception of invalid environment variables that issue warnings.

In addition to the context defined above, many fork(2)-exec(2) model restarters also use the following conventions when invoking executables as methods:

Argument array

File descriptors