1 SMF_METHOD(5) Standards, Environments, and Macros SMF_METHOD(5)
2
3
4
5 NAME
6 smf_method - service management framework conventions for methods
7
8 DESCRIPTION
9 The class of services managed by svc.startd(1M) in the service
10 management framework, smf(5), consists of applications that fit a
11 simple fork(2)-exec(2) model. The svc.startd(1M) master daemon and
12 other restarters support the fork(2)-exec(2) model, potentially with
13 additional capabilities. The svc.startd(1M) daemon and other restarters
14 require that the methods which activate, manipulate, or examine a
15 service instance follow the conventions described in this manual page.
16
17 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
24 /path/to/method_executable abbr_method_name
25
26
27
28 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
33
34 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
38 Environment Variables
39 The restarter provides four environment variables to the method that
40 determine the context in which the method is invoked.
41
42 SMF_FMRI
43
44 The service fault management resource identifier (FMRI) of the
45 instance for which the method is invoked.
46
47
48 SMF_METHOD
49
50 The full name of the method being invoked, such as start or stop.
51
52
53 SMF_RESTARTER
54
55 The service FMRI of the restarter that invokes the method
56
57
58 SMF_ZONENAME
59
60 The name of the zone in which the method is running. This can also
61 be obtained by using the zonename(1) command.
62
63
64
65 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
71
72 The method context can cause other environment variables to be set as
73 described below.
74
75 Method Definition
76 A method is defined minimally by three properties in a propertygroup of
77 type method.
78
79
80 These properties are:
81
82 exec (astring)
83 Method executable string.
84
85
86 timeout_seconds (count)
87 Number of seconds before method times out.
88 See the Timeouts section for more detail.
89
90
91 type (astring)
92 Method type. Currently always set to method.
93
94
95
96 A Method Context can be defined to further refine the execution
97 environment of the method. See the Method Context section for more
98 information.
99
100 Method Tokens
101 When defined in the exec string of the method by the restarter
102 svc.startd, a set of tokens are parsed and expanded with appropriate
103 value. Other restarters might not support method tokens. The delegated
104 restarter for inet services, inetd(1M), does not support the following
105 method expansions.
106
107 %%
108
109 %
110
111
112 %r
113
114 Name of the restarter, such as svc.startd
115
116
117 %m
118
119 The full name of the method being invoked, such as start or stop.
120
121
122 %s
123
124 Name of the service
125
126
127 %i
128
129 Name of the instance
130
131
132 %f
133
134 FMRI of the instance
135
136
137 %{prop[:,]}
138
139 Value(s) of a property. The prop might be a property FMRI, a
140 property group name and a property name separated by a /, or a
141 property name in the application property group. These values can
142 be followed by a , (comma) or : (colon). If present, the separators
143 are used to separate multiple values. If absent, a space is used.
144 The following shell metacharacters encountered in string values are
145 quoted with a (backslash):
146
147 ; & ( ) | ^ < > newline space tab " '
148
149 An invalid expansion constitutes method failure.
150
151
152
153 Two explicit tokens can be used in the place of method commands.
154
155 :kill [-signal]
156
157 Sends the specified signal, which is SIGTERM by default, to all
158 processes in the primary instance contract. Always returns
159 SMF_EXIT_OK. This token should be used to replace common pkill
160 invocations.
161
162
163 :true
164
165 Always returns SMF_EXIT_OK. This token should be used for methods
166 that are required by the restarter but which are unnecessary for
167 the particular service implementation.
168
169
170 Exiting and Exit Status
171 The required behavior of a start method is to delay exiting until the
172 service instance is ready to answer requests or is otherwise
173 functional.
174
175
176 The following exit status codes are defined in <libscf.h> and in the
177 shell support file.
178
179
180
181
182 SMF_EXIT_OK 0 Method exited,
183 performing its
184 operation
185 successfully.
186 SMF_EXIT_NODAEMON 94 Method exited
187 successfully but
188 purposefully leaves
189 no processes
190 remaining in the
191 contract; it should
192 be treated as if it
193 had a transient
194 service model.
195 SMF_EXIT_ERR_FATAL 95 Method failed
196 fatally and is
197 unrecoverable
198 without
199 administrative
200 intervention.
201 SMF_EXIT_ERR_CONFIG 96 Unrecoverable
202 configuration
203 error. A common
204 condition that
205 returns this exit
206 status is the
207 absence of required
208 configuration files
209 for an enabled
210 service instance.
211 SMF_EXIT_ERR_NOSMF 99 Method has been
212 mistakenly invoked
213 outside the smf(5)
214 facility. Services
215 that depend on
216 smf(5) capabilities
217 should exit with
218 this status value.
219 SMF_EXIT_ERR_PERM 100 Method requires a
220 form of permission
221 such as file
222 access, privilege,
223 authorization, or
224 other credential
225 that is not
226 available when
227 invoked.
228 SMF_EXIT_ERR_OTHER non-zero Any non-zero exit
229 status from a
230 method is treated
231 as an unknown
232 error. A series of
233 unknown errors can
234 be diagnosed as a
235 fault by the
236 restarter or on
237 behalf of the
238 restarter.
239
240
241
242 Use of a precise exit code allows the responsible restarter to
243 categorize an error response as likely to be intermittent and worth
244 pursuing restart or permanent and request administrative intervention.
245
246 Timeouts
247 Each method can have an independent timeout, given in seconds. The
248 choice of a particular timeout should be based on site expectations for
249 detecting a method failure due to non-responsiveness. Sites with
250 replicated filesystems or other failover resources can elect to
251 lengthen method timeouts from the default. Sites with no remote
252 resources can elect to shorten the timeouts. Method timeout is
253 specified by the timeout_seconds property.
254
255
256 If you specify 0 timeout_seconds for a method, it declares to the
257 restarter that there is no timeout for the service. This setting is not
258 preferred, but is available for services that absolutely require it.
259
260
261 -1 timeout_seconds is also accepted, but is a deprecated specification.
262
263 Shell Programming Support
264 A set of environment variables that define the above exit status values
265 is provided with convenience shell functions in the file
266 /lib/svc/share/smf_include.sh. This file is a Bourne shell script
267 suitable for inclusion via the source operator in any Bourne-compatible
268 shell.
269
270
271 To assist in the composition of scripts that can serve as SMF methods
272 as well as /etc/init.d scripts, the smf_present() shell function is
273 provided. If the smf(5) facility is not available, smf_present()
274 returns a non-zero exit status.
275
276
277 One possible structure for such a script follows:
278
279 if smf_present; then
280 # Shell code to run application as managed service
281 ....
282
283 smf_clear_env
284 else
285 # Shell code to run application as /etc/init.d script
286 ....
287 fi
288
289
290
291 This example shows the use of both convenience functions that are
292 provided.
293
294 Method Context
295 The service management facility offers a common mechanism set the
296 context in which the fork(2)-exec(2) model services execute.
297
298
299 The desired method context should be provided by the service developer.
300 All service instances should run with the lowest level of privileges
301 possible to limit potential security compromises.
302
303
304 A method context can contain the following properties:
305
306 use_profile
307
308 A boolean that specifies whether the profile should be used instead
309 of the user, group, privileges, and limit_privileges properties.
310
311
312 environment
313
314 Environment variables to insert into the environment of the method,
315 in the form of a number of NAME=value strings.
316
317
318 profile
319
320 The name of an RBAC (role-based access control) profile which,
321 along with the method executable, identifies an entry in
322 exec_attr(4).
323
324
325 user
326
327 The user ID in numeric or text form.
328
329
330 group
331
332 The group ID in numeric or text form.
333
334
335 supp_groups
336
337 An optional string that specifies the supplemental group
338 memberships by ID, in numeric or text form.
339
340
341 privileges
342
343 An optional string specifying the privilege set as defined in
344 privileges(5).
345
346
347 limit_privileges
348
349 An optional string specifying the limit privilege set as defined in
350 privileges(5).
351
352
353 working_directory
354
355 The home directory from which to launch the method. :home can be
356 used as a token to indicate the home directory of the user whose
357 uid is used to launch the method. If the property is unset, :home
358 is used.
359
360
361 security_flags
362
363 The security flags to apply when launching the method. See
364 security-flags(5).
365
366
367 The "default" keyword specifies those flags specified in
368 svc:/system/process-security. The "all" keyword enables all flags,
369 the "none" keyword enables no flags. The "current" keyword
370 specifies the current flags. Flags may be added by specifying
371 their name (optionally preceded by '+'), and removed by preceding
372 their name with '-').
373
374
375 Use of "all" has associated risks, as future versions of the system
376 may include further flags which may harm poorly implemented
377 software.
378
379
380 corefile_pattern
381
382 An optional string that specifies the corefile pattern to use for
383 the service, as per coreadm(1M). Most restarters supply a default.
384 Setting this property overrides local customizations to the global
385 core pattern.
386
387
388 project
389
390 The project ID in numeric or text form. :default can be used as a
391 token to indicate a project identified by getdefaultproj(3PROJECT)
392 for the user whose uid is used to launch the method.
393
394
395 resource_pool
396
397 The resource pool name on which to launch the method. :default can
398 be used as a token to indicate the pool specified in the project(4)
399 entry given in the project attribute above.
400
401
402
403 The method context can be set for the entire service instance by
404 specifying a method_context property group for the service or instance.
405 A method might override the instance method context by providing the
406 method context properties on the method property group.
407
408
409 Invalid method context settings always lead to failure of the method,
410 with the exception of invalid environment variables that issue
411 warnings.
412
413
414 In addition to the context defined above, many fork(2)-exec(2) model
415 restarters also use the following conventions when invoking executables
416 as methods:
417
418 Argument array
419
420 The arguments in argv[] are set consistently with the result
421 /bin/sh -c of the exec string.
422
423
424 File descriptors
425
426 File descriptor 0 is /dev/null. File descriptors 1 and 2 are
427 recommended to be a per-service log file.
428
429
430 FILES
431 /lib/svc/share/smf_include.sh
432
433 Definitions of exit status values.
434
435
436 /usr/include/libscf.h
437
438 Definitions of exit status codes.
439
440
441 SEE ALSO
442 zonename(1), coreadm(1M), inetd(1M), svccfg(1M), svc.startd(1M),
443 exec(2), fork(2), getdefaultproj(3PROJECT), exec_attr(4), project(4),
444 service_bundle(4), attributes(5), privileges(5), rbac(5), smf(5),
445 smf_bootstrap(5), zones(5), security-flags(5)
446
447 NOTES
448 The present version of smf(5) does not support multiple repositories.
449
450
451 When a service is configured to be started as root but with privileges
452 different from limit_privileges, the resulting process is privilege
453 aware. This can be surprising to developers who expect seteuid(<non-
454 zero UID>) to reduce privileges to basic or less.
455
456
457
458 February 25, 2019 SMF_METHOD(5)