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 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(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.
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 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 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 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_ERR_FATAL |
95 |
Method failed fatally and is unrecoverable 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 and may not be fully functional. |
| 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 value. |
| 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_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
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.
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(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
....
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 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
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(4).
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(5).
limit_privileges
An optional string specifying the limit
privilege set as defined in privileges(5).
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, :home is used.
security_flags
The security flags to apply when launching the
method. See
security-flags(5).
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(1M). 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(4) 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 /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.
zonename(1),
coreadm(1M),
inetd(1M),
svccfg(1M),
svc.startd(1M),
exec(2),
fork(2),
getdefaultproj(3PROJECT),
exec_attr(4),
project(4),
service_bundle(4),
attributes(5),
privileges(5),
rbac(5),
smf(5),
smf_bootstrap(5),
zones(5),
security-flags(5)
The present version of
smf(5) 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.