svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
smf_method(7)
Standards, Environments, Macros, Character Sets, and miscellany
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 manage‐
ment 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 addi‐
tional capabilities. The svc.startd(8) 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(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.
SMF_EXIT_DEGRADED
The method exits, but detects that the service instance has a prob‐
lem that may not require immediate administrative intervention.
This exit code can also be used in a stop method to indicate that
the service instance did not successfully stop, and the stop method
should be retried later.
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 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(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 prop‐
erty group name and a property name separated by a /, or a property
name in the application property group. These values can be fol‐
lowed 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 func‐
tional.
The following exit status codes are defined in <libscf.h> and in the
shell support file.
tab(); lw(1.73i) lw(0.91i) lw(2.86i) SMF_EXIT_OK0T{ Method exited, per‐
forming its operation successfully. T} SMF_EXIT_ERR_FATAL95T{ Method
failed fatally and is unrecoverable without administrative interven‐
tion. T} SMF_EXIT_ERR_CONFIG96T{ Unrecoverable configuration error. A
common condition that returns this exit status is the absence of
required configuration files for an enabled service instance. T}
SMF_EXIT_ERR_NOSMF99T{ Method has been mistakenly invoked outside the
smf(7) facility. Services that depend on smf(7) capabilities should
exit with this status value. T} SMF_EXIT_ERR_PERM100T{ Method requires
a form of permission such as file access, privilege, authorization, or
other credential that is not available when invoked. T}
SMF_EXIT_ERR_OTHERnon-zeroT{ 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. T}
In addition to the exit codes described above, a method may use the
following exit codes in conjunction with smf_method_exit(), available
via smf_method_exit(3SCF), smf_include.sh, and the smf_include.py
Python module:
tab(); lw(1.73i) lw(0.91i) lw(2.86i) SMF_EXIT_TEMP_DISABLE101T{ Method
exits successfully and requests a temporary disable. T}
SMF_EXIT_TEMP_TRANSIENT102T{ Method exits successfully and requests
that it be treated as if its service model was "transient". T}
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, specified in seconds. The
method timeout is specified by the timeout_seconds property.
A timeout is used as a last resort for the service's restarter to
determine that a method has hung or is not making progress. If a time‐
out elapsed, many restarters place the service into the maintenance
state. See svc.startd(8). A significant margin of error is recommended
when specifying a timeout in order to avoid premature failures when the
method is making progress, but the system is temporarily responding
very slowly due to memory, CPU, or I/O load.
60 seconds is a good starting value for methods expected to take only a
second or two. 300 seconds (5 minutes) is appropriate for a method
which commonly takes 30 seconds. Scale up as appropriate for methods
which routinely take longer.
Shorter timeouts can be used if fast failure is desired in order to
prompt administrative intervention. If administrative intervention is
likely to only be to clear the service and start the method again, con‐
sider a longer timeout.
If timeout_seconds is set to 0, there is no timeout for the service.
This setting is not preferred, but is available for services which
absolutely require it. -1 is also accepted to specify no timeout, but
is deprecated.
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(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 pro‐
vided.
Python Programming Support
The same set of exit statuses provided by /lib/svc/share/smf_include.sh
are available in the smf_include module.
Method Context
The service management facility offers a common mechanism to 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
and the lowest clearance that is necessary to limit potential security
compromises.
A method context can contain the following 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
An optional user ID in numeric or text form.
group
An optional group ID in numeric or text form.
supp_groups
An optional string that specifies the supplemental group member‐
ships by ID, in numeric or text form.
privileges
An optional string specifying the privilege set as defined in priv‐
ileges(7). An Extended Policy can be specified here.
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, :home
is used.
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.
clearance
An optional string that specifies the process clearance as speci‐
fied in labels(7). The string may be either ADMIN_LOW, ADMIN_HIGH,
or a hexadecimal string generated by atohexlabel(8). If not speci‐
fied methods are started with the clearance specified in pol‐
icy.conf(5). The default value is ADMIN_HIGH.
trusted_path
An optional string that specifies whether this service runs on the
trusted path. For more information, see the tpd(7) man page. The
default is false. A service running on the Trusted Path is exempt
from the MWAC policy. For more information, see the mwac(7) man
page.
priv_debug
An optional boolean that specifies whether this service runs with
the PPRIV_DEBUG process flag. Setting this true will result in
details of any file access errors or missing required privileges
being printed to the system messages file. These messages will
describe the missing privilege and for file access, name the file
to which access was denied.
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 consistently with the result of
/bin/sh -c of the exec string.
File descriptors
File descriptor 0 is /dev/null. File descriptors 1 and 2 are recom‐
mended to be a per-service log file.
FILES
/lib/svc/share/smf_include.sh
/lib/svc/share/smf_exit_codes.sh
/usr/lib/python-version/vendor-packages/smf_include.py
Definitions of exit status values.
/usr/include/libscf.h
Definitions of exit status codes.
EXAMPLES
Example 1 Report a service-specific configuration error message in the
service log.
A start method might want to use smf_method_exit() to report a service-
specific configuration error message in the service log.
if [ ! -s "$my_config_file" ]; then
smf_method_exit $SMF_EXIT_ERR_CONFIG \
missing_or_empty_config_file \
"$my_config_file is missing or empty"
fi
Example 2 Disable a service that should only run in the global zone
when started in a non-global zone.
A service that should only run in the global zone might want to disable
itself when started in a non-global zone.
if smf_is_nonglobalzone; then
smf_method_exit $SMF_EXIT_TEMP_DISABLE global_zone_only \
"$SMF_FMRI is not supported in a local zone" SUNW_OST_OSCMD
fi
SEE ALSO
zonename(1), exec(2), fork(2), getdefaultproj(3PROJECT),
smf_method_exit(3SCF), exec_attr(5), project(5), service_bundle(5),
attributes(7), mwac(7), labels(7), privileges(7), rbac(7), smf(7),
smf_bootstrap(7), tpd(7), zones(7), atohexlabel(8), coreadm(8),
inetd(8), svc.startd(8), svccfg(8)
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.
Oracle Solaris 11.4 27 Nov 2017 smf_method(7)