path: root/usr/src/man/man5/smf_method.5

'\" te
.\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association.
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SMF_METHOD 5 "February 25, 2019"
.SH NAME
smf_method \- service management framework conventions for methods
.SH DESCRIPTION
.LP
The class of services managed by \fBsvc.startd\fR(1M) in the service management
framework, \fBsmf\fR(5), consists of applications that fit a simple
\fBfork\fR(2)-\fBexec\fR(2) model. The \fBsvc.startd\fR(1M) master daemon and
other restarters support the \fBfork\fR(2)-\fBexec\fR(2) model, potentially
with additional capabilities. The \fBsvc.startd\fR(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.
.SS "Invocation form"
.LP
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:
.sp
.in +2
.nf
/path/to/method_executable abbr_method_name
.fi
.in -2

.sp
.LP
The \fIabbr_method_name\fR used for the recommended form is a supported method
such as \fBstart\fR or \fBstop\fR. The set of methods supported by a restarter
is given on the related restarter page. The \fBsvc.startd\fR(1M) daemon
supports \fBstart\fR, \fBstop\fR, and \fBrefresh\fR methods.
.sp
.LP
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.
.SS "Environment Variables"
.LP
The restarter provides four environment variables to the method that determine
the context in which the method is invoked.
.sp
.ne 2
.na
\fB\fBSMF_FMRI\fR\fR
.ad
.sp .6
.RS 4n
The service fault management resource identifier (FMRI) of the instance for
which the method is invoked.
.RE

.sp
.ne 2
.na
\fB\fBSMF_METHOD\fR\fR
.ad
.sp .6
.RS 4n
The full name of the method being invoked, such as \fBstart\fR or \fBstop\fR.
.RE

.sp
.ne 2
.na
\fB\fBSMF_RESTARTER\fR\fR
.ad
.sp .6
.RS 4n
The service FMRI of the restarter that invokes the method
.RE

.sp
.ne 2
.na
\fB\fBSMF_ZONENAME\fR\fR
.ad
.sp .6
.RS 4n
The name of the zone in which the method is running. This can also be obtained
by using the \fBzonename\fR(1) command.
.RE

.sp
.LP
These variables should be removed from the environment prior to the invocation
of any persistent process by the method. A convenience shell function,
\fBsmf_clear_env\fR, is given for service authors who use Bourne-compatible
shell scripting to compose service methods in the include file described below.
.sp
.LP
The method context can cause other environment variables to be set as described
below.
.SS "Method Definition"
.LP
A method is defined minimally by three properties in a propertygroup of type
\fBmethod\fR.
.sp
.LP
These properties are:
.sp
.ne 2
.na
\fBexec (\fIastring\fR)\fR
.ad
.RS 27n
Method executable string.
.RE

.sp
.ne 2
.na
\fBtimeout_seconds (\fIcount\fR)\fR
.ad
.RS 27n
Number of seconds before method times out. See the \fBTimeouts\fR section for
more detail.
.RE

.sp
.ne 2
.na
\fBtype (\fIastring\fR)\fR
.ad
.RS 27n
Method type. Currently always set to \fBmethod\fR.
.RE

.sp
.LP
A Method Context can be defined to further refine the execution environment of
the method. See the \fBMethod Context\fR section for more information.
.SS "Method Tokens"
.LP
When defined in the \fBexec\fR string of the method by the restarter
\fBsvc.startd\fR, a set of tokens are parsed and expanded with appropriate
value. Other restarters might not support method tokens. The delegated
restarter for inet services, \fBinetd\fR(1M), does not support the following
method expansions.
.sp
.ne 2
.na
\fB\fB%%\fR\fR
.ad
.sp .6
.RS 4n
%
.RE

.sp
.ne 2
.na
\fB\fB%r\fR\fR
.ad
.sp .6
.RS 4n
Name of the restarter, such as \fBsvc.startd\fR
.RE

.sp
.ne 2
.na
\fB\fB%m\fR\fR
.ad
.sp .6
.RS 4n
The full name of the method being invoked, such as \fBstart\fR or \fBstop\fR.
.RE

.sp
.ne 2
.na
\fB\fB%s\fR\fR
.ad
.sp .6
.RS 4n
Name of the service
.RE

.sp
.ne 2
.na
\fB\fB%i\fR\fR
.ad
.sp .6
.RS 4n
Name of the instance
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB%f\fR\fR
.ad
.sp .6
.RS 4n
FMRI of the instance
.RE

.sp
.ne 2
.na
\fB\fB%{prop[:,]}\fR\fR
.ad
.sp .6
.RS 4n
Value(s) of a property. The \fBprop\fR might be a property FMRI, a property
group name and a property name separated by a \fB/\fR, or a property name in
the \fBapplication\fR property group. These values can be followed by a \fB,\fR
(comma) or \fB:\fR (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):
.sp
.in +2
.nf
; & ( ) | ^ < > newline space tab  \  " '
.fi
.in -2

An invalid expansion constitutes method failure.
.RE

.sp
.LP
Two explicit tokens can be used in the place of method commands.
.sp
.ne 2
.na
\fB\fB:kill [-signal]\fR\fR
.ad
.sp .6
.RS 4n
Sends the specified signal, which is \fBSIGTERM\fR by default, to all processes
in the primary instance contract. Always returns \fBSMF_EXIT_OK\fR. This token
should be used to replace common \fBpkill\fR invocations.
.RE

.sp
.ne 2
.na
\fB\fB:true\fR\fR
.ad
.sp .6
.RS 4n
Always returns \fBSMF_EXIT_OK\fR. This token should be used for methods that
are required by the restarter but which are unnecessary for the particular
service implementation.
.RE

.SS "Exiting and Exit Status"
.LP
The required behavior of a start method is to delay exiting until the service
instance is ready to answer requests or is otherwise functional.
.sp
.LP
The following exit status codes are defined in \fB<libscf.h>\fR and in the
shell support file.
.sp

.sp
.TS
l l l
l l l .
\fBSMF_EXIT_OK\fR	\fB0\fR	T{
Method exited, performing its operation successfully.
T}
\fBSMF_EXIT_NODAEMON\fR	\fB94\fR	T{
Method exited successfully but purposefully leaves no processes remaining in
the contract; it should be treated as if it had a transient service model.
T}
\fBSMF_EXIT_ERR_FATAL\fR	\fB95\fR	T{
Method failed fatally and is unrecoverable without administrative intervention.
T}
\fBSMF_EXIT_ERR_CONFIG\fR	\fB96\fR	T{
Unrecoverable configuration error. A common condition that returns this exit status is the absence of required configuration files for an enabled service instance.
T}
\fBSMF_EXIT_ERR_NOSMF\fR	\fB99\fR	T{
Method has been mistakenly invoked outside the \fBsmf\fR(5) facility. Services that depend on \fBsmf\fR(5) capabilities should exit with this status value.
T}
\fBSMF_EXIT_ERR_PERM\fR	\fB100\fR	T{
Method requires a form of permission such as file access, privilege, authorization, or other credential that is not available when invoked.
T}
\fBSMF_EXIT_ERR_OTHER\fR	\fBnon-zero\fR	T{
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.
T}
.TE

.sp
.LP
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.
.SS "Timeouts"
.LP
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 \fBtimeout_seconds\fR property.
.sp
.LP
If you specify \fB0 timeout_seconds\fR 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.
.sp
.LP
\fB-1 timeout_seconds\fR is also accepted, but is a deprecated specification.
.SS "Shell Programming Support"
.LP
A set of environment variables that define the above exit status values is
provided with convenience shell functions in the file
\fB/lib/svc/share/smf_include.sh\fR. This file is a Bourne shell script
suitable for inclusion via the source operator in any Bourne-compatible shell.
.sp
.LP
To assist in the composition of scripts that can serve as SMF methods as well
as \fB/etc/init.d\fR scripts, the \fBsmf_present()\fR shell function is
provided. If the \fBsmf\fR(5) facility is not available, \fBsmf_present()\fR
returns a non-zero exit status.
.sp
.LP
One possible structure for such a script follows:
.sp
.in +2
.nf
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
.fi
.in -2

.sp
.LP
This example shows the use of both convenience functions that are provided.
.SS "Method Context"
.LP
The service management facility offers a common mechanism set the context in
which the \fBfork\fR(2)-\fBexec\fR(2) model services execute.
.sp
.LP
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.
.sp
.LP
A method context can contain the following properties:
.sp
.ne 2
.na
\fB\fBuse_profile\fR\fR
.ad
.sp .6
.RS 4n
A boolean that specifies whether the profile should be used instead of the
\fBuser\fR, \fBgroup\fR, \fBprivileges\fR, and \fBlimit_privileges\fR
properties.
.RE

.sp
.ne 2
.na
\fBenvironment\fR
.ad
.sp .6
.RS 4n
Environment variables to insert into the environment of the method, in the form
of a number of \fBNAME=value\fR strings.
.RE

.sp
.ne 2
.na
\fB\fBprofile\fR\fR
.ad
.sp .6
.RS 4n
The name of an RBAC (role-based access control) profile which, along with the
method executable, identifies an entry in \fBexec_attr\fR(4).
.RE

.sp
.ne 2
.na
\fB\fBuser\fR\fR
.ad
.sp .6
.RS 4n
The user ID in numeric or text form.
.RE

.sp
.ne 2
.na
\fB\fBgroup\fR\fR
.ad
.sp .6
.RS 4n
The group ID in numeric or text form.
.RE

.sp
.ne 2
.na
\fB\fBsupp_groups\fR\fR
.ad
.sp .6
.RS 4n
An optional string that specifies the supplemental group memberships by ID, in
numeric or text form.
.RE

.sp
.ne 2
.na
\fB\fBprivileges\fR\fR
.ad
.sp .6
.RS 4n
An optional string specifying the privilege set as defined in
\fBprivileges\fR(5).
.RE

.sp
.ne 2
.na
\fB\fBlimit_privileges\fR\fR
.ad
.sp .6
.RS 4n
An optional string specifying the limit privilege set as defined in
\fBprivileges\fR(5).
.RE

.sp
.ne 2
.na
\fB\fBworking_directory\fR\fR
.ad
.sp .6
.RS 4n
The home directory from which to launch the method. \fB:home\fR can be used as
a token to indicate the home directory of the user whose \fBuid\fR is used to
launch the method. If the property is unset, \fB:home\fR is used.
.RE

.sp
.ne 2
.na
\fB\fBsecurity_flags\fR\fR
.ad
.sp .6
.RS 4n
The security flags to apply when launching the method.  See \fBsecurity-flags\fR(5).
.sp
.LP
The "default" keyword specifies those flags specified in
\fBsvc:/system/process-security\fR.  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 '-').
.sp
.LP
Use of "all" has associated risks, as future versions of the system may
include further flags which may harm poorly implemented software.
.RE

