Tribblix: manual page: smf

SMF_METHOD(7) Standards, Environments, and Macros SMF_METHOD(7)

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 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. If no Method Context is present then the service will be
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 will 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, 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(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
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
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. 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.
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.

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 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-
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.

Method Context

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(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, then
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 will start 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
/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.

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.

September 26, 2024 SMF_METHOD(7)