smf_method(5) Standards, Environments, and Macros smf_method(5)
smf_method - service management framework conventions for methods
The class of services managed by svc.startd(1M) in the service management framework,
smf(5), consists of applications that fit a simple fork(2)-exec(2) model. The
svc.startd(1M) master daemon and other restarters support the fork(2)-exec(2) model,
potentially with additional capabilities. The svc.startd(1M) daemon and other restarters
require that the methods which activate, manipulate, or examine a service instance follow
the conventions described in this manual page.
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 exe-
cutable is used, the convention recommends the form:
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(1M) 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.
The restarter provides four environment variables to the method that determine the context
in which the method is invoked.
The service fault management resource identifier (FMRI) of the instance for which the
method is invoked.
The full name of the method being invoked, such as start or stop.
The service FMRI of the restarter that invokes the method
The name of the zone in which the method is running. This can also be obtained by
using the zonename(1) command.
These variables should be removed from the environment prior to the invocation of any per-
sistent 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.
A method is defined minimally by three properties in a propertygroup of type method.
These properties are:
exec (astring) Method executable string.
timeout_seconds (count) Number of seconds before method times out. See the Timeouts
section for more detail.
type (astring) Method type. Currently always set to method.
A Method Context can be defined to further refine the execution environment of the method.
See the Method Context section for more information.
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(1M), does not support the follow-
ing method expansions.
Name of the restarter, such as svc.startd
The full name of the method being invoked, such as start or stop.
Name of the service
Name of the instance
FMRI of the instance
Value(s) of a property. The prop might be a property FMRI, a property group name and a
property name separated by a /, or a property name in the application property group.
These values can be followed by a , (comma) or : (colon). If present, the separators
are used to separate multiple values. If absent, a space is used. The following shell
metacharacters encountered in string values are quoted with a (backslash):
; & ( ) | ^ < > newline space tab " '
An invalid expansion constitutes method failure.
Two explicit tokens can be used in the place of method commands.
Sends the specified signal, which is SIGTERM by default, to all processes in the pri-
mary instance contract. Always returns SMF_EXIT_OK. This token should be used to
replace common pkill invocations.
Always returns SMF_EXIT_OK. This token should be used for methods that are required by
the restarter but which are unnecessary for the particular service implementation.
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.
SMF_EXIT_OK 0 Method exited, performing its
SMF_EXIT_ERR_FATAL 95 Method failed fatally and is
unrecoverable without admin-
SMF_EXIT_ERR_CONFIG 96 Unrecoverable configuration
error. A common condition
that returns this exit status
is the absence of required
configuration files for an
enabled service instance.
SMF_EXIT_ERR_NOSMF 99 Method has been mistakenly
invoked outside the smf(5)
facility. Services that
depend on smf(5) capabilities
should exit with this status
SMF_EXIT_ERR_PERM 100 Method requires a form of
permission such as file
access, privilege, authoriza-
tion, or other credential
that is not available when
SMF_EXIT_ERR_OTHER non-zero Any non-zero exit status from
a method is treated as an
unknown error. A series of
unknown errors can be diag-
nosed as a fault by the
restarter or on behalf of the
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
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-compati-
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(5) 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
# Shell code to run application as /etc/init.d script
This example shows the use of both convenience functions that are provided.
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 secu-
A method context can contain the following properties:
A boolean that specifies whether the profile should be used instead of the user,
group, privileges, and limit_privileges properties.
Environment variables to insert into the environment of the method, in the form of a
number of NAME=value strings.
The name of an RBAC (role-based access control) profile which, along with the method
executable, identifies an entry in exec_attr(4).
The user ID in numeric or text form.
The group ID in numeric or text form.
An optional string that specifies the supplemental group memberships by ID, in numeric
or text form.
An optional string specifying the privilege set as defined in privileges(5).
An optional string specifying the limit privilege set as defined in privileges(5).
The home directory from which to launch the method. :home can be used as a token to
indicate the home directory of the user whose uid is used to launch the method. If the
property is unset, :home is used.
An optional string that specifies the corefile pattern to use for the service, as per
coreadm(1M). Most restarters supply a default. Setting this property overrides local
customizations to the global core pattern.
The project ID in numeric or text form. :default can be used as a token to indicate a
project identified by getdefaultproj(3PROJECT) for the user whose uid is used to
launch the method.
The resource pool name on which to launch the method. :default can be used as a token
to indicate the pool specified in the project(4) entry given in the project attribute
The method context can be set for the entire service instance by specifying a method_con-
text 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:
The arguments in argv are set consistently with the result /bin/sh -c of the exec
File descriptor 0 is /dev/null. File descriptors 1 and 2 are recommended to be a per-
service log file.
Definitions of exit status values.
Definitions of exit status codes.
zonename(1), coreadm(1M), inetd(1M), svccfg(1M), svc.startd(1M), exec(2), fork(2), getde-
faultproj(3PROJECT), exec_attr(4), project(4), service_bundle(4), attributes(5), privi-
leges(5), rbac(5), smf(5), smf_bootstrap(5), zones(5)
The present version of smf(5) does not support multiple repositories.
SunOS 5.11 3 May 2008 smf_method(5)