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