Standards, Environments, and Macros smfmethod(5)
NAME
smfmethod - service management framework conventions for
methods
DESCRIPTION
The class of services managed by svc.startd(1M) in the ser-
vice 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.
Invocation form
The form of a method invocation is not dictated by conven-
tion. In some cases, a method invocation might consist of
the direct invocation of the daemon or other binary execut-
able that provides the service. For cases in which an exe-
cutable script or other mediating executable is used, the
convention recommends the form:
/path/to/methodexecutable abbrmethodname
The abbrmethodname used for the recommended form is a sup-
ported method such as start or stop. The set of methods sup-
ported 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 four environment variables to the
method that determine the context in which the method is
invoked.
SMFMRI
The service fault management resource identifier (FMRI)
of the instance for which the method is invoked.
SMFMETHOD
SunOS 5.11 Last change: 3 May 2008 1
Standards, Environments, and Macros smfmethod(5)
The full name of the method being invoked, such as start
or stop.
SMFRESTARTER
The service FMRI of the restarter that invokes the
method
SMFZONENAME
The name of the zone in which the method is running.
This can also be obtained by using the zonename(1) com-
mand.
These variables should be removed from the environment prior
to the invocation of any persistent process by the method. A
convenience shell function, smfclearenv, is given for ser-
vice 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 pro-
pertygroup of type method.
These properties are:
exec (astring) Method executable string.
timeoutseconds (count) Number of seconds before method
times out. See the Timeouts sec-
tion for more detail.
type (astring) Method type. Currently always set
to method.
A Method Context can be defined to further refine the execu-
tion environment of the method. See the Method Context sec-
tion for more information.
SunOS 5.11 Last change: 3 May 2008 2
Standards, Environments, and Macros smfmethod(5)
Method Tokens
When defined in the exec string of the method by the restar-
ter 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.
SunOS 5.11 Last change: 3 May 2008 3
Standards, Environments, and Macros smfmethod(5)
Two explicit tokens can be used in the place of method com-
mands.
:kill [-signal]
Sends the specified signal, which is SIGTERM by default,
to all processes in the primary instance contract.
Always returns SMFEXITOK. This token should be used to
replace common pkill invocations.
:true
Always returns SMFEXITOK. This token should be used
for methods that are required by the restarter but which
are unnecessary for the particular service implementa-
tion.
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
and in the shell support file.
SMFEXITOK 0 Method exited, performing its
operation successfully.
SMFEXITERFATAL 95 Method failed fatally and is
unrecoverable without admin-
istrative intervention.
SMFEXITERCONFIG 96 Unrecoverable configuration
error. A common condition
that returns this exit status
is the absence of required
configuration files for an
enabled service instance.
SMFEXITERNOSMF 99 Method has been mistakenly
invoked outside the smf(5)
facility. Services that
depend on smf(5) capabilities
should exit with this status
value.
SunOS 5.11 Last change: 3 May 2008 4
Standards, Environments, and Macros smfmethod(5)
SMFEXITERPERM 100 Method requires a form of
permission such as file
access, privilege, authoriza-
tion, or other credential
that is not available when
invoked.
SMFEXITEROTHER 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 res-
tarter 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 adminis-
trative 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 speci-
fied by the timeoutseconds property.
If you specify 0 timeoutseconds 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 timeoutseconds 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/smfinclude.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
smfpresent() shell function is provided. If the smf(5)
SunOS 5.11 Last change: 3 May 2008 5
Standards, Environments, and Macros smfmethod(5)
facility is not available, smfpresent() returns a non-zero
exit status.
One possible structure for such a script follows:
if smfpresent; then
# Shell code to run application as managed service
....
smfclearenv
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:
useprofile
A boolean that specifies whether the profile should be
used instead of the user, group, privileges, and
limitprivileges 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
SunOS 5.11 Last change: 3 May 2008 6
Standards, Environments, and Macros smfmethod(5)
which, along with the method executable, identifies an
entry in execattr(4).
user
The user ID in numeric or text form.
group
The group ID in numeric or text form.
suppgroups
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).
limitprivileges
An optional string specifying the limit privilege set as
defined in privileges(5).
workingdirectory
The home directory from which to launch the method.
:home can be used as a token to indicate the home direc-
tory of the user whose uid is used to launch the method.
If the property is unset, :home is used.
corefilepattern
An optional string that specifies the corefile pattern
to use for the service, as per coreadm(1M). Most restar-
ters 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
SunOS 5.11 Last change: 3 May 2008 7
Standards, Environments, and Macros smfmethod(5)
getdefaultproj(3PROJECT) for the user whose uid is used
to launch the method.
resourcepool
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 methodcontext property group for
the service or instance. A method might override the
instance method context by providing the method context pro-
perties on the method property group.
Invalid method context settings always lead to failure of
the method, with the exception of invalid environment vari-
ables 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/smfinclude.sh
Definitions of exit status values.
/usr/include/libscf.h
Definitions of exit status codes.
SunOS 5.11 Last change: 3 May 2008 8
Standards, Environments, and Macros smfmethod(5)
SEE ALSO
zonename(1), coreadm(1M), inetd(1M), svccfg(1M),
svc.startd(1M), exec(2), fork(2), getdefaultproj(3PROJECT),
execattr(4), project(4), servicebundle(4), attributes(5),
privileges(5), rbac(5), smf(5), smfbootstrap(5), zones(5)
NOTES
The present version of smf(5) does not support multiple
repositories.
SunOS 5.11 Last change: 3 May 2008 9
|
