smf_method(5) Standards, Environments, and Macros smf_method(5)NAMEsmf_method - service management framework conventions for methods
DESCRIPTION
The class of services managed by svc.startd(1M) in the service manage‐
ment 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 addi‐
tional capabilities. The svc.startd(1M) daemon and other restarters
require that the methods which activate, manipulate, or examine a ser‐
vice 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(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.
Environment Variables
The restarter provides three 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 method name of the method that is invoked
SMF_RESTARTER The service FMRI of the restarter that invokes the
method
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 may 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) 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 envi‐
ronment of the method. See the Method Context section for more informa‐
tion.
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(1M), does not support the following
method expansions.
%% %
%r Name of the restarter, such as svc.startd
%m Name of the method, 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 prop‐
erty 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 val‐
ues. 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 ser‐
vice 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 func‐
tional.
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 admin‐
istrative 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_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, authoriza‐
tion, 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 diag‐
nosed as a fault by the
restarter or on behalf of the
restarter.
Use of a precise exit code allows the responsible restarter to catego‐
rize 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 repli‐
cated 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 time‐
out_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 suit‐
able 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 pro‐
vided.
Method Context
The service management facility offers a common mechanism set the con‐
text 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 may contain the following properties:
use_profile A boolean that specifies whether the pro‐
file 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 con‐
trol) 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 sup‐
plemental 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 will be used to launch the
method. If the property is unset, :home is
used.
corefile_pattern An optional string that specifies the core‐
file 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 getdefault‐
proj(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 speci‐
fying 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 warn‐
ings.
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 consis‐
tently 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.
FILES
/lib/svc/share/smf_include.sh
Definitions of exit status values.
/usr/include/libscf.h
Definitions of exit status codes.
SEE ALSOcoreadm(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)NOTES
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.
SunOS 5.10 20 May 2009 smf_method(5)
