man/man7/smf_method.7

.\" The contents of this file are subject to the terms of the Common
.\" Development and Distribution License (the "License").  You may not use
.\" this file except in compliance with the License. You can obtain a copy
.\" of the license at usr/src/OPENSOLARIS.LICENSE or
.\" http://www.opensolaris.org/os/licensing.
.\"
.\"  See the License for the specific language governing permissions and
.\" limitations under the License. When distributing Covered Code, include
.\" this CDDL HEADER in each file and include the License file at
.\" usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below
.\" this CDDL HEADER, with
.\"
.\" the fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2017 RackTop Systems.
.\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association.
.\" Copyright 2026 Oxide Computer Company
.\"
.Dd July 18, 2026
.Dt SMF_METHOD 7
.Os
.Sh NAME
.Nm smf_method
.Nd service management framework conventions for methods
.Sh DESCRIPTION
The class of services managed by
.Xr svc.startd 8
in the service management framework,
.Xr smf 7 ,
consists of applications that fit a simple
.Sm off
.Xr fork 2
-
.Xr exec 2
.Sm on
model.
The
.Xr svc.startd 8
master daemon and other restarters support the
.Sm off
.Xr fork 2
-
.Xr exec 2
.Sm on
model, potentially with additional capabilities.
The
.Xr svc.startd 8
daemon and other restarters require that the methods which activate,
manipulate, or examine a service instance follow the conventions described in
this manual page.
.Ss 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:
.Pp
.Dl /path/to/method_executable abbr_method_name
.Pp
The
.Ar abbr_method_name
used for the recommended form is a supported method such as
.Cm start
or
.Cm stop .
The set of methods supported by a restarter is given on the related restarter
page.
The
.Xr svc.startd 8
daemon supports
.Cm start ,
.Cm stop ,
and
.Cm refresh
methods.
.Pp
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.
.Ss Environment Variables
The restarter provides four environment variables to the method that determine
the context in which the method is invoked.
.Bl -tag -width Ev
.It Sy SMF_FMRI
The service fault management resource identifier
.Pq FMRI
of the instance for which the method is invoked.
.It Sy SMF_METHOD
The full name of the method being invoked, such as
.Cm start
or
.Cm stop .
.It Sy SMF_RESTARTER
The service FMRI of the restarter that invokes the method
.It Sy SMF_ZONENAME
The name of the zone in which the method is running.
This can also be obtained by using the
.Xr zonename 1
command.
.El
.Pp
These variables should be removed from the environment prior to the invocation
of any persistent process by the method.
A convenience shell function,
.Fn smf_clear_env ,
is given for service authors who use Bourne-compatible shell scripting to
compose service methods in the include file described below.
.Pp
The method context can cause other environment variables to be set as described
below.
.Ss Method Definition
A method is defined minimally by three properties in a property group of type
.Sy method .
.Pp
These properties are:
.Bl -tag -width timeout_seconds_(count)
.It Sy exec Pq Ar astring
Method executable string.
.It Sy timeout_seconds Pq Ar count
Number of seconds before method times out.
See the
.Sy Timeouts
section for more detail.
.It Sy type Pq Ar astring
Method type.
Currently always set to
.Sy method .
.El
.Pp
A Method Context can be defined to further refine the execution environment of
the method.
See the
.Sx Method Context
section for more information.
If no Method Context is present then the service is started as root, with user
ID and group ID set to 0 and full privileges in effect, and in the system root
directory,
.Pa / .
However, if a Method Context is used then the defaults described below in
.Sx Method Context
apply.
Note that in particular, for services started as root, this may cause a change
of working directory to
.Pa /root .
.Ss Method Tokens
When defined in the
.Sy exec
string of the method by the restarter
.Xr svc.startd 8 ,
a set of tokens are parsed and expanded with appropriate value.
Other restarters might not support method tokens.
For example, the delegated restarter for inet services,
.Xr inetd 8 ,
does
.Em not
support the following method expansions.
.Bl -tag -width xxxxxxxxxxx
.It Sy %%
%
.It Sy %r
Name of the restarter, such as
.Sy svc.startd
.It Sy %m
The full name of the method being invoked, such as
.Cm start
or
.Cm stop .
.It Sy %s
Name of the service
.It Sy %i
Name of the instance
.It Sy %f
FMRI of the instance
.It Sy %{prop[:,]}
Value(s) of a property.
The
.Sy prop
might be a property FMRI, a property group name and a property name separated
by a /, or a property name in the
.Sy application
property group.
These values can be followed by a ,
.Pq comma
or :
.Pq 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 \e
.Pq backslash :
.Pp
.D1 \&; & \&( \&) \&| ^ < > newline space tab \e \&" ' \(ga
.Pp
An invalid expansion constitutes method failure.
.El
.Pp
Two explicit tokens can be used in the place of method commands.
.Bl -tag -width :kill_[-signal]
.It Ic :kill Op Fl signal
Sends the specified signal, which is
.Dv SIGTERM
by default, to all processes in the primary instance contract.
Always returns
.Sy SMF_EXIT_OK .
This token should be used to replace common
.Xr pkill 1
invocations.
.It Ic :true
Always returns
.Sy 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.
.El
.Ss 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.
.Pp
The following exit status codes are defined in
.In libscf.h
and in the shell support file.
.Bl -column "SMF_EXIT_TEMP_DISABLE" "non-zero"
.It Sy SMF_EXIT_OK Ta Sy 0 Ta
Method exited, performing its operation successfully.
.It Sy SMF_EXIT_NODAEMON Ta Sy 94 Ta
Method exited successfully but purposefully leaves no processes remaining in
the contract; it should be treated as if it had a transient service model.
.It Sy SMF_EXIT_ERR_FATAL Ta Sy 95 Ta
Method failed fatally and is irrecoverable without administrative
intervention.
.It Sy SMF_EXIT_ERR_CONFIG Ta Sy 96 Ta
Unrecoverable configuration error.
A common condition that returns this exit status is the absence of required
configuration files for an enabled service instance.
.It Sy SMF_EXIT_MON_DEGRADE Ta Sy 97 Ta
Method encountered some problems; the service may not be fully functional.
.It Sy SMF_EXIT_ERR_NOSMF Ta Sy 99 Ta
Method has been mistakenly invoked outside the
.Xr smf 7
facility.
Services that depend on
.Xr smf 7
capabilities should exit with this status value in that situation.
.It Sy SMF_EXIT_ERR_PERM Ta Sy 100 Ta
Method requires a form of permission such as file access, privilege,
authorization, or other credential that is not available when invoked.
.It Sy SMF_EXIT_TEMP_DISABLE Ta Sy 101 Ta
Method requests that the service instance be temporarily disabled.
This is honoured only for start methods.
A method may use this when it determines that the service should not run in the
current environment.
The disable does not persist across a reboot, so the method runs again on the
next boot in case the condition that prompted it has since cleared.
The instance can also be re-enabled at any time using
.Xr svcadm 8 .
This is equivalent to the service running
.Ql svcadm disable -t
on itself, but is performed atomically by the restarter.
See
.Fn smf_method_exit
below for a convenient way to record the reason for the disable.
.It Sy SMF_EXIT_ERR_OTHER Ta non-zero Ta
Any non-zero exit status from a method is treated as an unknown error.
A series of unknown errors can be diagnosed as a fault by the restarter or on
behalf of the restarter.
.El
.Pp
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.
.Ss 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
.Sy timeout_seconds
property.
.Pp
If you specify a
.Sy timeout_seconds
of 0 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.
.Pp
-1 is also accepted, but is a deprecated specification.
.Ss Shell Programming Support
A set of environment variables that define the above exit status values is
provided with convenience shell functions in the file
.Pa /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.
.Pp
To assist in the composition of scripts that can serve as SMF methods as well
as
.Pa /etc/init.d
scripts, the
.Fn smf_present
shell function is provided.
If the
.Xr smf 7
facility is not available,
.Fn smf_present
returns a non-zero exit status.
.Pp
One possible structure for such a script follows:
.Bd -literal -offset indent
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
.Ed
.Pp
This example shows the use of both convenience functions that are provided.
.Pp
The
.Fn smf_method_exit
function records a human-readable
.Ar reason
for the action a method is taking and then exits with the provided
.Ar exit_status :
.Bd -literal -offset indent
smf_method_exit exit_status reason
.Ed
.Pp
It is intended for use with
.Sy SMF_EXIT_TEMP_DISABLE .
The
.Ar reason
is stored in the
.Sy general_ovr/comment
property of the instance, the same property used by the
.Fl c
option of
.Xr svcadm 8 ,
and is displayed by
.Xr svcs 1
in the
.Fl x
and
.Fl l
output while the instance remains disabled.
Like the temporary disable itself, this property does not persist across a
reboot and is removed automatically when the instance is re-enabled.
.Ss Method Context
The service management facility offers a common mechanism to set the context in
which the
.Sm off
.Xr fork 2
-
.Xr exec 2
.Sm on
model services execute.
.Pp
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.
.Pp
A method context can contain the following properties:
.Bl -tag -width working_directory
.It Sy use_profile
A boolean that specifies whether the profile should be used instead of the
.Sy user ,
.Sy group ,
.Sy privileges ,
and
.Sy limit_privileges
properties.
.It Sy environment
Environment variables to insert into the environment of the method, in the form
of a number of NAME=value strings.
.It Sy profile
The name of an RBAC
.Pq role-based access control
profile which, along with the method executable, identifies an entry in
.Xr exec_attr 5 .
.It Sy user
The user ID in numeric or text form.
.It Sy group
The group ID in numeric or text form.
.It Sy supp_groups
An optional string that specifies the supplemental group memberships by ID, in
numeric or text form.
.It Sy privileges
An optional string specifying the privilege set as defined in
.Xr privileges 7 .
.It Sy limit_privileges
An optional string specifying the limit privilege set as defined in
.Xr privileges 7 .
.It Sy working_directory
The home directory from which to launch the method.
.Cm :home
can be used as a token to indicate the home directory of the user whose
.Sy uid
is used to launch the method.
If the property is unset, the default depends on the presence of the
.Sy use_profile ,
.Sy profile ,
.Sy user ,
and
.Sy group
properties.
If any of these are set then
.Cm :home
is used, otherwise the method starts in the root directory,
.Pa / .
.It Sy security_flags
The security flags to apply when launching the method.
See
.Xr security-flags 7 .
.Pp
The
.Dq default
keyword specifies those flags specified in svc:/system/process-security.
The
.Dq all
keyword enables all flags, the
.Dq none
keyword enables no flags.
The
.Dq current
keyword specifies the current flags.
Flags may be added by specifying their name
.Pq optionally preceded by Sq \&+ ,
and removed by preceding their name with
.Sq \&- .
.Pp
Use of
.Dq all
has associated risks, as future versions of the system may include further
flags which may harm poorly implemented software.
.It Sy corefile_pattern
An optional string that specifies the corefile pattern to use for the service,
as per
.Xr coreadm 8 .
Most restarters supply a default.
Setting this property overrides local customizations to the global core pattern.
.It Sy project
The project ID in numeric or text form.
.Cm :default
can be used as a token to indicate a project identified by
.Xr getdefaultproj 3PROJECT
for the user whose
.Sy uid
is used to launch the method.
.It Sy resource_pool
The resource pool name on which to launch the method.
.Cm :default
can be used as a token to indicate the pool specified in the
.Xr project 5
entry given in the
.Sy project
attribute above.
.El
.Pp
The method context can be set for the entire service instance by specifying a
.Sy 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.
.Pp
Invalid method context settings always lead to failure of the method, with the
exception of invalid environment variables that issue warnings.
.Pp
In addition to the context defined above, many
.Sm off
.Xr fork 2
-
.Xr exec 2
.Sm on
model restarters also use the following conventions when invoking executables
as methods:
.Bl -tag -width Ds
.It Sy Argument array
The arguments in
.Sy argv[]
are set consistently with the result of
.Sy /bin/sh -c
of the
.Sy exec
string.
.It Sy File descriptors
File descriptor
.Sy 0
is
.Pa /dev/null .
File descriptors
.Sy 1
and
.Sy 2
are recommended to be a per-service log file.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa /lib/svc/share/smf_include.sh
Definitions of exit status values.
.It Pa /usr/include/libscf.h
Definitions of exit status codes.
.El
.Sh SEE ALSO
.Xr svcs 1 ,
.Xr zonename 1 ,
.Xr exec 2 ,
.Xr fork 2 ,
.Xr getdefaultproj 3PROJECT ,
.Xr exec_attr 5 ,
.Xr project 5 ,
.Xr service_bundle 5 ,
.Xr attributes 7 ,
.Xr privileges 7 ,
.Xr rbac 7 ,
.Xr security-flags 7 ,
.Xr smf 7 ,
.Xr smf_bootstrap 7 ,
.Xr zones 7 ,
.Xr coreadm 8 ,
.Xr inetd 8 ,
.Xr svc.startd 8 ,
.Xr svcadm 8 ,
.Xr svccfg 8
.Sh NOTES
The present version of
.Xr smf 7
does not support multiple repositories.
.Pp
When a service is configured to be started as root but with privileges
different from
.Sy limit_privileges ,
the resulting process is privilege aware.
This can be surprising to developers who expect
.No seteuid Ns Pq <non-zero UID>
to reduce privileges to basic or less.