SMF_METHOD(7) Standards, Environments, and Macros SMF_METHOD(7)
smf_method - service management framework conventions for methods
The class of services managed by svc.startd(8) in the service
management framework, smf(7), consists of applications that fit a
simple fork(2)-exec(2) model. The svc.startd(8) master daemon and
other restarters support the fork(2)-exec(2) model, potentially with
additional capabilities. The 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.
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.
The restarter provides four environment variables to the method that
determine the context in which the method is invoked.
SMF_FMRI The service fault management resource identifier
(FMRI) of the instance for which the method is
invoked.
SMF_METHOD The full name of the method being invoked, such as
start or stop.
SMF_RESTARTER The service FMRI of the restarter that invokes the
method
SMF_ZONENAME 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 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.
A method is defined minimally by three properties in a property group
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. 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, /. However, if a Method
Context is used then the defaults described below in Method Context
apply. Note that in particular, for services started as root, this may
cause a change of working directory to /root.
When defined in the exec string of the method by the restarter
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, inetd(8), does not support
the following method expansions.
%% %
%r Name of the restarter, such as svc.startd
%m The full name of the method being invoked, such as start
or stop.
%s Name of the service
%i Name of the instance
%f FMRI of the instance
%{prop[:,]} 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.
:kill [-signal] Sends the specified signal, which is SIGTERM by
default, to all processes in the primary instance
contract. Always returns SMF_EXIT_OK. This token
should be used to replace common pkill(1) invocations.
:true 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.
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
operation successfully.
SMF_EXIT_NODAEMON 94 Method exited successfully but
purposefully leaves no processes
remaining in the contract; it
should be treated as if it had a
transient service model.
SMF_EXIT_ERR_FATAL 95 Method failed fatally and is
irrecoverable without
administrative intervention.
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_MON_DEGRADE 97 Method encountered some problems;
the service may not be fully
functional.
SMF_EXIT_ERR_NOSMF 99 Method has been mistakenly invoked
outside the smf(7) facility.
Services that depend on smf(7)
capabilities should exit with this
status value in that situation.
SMF_EXIT_ERR_PERM 100 Method requires a form of
permission such as file access,
privilege, authorization, or other
credential that is not available
when invoked.
SMF_EXIT_TEMP_DISABLE 101 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
svcadm(8). This is equivalent to
the service running `svcadm
disable -t' on itself, but is
performed atomically by the
restarter. See smf_method_exit()
below for a convenient way to
record the reason for the disable.
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 diagnosed as a fault by the
restarter or on behalf of the
restarter.
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.
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 a 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.
-1 is also accepted, but is a deprecated specification.
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.
The smf_method_exit() function records a human-readable reason for the
action a method is taking and then exits with the provided exit_status:
smf_method_exit exit_status reason
It is intended for use with SMF_EXIT_TEMP_DISABLE. The reason is
stored in the general_ovr/comment property of the instance, the same
property used by the -c option of svcadm(8), and is displayed by
svcs(1) in the -x and -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.
The service management facility offers a common mechanism to 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 A boolean that specifies whether the profile should
be used instead of the user, group, privileges, and
limit_privileges properties.
environment Environment variables to insert into the environment
of the method, in the form of a number of NAME=value
strings.
profile The name of an RBAC (role-based access control)
profile which, along with the method executable,
identifies an entry in exec_attr(5).
user The user ID in numeric or text form.
group The group ID in numeric or text form.
supp_groups An optional string that specifies the supplemental
group memberships by ID, in numeric or text form.
privileges An optional string specifying the privilege set as
defined in privileges(7).
limit_privileges An optional string specifying the limit privilege
set as defined in privileges(7).
working_directory 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, the default
depends on the presence of the use_profile, profile,
user, and group properties. If any of these are set
then :home is used, otherwise the method starts in
the root directory, /.
security_flags The security flags to apply when launching the
method. See security-flags(7).
The "default" keyword specifies those flags
specified in svc:/system/process-security. The
"all" keyword enables all flags, the "none" keyword
enables no flags. The "current" keyword specifies
the current flags. Flags may be added by specifying
their name (optionally preceded by `+'), and removed
by preceding their name with `-'.
Use of "all" has associated risks, as future
versions of the system may include further flags
which may harm poorly implemented software.
corefile_pattern An optional string that specifies the corefile
pattern to use for the service, as per coreadm(8).
Most restarters supply a default. Setting this
property overrides local customizations to the
global core pattern.
project 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.
resource_pool 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(5) entry given in
the project attribute above.
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
The arguments in argv[] are set consistently with the result of
/bin/sh -c of the exec string.
File descriptors
File descriptor 0 is /dev/null. File descriptors 1 and 2 are
recommended to be a per-service log file.
/lib/svc/share/smf_include.sh
Definitions of exit status values.
/usr/include/libscf.h
Definitions of exit status codes.
svcs(1), zonename(1), exec(2), fork(2), getdefaultproj(3PROJECT),
exec_attr(5), project(5), service_bundle(5), attributes(7),
privileges(7), rbac(7), security-flags(7), smf(7), smf_bootstrap(7),
zones(7), coreadm(8), inetd(8), svc.startd(8), svcadm(8), svccfg(8)
The present version of smf(7) does not support multiple repositories.
When a service is configured to be started as root but with privileges
different from limit_privileges, the resulting process is privilege
aware. This can be surprising to developers who expect
seteuid(<non-zero UID>) to reduce privileges to basic or less.
illumos July 18, 2026 illumos
NAME
smf_method - service management framework conventions for methods
DESCRIPTION
The class of services managed by svc.startd(8) in the service
management framework, smf(7), consists of applications that fit a
simple fork(2)-exec(2) model. The svc.startd(8) master daemon and
other restarters support the fork(2)-exec(2) model, potentially with
additional capabilities. The 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.
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 The service fault management resource identifier
(FMRI) of the instance for which the method is
invoked.
SMF_METHOD The full name of the method being invoked, such as
start or stop.
SMF_RESTARTER The service FMRI of the restarter that invokes the
method
SMF_ZONENAME 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 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 property group
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. 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, /. However, if a Method
Context is used then the defaults described below in Method Context
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(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, inetd(8), does not support
the following method expansions.
%% %
%r Name of the restarter, such as svc.startd
%m The full name of the method being invoked, such as start
or stop.
%s Name of the service
%i Name of the instance
%f FMRI of the instance
%{prop[:,]} 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.
:kill [-signal] Sends the specified signal, which is SIGTERM by
default, to all processes in the primary instance
contract. Always returns SMF_EXIT_OK. This token
should be used to replace common pkill(1) invocations.
:true 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
operation successfully.
SMF_EXIT_NODAEMON 94 Method exited successfully but
purposefully leaves no processes
remaining in the contract; it
should be treated as if it had a
transient service model.
SMF_EXIT_ERR_FATAL 95 Method failed fatally and is
irrecoverable without
administrative intervention.
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_MON_DEGRADE 97 Method encountered some problems;
the service may not be fully
functional.
SMF_EXIT_ERR_NOSMF 99 Method has been mistakenly invoked
outside the smf(7) facility.
Services that depend on smf(7)
capabilities should exit with this
status value in that situation.
SMF_EXIT_ERR_PERM 100 Method requires a form of
permission such as file access,
privilege, authorization, or other
credential that is not available
when invoked.
SMF_EXIT_TEMP_DISABLE 101 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
svcadm(8). This is equivalent to
the service running `svcadm
disable -t' on itself, but is
performed atomically by the
restarter. See smf_method_exit()
below for a convenient way to
record the reason for the disable.
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 diagnosed as a fault by the
restarter or on behalf of the
restarter.
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 a 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.
-1 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.
The smf_method_exit() function records a human-readable reason for the
action a method is taking and then exits with the provided exit_status:
smf_method_exit exit_status reason
It is intended for use with SMF_EXIT_TEMP_DISABLE. The reason is
stored in the general_ovr/comment property of the instance, the same
property used by the -c option of svcadm(8), and is displayed by
svcs(1) in the -x and -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.
Method Context
The service management facility offers a common mechanism to 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 A boolean that specifies whether the profile should
be used instead of the user, group, privileges, and
limit_privileges properties.
environment Environment variables to insert into the environment
of the method, in the form of a number of NAME=value
strings.
profile The name of an RBAC (role-based access control)
profile which, along with the method executable,
identifies an entry in exec_attr(5).
user The user ID in numeric or text form.
group The group ID in numeric or text form.
supp_groups An optional string that specifies the supplemental
group memberships by ID, in numeric or text form.
privileges An optional string specifying the privilege set as
defined in privileges(7).
limit_privileges An optional string specifying the limit privilege
set as defined in privileges(7).
working_directory 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, the default
depends on the presence of the use_profile, profile,
user, and group properties. If any of these are set
then :home is used, otherwise the method starts in
the root directory, /.
security_flags The security flags to apply when launching the
method. See security-flags(7).
The "default" keyword specifies those flags
specified in svc:/system/process-security. The
"all" keyword enables all flags, the "none" keyword
enables no flags. The "current" keyword specifies
the current flags. Flags may be added by specifying
their name (optionally preceded by `+'), and removed
by preceding their name with `-'.
Use of "all" has associated risks, as future
versions of the system may include further flags
which may harm poorly implemented software.
corefile_pattern An optional string that specifies the corefile
pattern to use for the service, as per coreadm(8).
Most restarters supply a default. Setting this
property overrides local customizations to the
global core pattern.
project 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.
resource_pool 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(5) entry given in
the project attribute above.
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
The arguments in argv[] are set consistently with the result of
/bin/sh -c of the exec string.
File descriptors
File descriptor 0 is /dev/null. File descriptors 1 and 2 are
recommended to be a per-service log file.
FILES
/lib/svc/share/smf_include.sh
Definitions of exit status values.
/usr/include/libscf.h
Definitions of exit status codes.
SEE ALSO
svcs(1), zonename(1), exec(2), fork(2), getdefaultproj(3PROJECT),
exec_attr(5), project(5), service_bundle(5), attributes(7),
privileges(7), rbac(7), security-flags(7), smf(7), smf_bootstrap(7),
zones(7), coreadm(8), inetd(8), svc.startd(8), svcadm(8), svccfg(8)
NOTES
The present version of smf(7) does not support multiple repositories.
When a service is configured to be started as root but with privileges
different from limit_privileges, the resulting process is privilege
aware. This can be surprising to developers who expect
seteuid(<non-zero UID>) to reduce privileges to basic or less.
illumos July 18, 2026 illumos