1smf_method(5) Standards, Environments, and Macros smf_method(5)
2
6 smf_method - service management framework conventions for methods
7
9 The class of services managed by svc.startd(1M) in the service manage‐
10 ment framework, smf(5), consists of applications that fit a simple
11 fork(2)-exec(2) model. The svc.startd(1M) master daemon and other
12 restarters support the fork(2)-exec(2) model, potentially with addi‐
13 tional capabilities. The svc.startd(1M) daemon and other restarters
14 require that the methods which activate, manipulate, or examine a ser‐
15 vice instance follow the conventions described in this manual page.
16 Invocation form
18 The form of a method invocation is not dictated by convention. In some
19 cases, a method invocation might consist of the direct invocation of
20 the daemon or other binary executable that provides the service. For
21 cases in which an executable script or other mediating executable is
22 used, the convention recommends the form:
23 /path/to/method_executable abbr_method_name
25 The abbr_method_name used for the recommended form is a supported
29 method such as start or stop. The set of methods supported by a
30 restarter is given on the related restarter page. The svc.startd(1M)
31 daemon supports start, stop, and refresh methods.
32 A restarter might define other kinds of methods beyond those referenced
35 in this page. The conventions surrounding such extensions are defined
36 by the restarter and might not be identical to those given here.
37 Environment Variables
39 The restarter provides four environment variables to the method that
40 determine the context in which the method is invoked.
41 SMF_FMRI
43 The service fault management resource identifier (FMRI) of the
45 instance for which the method is invoked.
46 SMF_METHOD
49 The full name of the method being invoked, such as start or stop.
51 SMF_RESTARTER
54 The service FMRI of the restarter that invokes the method
56 SMF_ZONENAME
59 The name of the zone in which the method is running. This can also
61 be obtained by using the zonename(1) command.
62 These variables should be removed from the environment prior to the
66 invocation of any persistent process by the method. A convenience shell
67 function, smf_clear_env, is given for service authors who use Bourne-
68 compatible shell scripting to compose service methods in the include
69 file described below.
70 The method context can cause other environment variables to be set as
73 described below.
74 Method Definition
76 A method is defined minimally by three properties in a propertygroup of
77 type method.
78 These properties are:
81 exec (astring) Method executable string.
83 timeout_seconds (count) Number of seconds before method times out.
86 See the Timeouts section for more detail.
87 type (astring) Method type. Currently always set to method.
90 A Method Context can be defined to further refine the execution envi‐
94 ronment of the method. See the Method Context section for more informa‐
95 tion.
96 Method Tokens
98 When defined in the exec string of the method by the restarter
99 svc.startd, a set of tokens are parsed and expanded with appropriate
100 value. Other restarters might not support method tokens. The delegated
101 restarter for inet services, inetd(1M), does not support the following
102 method expansions.
103 %%
105 %
107 %r
110 Name of the restarter, such as svc.startd
112 %m
115 The full name of the method being invoked, such as start or stop.
117 %s
120 Name of the service
122 %i
125 Name of the instance
127 %f
130 FMRI of the instance
132 %{prop[:,]}
135 Value(s) of a property. The prop might be a property FMRI, a prop‐
137 erty group name and a property name separated by a /, or a property
138 name in the application property group. These values can be fol‐
139 lowed by a , (comma) or : (colon). If present, the separators are
140 used to separate multiple values. If absent, a space is used. The
141 following shell metacharacters encountered in string values are
142 quoted with a (backslash):
143 ; & ( ) | ^ < > newline space tab " '
145 An invalid expansion constitutes method failure.
147 Two explicit tokens can be used in the place of method commands.
151 :kill [-signal]
153 Sends the specified signal, which is SIGTERM by default, to all
155 processes in the primary instance contract. Always returns
156 SMF_EXIT_OK. This token should be used to replace common pkill
157 invocations.
158 :true
161 Always returns SMF_EXIT_OK. This token should be used for methods
163 that are required by the restarter but which are unnecessary for
164 the particular service implementation.
165 Exiting and Exit Status
168 The required behavior of a start method is to delay exiting until the
169 service instance is ready to answer requests or is otherwise func‐
170 tional.
171 The following exit status codes are defined in <libscf.h> and in the
174 shell support file.
175 SMF_EXIT_OK 0 Method exited, performing its
180 operation successfully.
181 SMF_EXIT_ERR_FATAL 95 Method failed fatally and is
182 unrecoverable without admin‐
183 istrative intervention.
184 SMF_EXIT_ERR_CONFIG 96 Unrecoverable configuration
185 error. A common condition
186 that returns this exit status
187 is the absence of required
188 configuration files for an
189 enabled service instance.
190 SMF_EXIT_ERR_NOSMF 99 Method has been mistakenly
191 invoked outside the smf(5)
192 facility. Services that
193 depend on smf(5) capabilities
194 should exit with this status
195 value.
196 SMF_EXIT_ERR_PERM 100 Method requires a form of
200 permission such as file
201 access, privilege, authoriza‐
202 tion, or other credential
203 that is not available when
204 invoked.
205 SMF_EXIT_ERR_OTHER non-zero Any non-zero exit status from
206 a method is treated as an
207 unknown error. A series of
208 unknown errors can be diag‐
209 nosed as a fault by the
210 restarter or on behalf of the
211 restarter.
212 Use of a precise exit code allows the responsible restarter to catego‐
216 rize an error response as likely to be intermittent and worth pursuing
217 restart or permanent and request administrative intervention.
218 Timeouts
220 Each method can have an independent timeout, given in seconds. The
221 choice of a particular timeout should be based on site expectations for
222 detecting a method failure due to non-responsiveness. Sites with repli‐
223 cated filesystems or other failover resources can elect to lengthen
224 method timeouts from the default. Sites with no remote resources can
225 elect to shorten the timeouts. Method timeout is specified by the time‐
226 out_seconds property.
227 If you specify 0 timeout_seconds for a method, it declares to the
230 restarter that there is no timeout for the service. This setting is not
231 preferred, but is available for services that absolutely require it.
232 -1 timeout_seconds is also accepted, but is a deprecated specification.
235 Shell Programming Support
237 A set of environment variables that define the above exit status values
238 is provided with convenience shell functions in the file
239 /lib/svc/share/smf_include.sh. This file is a Bourne shell script suit‐
240 able for inclusion via the source operator in any Bourne-compatible
241 shell.
242 To assist in the composition of scripts that can serve as SMF methods
245 as well as /etc/init.d scripts, the smf_present() shell function is
246 provided. If the smf(5) facility is not available, smf_present()
247 returns a non-zero exit status.
248 One possible structure for such a script follows:
251 if smf_present; then
253 # Shell code to run application as managed service
254 ....
255 smf_clear_env
257 else
258 # Shell code to run application as /etc/init.d script
259 ....
260 fi
261 This example shows the use of both convenience functions that are pro‐
265 vided.
266 Method Context
268 The service management facility offers a common mechanism set the con‐
269 text in which the fork(2)-exec(2) model services execute.
270 The desired method context should be provided by the service developer.
273 All service instances should run with the lowest level of privileges
274 possible to limit potential security compromises.
275 A method context can contain the following properties:
278 use_profile
280 A boolean that specifies whether the profile should be used instead
282 of the user, group, privileges, and limit_privileges properties.
283 environment
286 Environment variables to insert into the environment of the method,
288 in the form of a number of NAME=value strings.
289 profile
292 The name of an RBAC (role-based access control) profile which,
294 along with the method executable, identifies an entry in
295 exec_attr(4).
296 user
299 The user ID in numeric or text form.
301 group
304 The group ID in numeric or text form.
306 supp_groups
309 An optional string that specifies the supplemental group member‐
311 ships by ID, in numeric or text form.
312 privileges
315 An optional string specifying the privilege set as defined in priv‐
317 ileges(5).
318 limit_privileges
321 An optional string specifying the limit privilege set as defined in
323 privileges(5).
324 working_directory
327 The home directory from which to launch the method. :home can be
329 used as a token to indicate the home directory of the user whose
330 uid is used to launch the method. If the property is unset, :home
331 is used.
332 corefile_pattern
335 An optional string that specifies the corefile pattern to use for
337 the service, as per coreadm(1M). Most restarters supply a default.
338 Setting this property overrides local customizations to the global
339 core pattern.
340 project
343 The project ID in numeric or text form. :default can be used as a
345 token to indicate a project identified by getdefaultproj(3PROJECT)
346 for the user whose uid is used to launch the method.
347 resource_pool
350 The resource pool name on which to launch the method. :default can
352 be used as a token to indicate the pool specified in the project(4)
353 entry given in the project attribute above.
354 The method context can be set for the entire service instance by speci‐
358 fying a method_context property group for the service or instance. A
359 method might override the instance method context by providing the
360 method context properties on the method property group.
361 Invalid method context settings always lead to failure of the method,
364 with the exception of invalid environment variables that issue warn‐
365 ings.
366 In addition to the context defined above, many fork(2)-exec(2) model
369 restarters also use the following conventions when invoking executables
370 as methods:
371 Argument array
373 The arguments in argv[] are set consistently with the result
375 /bin/sh -c of the exec string.
376 File descriptors
379 File descriptor 0 is /dev/null. File descriptors 1 and 2 are recom‐
381 mended to be a per-service log file.
382
385 /lib/svc/share/smf_include.sh
386 Definitions of exit status values.
388 /usr/include/libscf.h
391 Definitions of exit status codes.
393
396 zonename(1), coreadm(1M), inetd(1M), svccfg(1M), svc.startd(1M),
397 exec(2), fork(2), getdefaultproj(3PROJECT), exec_attr(4), project(4),
398 service_bundle(4), attributes(5), privileges(5), rbac(5), smf(5),
399 smf_bootstrap(5), zones(5)
400
402 The present version of smf(5) does not support multiple repositories.
403 When a service is configured to be started as root but with privileges
406 different from limit_privileges, the resulting process is privilege
407 aware. This can be surprising to developers who expect seteuid(<non-
408 zero UID>) to reduce privileges to basic or less.
409SunOS 5.11 20 May 2009 smf_method(5)