.sp
.ne 2
.na
\fB\fBcorefile_pattern\fR\fR
.ad
.sp .6
.RS 4n
An optional string that specifies the corefile pattern to use for the service,
as per \fBcoreadm\fR(1M). Most restarters supply a default. Setting this
property overrides local customizations to the global core pattern.
.RE

.sp
.ne 2
.na
\fB\fBproject\fR\fR
.ad
.sp .6
.RS 4n
The project ID in numeric or text form. \fB:default\fR can be used as a token
to indicate a project identified by \fBgetdefaultproj\fR(3PROJECT) for the user
whose \fBuid\fR is used to launch the method.
.RE

.sp
.ne 2
.na
\fB\fBresource_pool\fR\fR
.ad
.sp .6
.RS 4n
The resource pool name on which to launch the method. \fB:default\fR can be
used as a token to indicate the pool specified in the \fBproject\fR(4) entry
given in the \fBproject\fR attribute above.
.RE

.sp
.LP
The method context can be set for the entire service instance by specifying a
\fBmethod_context\fR 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.
.sp
.LP
Invalid method context settings always lead to failure of the method, with the
exception of invalid environment variables that issue warnings.
.sp
.LP
In addition to the context defined above, many \fBfork\fR(2)-\fBexec\fR(2)
model restarters also use the following conventions when invoking executables
as methods:
.sp
.ne 2
.na
\fBArgument array\fR
.ad
.sp .6
.RS 4n
The arguments in \fBargv[]\fR are set consistently with the result \fB/bin/sh
-c\fR of the \fBexec\fR string.
.RE

.sp
.ne 2
.na
\fBFile descriptors\fR
.ad
.sp .6
.RS 4n
File descriptor \fB0\fR is \fB/dev/null\fR. File descriptors \fB1\fR and
\fB2\fR are recommended to be a per-service log file.
.RE

.SH FILES
.ne 2
.na
\fB\fB/lib/svc/share/smf_include.sh\fR\fR
.ad
.sp .6
.RS 4n
Definitions of exit status values.
.RE

.sp
.ne 2
.na
\fB\fB/usr/include/libscf.h\fR\fR
.ad
.sp .6
.RS 4n
Definitions of exit status codes.
.RE

.SH SEE ALSO
.LP
\fBzonename\fR(1), \fBcoreadm\fR(1M), \fBinetd\fR(1M), \fBsvccfg\fR(1M),
\fBsvc.startd\fR(1M), \fBexec\fR(2), \fBfork\fR(2),
\fBgetdefaultproj\fR(3PROJECT), \fBexec_attr\fR(4), \fBproject\fR(4),
\fBservice_bundle\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5),
\fBrbac\fR(5), \fBsmf\fR(5), \fBsmf_bootstrap\fR(5), \fBzones\fR(5),
\fBsecurity-flags\fR(5)
.SH NOTES
.LP
The present version of \fBsmf\fR(5) does not support multiple repositories.
.sp
.LP
When a service is configured to be started as root but with privileges
different from \fBlimit_privileges\fR, the resulting process is privilege
aware.  This can be surprising to developers who expect \fBseteuid(<non-zero
UID>)\fR to reduce privileges to basic or less.