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
+++ new/usr/src/man/man5/smf_method.5
1 1 '\" te
2 2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 +.\" Copyright 2017 RackTop Systems.
3 4 .\" 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.
4 5 .\" 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
5 6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH SMF_METHOD 5 "June 6, 2016"
7 +.TH SMF_METHOD 5 "Dec 4, 2017"
7 8 .SH NAME
8 9 smf_method \- service management framework conventions for methods
9 10 .SH DESCRIPTION
10 11 .LP
11 12 The class of services managed by \fBsvc.startd\fR(1M) in the service management
12 13 framework, \fBsmf\fR(5), consists of applications that fit a simple
13 14 \fBfork\fR(2)-\fBexec\fR(2) model. The \fBsvc.startd\fR(1M) master daemon and
14 15 other restarters support the \fBfork\fR(2)-\fBexec\fR(2) model, potentially
15 16 with additional capabilities. The \fBsvc.startd\fR(1M) daemon and other
16 17 restarters require that the methods which activate, manipulate, or examine a
17 18 service instance follow the conventions described in this manual page.
18 19 .SS "Invocation form"
19 20 .LP
20 21 The form of a method invocation is not dictated by convention. In some cases, a
21 22 method invocation might consist of the direct invocation of the daemon or other
22 23 binary executable that provides the service. For cases in which an executable
23 24 script or other mediating executable is used, the convention recommends the
24 25 form:
25 26 .sp
26 27 .in +2
27 28 .nf
28 29 /path/to/method_executable abbr_method_name
29 30 .fi
30 31 .in -2
31 32
32 33 .sp
33 34 .LP
34 35 The \fIabbr_method_name\fR used for the recommended form is a supported method
35 36 such as \fBstart\fR or \fBstop\fR. The set of methods supported by a restarter
36 37 is given on the related restarter page. The \fBsvc.startd\fR(1M) daemon
37 38 supports \fBstart\fR, \fBstop\fR, and \fBrefresh\fR methods.
38 39 .sp
39 40 .LP
40 41 A restarter might define other kinds of methods beyond those referenced in this
41 42 page. The conventions surrounding such extensions are defined by the restarter
42 43 and might not be identical to those given here.
43 44 .SS "Environment Variables"
44 45 .LP
45 46 The restarter provides four environment variables to the method that determine
46 47 the context in which the method is invoked.
47 48 .sp
48 49 .ne 2
49 50 .na
50 51 \fB\fBSMF_FMRI\fR\fR
51 52 .ad
52 53 .sp .6
53 54 .RS 4n
54 55 The service fault management resource identifier (FMRI) of the instance for
55 56 which the method is invoked.
56 57 .RE
57 58
58 59 .sp
59 60 .ne 2
60 61 .na
61 62 \fB\fBSMF_METHOD\fR\fR
62 63 .ad
63 64 .sp .6
64 65 .RS 4n
65 66 The full name of the method being invoked, such as \fBstart\fR or \fBstop\fR.
66 67 .RE
67 68
68 69 .sp
69 70 .ne 2
70 71 .na
71 72 \fB\fBSMF_RESTARTER\fR\fR
72 73 .ad
73 74 .sp .6
74 75 .RS 4n
75 76 The service FMRI of the restarter that invokes the method
76 77 .RE
77 78
78 79 .sp
79 80 .ne 2
80 81 .na
81 82 \fB\fBSMF_ZONENAME\fR\fR
82 83 .ad
83 84 .sp .6
84 85 .RS 4n
85 86 The name of the zone in which the method is running. This can also be obtained
86 87 by using the \fBzonename\fR(1) command.
87 88 .RE
88 89
89 90 .sp
90 91 .LP
91 92 These variables should be removed from the environment prior to the invocation
92 93 of any persistent process by the method. A convenience shell function,
93 94 \fBsmf_clear_env\fR, is given for service authors who use Bourne-compatible
94 95 shell scripting to compose service methods in the include file described below.
95 96 .sp
96 97 .LP
97 98 The method context can cause other environment variables to be set as described
98 99 below.
99 100 .SS "Method Definition"
100 101 .LP
101 102 A method is defined minimally by three properties in a propertygroup of type
102 103 \fBmethod\fR.
103 104 .sp
104 105 .LP
105 106 These properties are:
106 107 .sp
107 108 .ne 2
108 109 .na
109 110 \fBexec (\fIastring\fR)\fR
110 111 .ad
111 112 .RS 27n
112 113 Method executable string.
113 114 .RE
114 115
115 116 .sp
116 117 .ne 2
117 118 .na
118 119 \fBtimeout_seconds (\fIcount\fR)\fR
119 120 .ad
120 121 .RS 27n
121 122 Number of seconds before method times out. See the \fBTimeouts\fR section for
122 123 more detail.
123 124 .RE
124 125
125 126 .sp
126 127 .ne 2
127 128 .na
128 129 \fBtype (\fIastring\fR)\fR
129 130 .ad
130 131 .RS 27n
131 132 Method type. Currently always set to \fBmethod\fR.
132 133 .RE
133 134
134 135 .sp
135 136 .LP
136 137 A Method Context can be defined to further refine the execution environment of
137 138 the method. See the \fBMethod Context\fR section for more information.
138 139 .SS "Method Tokens"
139 140 .LP
140 141 When defined in the \fBexec\fR string of the method by the restarter
141 142 \fBsvc.startd\fR, a set of tokens are parsed and expanded with appropriate
142 143 value. Other restarters might not support method tokens. The delegated
143 144 restarter for inet services, \fBinetd\fR(1M), does not support the following
144 145 method expansions.
145 146 .sp
146 147 .ne 2
147 148 .na
148 149 \fB\fB%%\fR\fR
149 150 .ad
150 151 .sp .6
151 152 .RS 4n
152 153 %
153 154 .RE
154 155
155 156 .sp
156 157 .ne 2
157 158 .na
158 159 \fB\fB%r\fR\fR
159 160 .ad
160 161 .sp .6
161 162 .RS 4n
162 163 Name of the restarter, such as \fBsvc.startd\fR
163 164 .RE
164 165
165 166 .sp
166 167 .ne 2
167 168 .na
168 169 \fB\fB%m\fR\fR
169 170 .ad
170 171 .sp .6
171 172 .RS 4n
172 173 The full name of the method being invoked, such as \fBstart\fR or \fBstop\fR.
173 174 .RE
174 175
175 176 .sp
176 177 .ne 2
177 178 .na
178 179 \fB\fB%s\fR\fR
179 180 .ad
180 181 .sp .6
181 182 .RS 4n
182 183 Name of the service
183 184 .RE
184 185
185 186 .sp
186 187 .ne 2
187 188 .na
188 189 \fB\fB%i\fR\fR
189 190 .ad
190 191 .sp .6
191 192 .RS 4n
192 193 Name of the instance
193 194 .RE
194 195
195 196 .sp
196 197 .ne 2
197 198 .na
198 199 \fB\fB\fR\fB%f\fR\fR
199 200 .ad
200 201 .sp .6
201 202 .RS 4n
202 203 FMRI of the instance
203 204 .RE
204 205
205 206 .sp
206 207 .ne 2
207 208 .na
208 209 \fB\fB%{prop[:,]}\fR\fR
209 210 .ad
210 211 .sp .6
211 212 .RS 4n
212 213 Value(s) of a property. The \fBprop\fR might be a property FMRI, a property
213 214 group name and a property name separated by a \fB/\fR, or a property name in
214 215 the \fBapplication\fR property group. These values can be followed by a \fB,\fR
215 216 (comma) or \fB:\fR (colon). If present, the separators are used to separate
216 217 multiple values. If absent, a space is used. The following shell metacharacters
217 218 encountered in string values are quoted with a \ (backslash):
218 219 .sp
219 220 .in +2
220 221 .nf
221 222 ; & ( ) | ^ < > newline space tab \ " '
222 223 .fi
223 224 .in -2
224 225
225 226 An invalid expansion constitutes method failure.
226 227 .RE
227 228
228 229 .sp
229 230 .LP
230 231 Two explicit tokens can be used in the place of method commands.
231 232 .sp
232 233 .ne 2
233 234 .na
234 235 \fB\fB:kill [-signal]\fR\fR
235 236 .ad
236 237 .sp .6
237 238 .RS 4n
238 239 Sends the specified signal, which is \fBSIGTERM\fR by default, to all processes
239 240 in the primary instance contract. Always returns \fBSMF_EXIT_OK\fR. This token
240 241 should be used to replace common \fBpkill\fR invocations.
241 242 .RE
242 243
243 244 .sp
244 245 .ne 2
245 246 .na
246 247 \fB\fB:true\fR\fR
247 248 .ad
248 249 .sp .6
249 250 .RS 4n
250 251 Always returns \fBSMF_EXIT_OK\fR. This token should be used for methods that
251 252 are required by the restarter but which are unnecessary for the particular
252 253 service implementation.
253 254 .RE
254 255
255 256 .SS "Exiting and Exit Status"
256 257 .LP
257 258 The required behavior of a start method is to delay exiting until the service
258 259 instance is ready to answer requests or is otherwise functional.
259 260 .sp
260 261 .LP
261 262 The following exit status codes are defined in \fB<libscf.h>\fR and in the
262 263 shell support file.
263 264 .sp
264 265
265 266 .sp
266 267 .TS
267 268 l l l
↓ open down ↓ |
251 lines elided |
↑ open up ↑ |
268 269 l l l .
269 270 \fBSMF_EXIT_OK\fR \fB0\fR T{
270 271 Method exited, performing its operation successfully.
271 272 T}
272 273 \fBSMF_EXIT_ERR_FATAL\fR \fB95\fR T{
273 274 Method failed fatally and is unrecoverable without administrative intervention.
274 275 T}
275 276 \fBSMF_EXIT_ERR_CONFIG\fR \fB96\fR T{
276 277 Unrecoverable configuration error. A common condition that returns this exit status is the absence of required configuration files for an enabled service instance.
277 278 T}
279 +\fBSMF_EXIT_MON_DEGRADE\fR \fB97\fR T{
280 +Method encountered some problems and may not be fully functional.
281 +T}
278 282 \fBSMF_EXIT_ERR_NOSMF\fR \fB99\fR T{
279 283 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.
280 284 T}
281 285 \fBSMF_EXIT_ERR_PERM\fR \fB100\fR T{
282 286 Method requires a form of permission such as file access, privilege, authorization, or other credential that is not available when invoked.
283 287 T}
284 288 \fBSMF_EXIT_ERR_OTHER\fR \fBnon-zero\fR T{
285 289 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.
286 290 T}
287 291 .TE
288 292
289 293 .sp
290 294 .LP
291 295 Use of a precise exit code allows the responsible restarter to categorize an
292 296 error response as likely to be intermittent and worth pursuing restart or
293 297 permanent and request administrative intervention.
294 298 .SS "Timeouts"
295 299 .LP
296 300 Each method can have an independent timeout, given in seconds. The choice of a
297 301 particular timeout should be based on site expectations for detecting a method
298 302 failure due to non-responsiveness. Sites with replicated filesystems or other
299 303 failover resources can elect to lengthen method timeouts from the default.
300 304 Sites with no remote resources can elect to shorten the timeouts. Method
301 305 timeout is specified by the \fBtimeout_seconds\fR property.
302 306 .sp
303 307 .LP
304 308 If you specify \fB0 timeout_seconds\fR for a method, it declares to the
305 309 restarter that there is no timeout for the service. This setting is not
306 310 preferred, but is available for services that absolutely require it.
307 311 .sp
308 312 .LP
309 313 \fB-1 timeout_seconds\fR is also accepted, but is a deprecated specification.
310 314 .SS "Shell Programming Support"
311 315 .LP
312 316 A set of environment variables that define the above exit status values is
313 317 provided with convenience shell functions in the file
314 318 \fB/lib/svc/share/smf_include.sh\fR. This file is a Bourne shell script
315 319 suitable for inclusion via the source operator in any Bourne-compatible shell.
316 320 .sp
317 321 .LP
318 322 To assist in the composition of scripts that can serve as SMF methods as well
319 323 as \fB/etc/init.d\fR scripts, the \fBsmf_present()\fR shell function is
320 324 provided. If the \fBsmf\fR(5) facility is not available, \fBsmf_present()\fR
321 325 returns a non-zero exit status.
322 326 .sp
323 327 .LP
324 328 One possible structure for such a script follows:
325 329 .sp
326 330 .in +2
327 331 .nf
328 332 if smf_present; then
329 333 # Shell code to run application as managed service
330 334 ....
331 335
332 336 smf_clear_env
333 337 else
334 338 # Shell code to run application as /etc/init.d script
335 339 ....
336 340 fi
337 341 .fi
338 342 .in -2
339 343
340 344 .sp
341 345 .LP
342 346 This example shows the use of both convenience functions that are provided.
343 347 .SS "Method Context"
344 348 .LP
345 349 The service management facility offers a common mechanism set the context in
346 350 which the \fBfork\fR(2)-\fBexec\fR(2) model services execute.
347 351 .sp
348 352 .LP
349 353 The desired method context should be provided by the service developer. All
350 354 service instances should run with the lowest level of privileges possible to
351 355 limit potential security compromises.
352 356 .sp
353 357 .LP
354 358 A method context can contain the following properties:
355 359 .sp
356 360 .ne 2
357 361 .na
358 362 \fB\fBuse_profile\fR\fR
359 363 .ad
360 364 .sp .6
361 365 .RS 4n
362 366 A boolean that specifies whether the profile should be used instead of the
363 367 \fBuser\fR, \fBgroup\fR, \fBprivileges\fR, and \fBlimit_privileges\fR
364 368 properties.
365 369 .RE
366 370
367 371 .sp
368 372 .ne 2
369 373 .na
370 374 \fBenvironment\fR
371 375 .ad
372 376 .sp .6
373 377 .RS 4n
374 378 Environment variables to insert into the environment of the method, in the form
375 379 of a number of \fBNAME=value\fR strings.
376 380 .RE
377 381
378 382 .sp
379 383 .ne 2
380 384 .na
381 385 \fB\fBprofile\fR\fR
382 386 .ad
383 387 .sp .6
384 388 .RS 4n
385 389 The name of an RBAC (role-based access control) profile which, along with the
386 390 method executable, identifies an entry in \fBexec_attr\fR(4).
387 391 .RE
388 392
389 393 .sp
390 394 .ne 2
391 395 .na
392 396 \fB\fBuser\fR\fR
393 397 .ad
394 398 .sp .6
395 399 .RS 4n
396 400 The user ID in numeric or text form.
397 401 .RE
398 402
399 403 .sp
400 404 .ne 2
401 405 .na
402 406 \fB\fBgroup\fR\fR
403 407 .ad
404 408 .sp .6
405 409 .RS 4n
406 410 The group ID in numeric or text form.
407 411 .RE
408 412
409 413 .sp
410 414 .ne 2
411 415 .na
412 416 \fB\fBsupp_groups\fR\fR
413 417 .ad
414 418 .sp .6
415 419 .RS 4n
416 420 An optional string that specifies the supplemental group memberships by ID, in
417 421 numeric or text form.
418 422 .RE
419 423
420 424 .sp
421 425 .ne 2
422 426 .na
423 427 \fB\fBprivileges\fR\fR
424 428 .ad
425 429 .sp .6
426 430 .RS 4n
427 431 An optional string specifying the privilege set as defined in
428 432 \fBprivileges\fR(5).
429 433 .RE
430 434
431 435 .sp
432 436 .ne 2
433 437 .na
434 438 \fB\fBlimit_privileges\fR\fR
435 439 .ad
436 440 .sp .6
437 441 .RS 4n
438 442 An optional string specifying the limit privilege set as defined in
439 443 \fBprivileges\fR(5).
440 444 .RE
441 445
442 446 .sp
443 447 .ne 2
444 448 .na
445 449 \fB\fBworking_directory\fR\fR
446 450 .ad
447 451 .sp .6
448 452 .RS 4n
449 453 The home directory from which to launch the method. \fB:home\fR can be used as
450 454 a token to indicate the home directory of the user whose \fBuid\fR is used to
451 455 launch the method. If the property is unset, \fB:home\fR is used.
452 456 .RE
453 457
454 458 .sp
455 459 .ne 2
456 460 .na
457 461 \fB\fBsecurity_flags\fR\fR
458 462 .ad
459 463 .sp .6
460 464 .RS 4n
461 465 The security flags to apply when launching the method. See \fBsecurity-flags\fR(5).
462 466 .sp
463 467 .LP
464 468 The "default" keyword specifies those flags specified in
465 469 \fBsvc:/system/process-security\fR. The "all" keyword enables all flags, the
466 470 "none" keyword enables no flags. The "current" keyword specifies the current
467 471 flags. Flags may be added by specifying their name (optionally preceded
468 472 by '+'), and removed by preceding their name with '-').
469 473 .sp
470 474 .LP
471 475 Use of "all" has associated risks, as future versions of the system may
472 476 include further flags which may harm poorly implemented software.
473 477 .RE
474 478
475 479 .sp
476 480 .ne 2
477 481 .na
478 482 \fB\fBcorefile_pattern\fR\fR
479 483 .ad
480 484 .sp .6
481 485 .RS 4n
482 486 An optional string that specifies the corefile pattern to use for the service,
483 487 as per \fBcoreadm\fR(1M). Most restarters supply a default. Setting this
484 488 property overrides local customizations to the global core pattern.
485 489 .RE
486 490
487 491 .sp
488 492 .ne 2
489 493 .na
490 494 \fB\fBproject\fR\fR
491 495 .ad
492 496 .sp .6
493 497 .RS 4n
494 498 The project ID in numeric or text form. \fB:default\fR can be used as a token
495 499 to indicate a project identified by \fBgetdefaultproj\fR(3PROJECT) for the user
496 500 whose \fBuid\fR is used to launch the method.
497 501 .RE
498 502
499 503 .sp
500 504 .ne 2
501 505 .na
502 506 \fB\fBresource_pool\fR\fR
503 507 .ad
504 508 .sp .6
505 509 .RS 4n
506 510 The resource pool name on which to launch the method. \fB:default\fR can be
507 511 used as a token to indicate the pool specified in the \fBproject\fR(4) entry
508 512 given in the \fBproject\fR attribute above.
509 513 .RE
510 514
511 515 .sp
512 516 .LP
513 517 The method context can be set for the entire service instance by specifying a
514 518 \fBmethod_context\fR property group for the service or instance. A method might
515 519 override the instance method context by providing the method context properties
516 520 on the method property group.
517 521 .sp
518 522 .LP
519 523 Invalid method context settings always lead to failure of the method, with the
520 524 exception of invalid environment variables that issue warnings.
521 525 .sp
522 526 .LP
523 527 In addition to the context defined above, many \fBfork\fR(2)-\fBexec\fR(2)
524 528 model restarters also use the following conventions when invoking executables
525 529 as methods:
526 530 .sp
527 531 .ne 2
528 532 .na
529 533 \fBArgument array\fR
530 534 .ad
531 535 .sp .6
532 536 .RS 4n
533 537 The arguments in \fBargv[]\fR are set consistently with the result \fB/bin/sh
534 538 -c\fR of the \fBexec\fR string.
535 539 .RE
536 540
537 541 .sp
538 542 .ne 2
539 543 .na
540 544 \fBFile descriptors\fR
541 545 .ad
542 546 .sp .6
543 547 .RS 4n
544 548 File descriptor \fB0\fR is \fB/dev/null\fR. File descriptors \fB1\fR and
545 549 \fB2\fR are recommended to be a per-service log file.
546 550 .RE
547 551
548 552 .SH FILES
549 553 .ne 2
550 554 .na
551 555 \fB\fB/lib/svc/share/smf_include.sh\fR\fR
552 556 .ad
553 557 .sp .6
554 558 .RS 4n
555 559 Definitions of exit status values.
556 560 .RE
557 561
558 562 .sp
559 563 .ne 2
560 564 .na
561 565 \fB\fB/usr/include/libscf.h\fR\fR
562 566 .ad
563 567 .sp .6
564 568 .RS 4n
565 569 Definitions of exit status codes.
566 570 .RE
567 571
568 572 .SH SEE ALSO
569 573 .LP
570 574 \fBzonename\fR(1), \fBcoreadm\fR(1M), \fBinetd\fR(1M), \fBsvccfg\fR(1M),
571 575 \fBsvc.startd\fR(1M), \fBexec\fR(2), \fBfork\fR(2),
572 576 \fBgetdefaultproj\fR(3PROJECT), \fBexec_attr\fR(4), \fBproject\fR(4),
573 577 \fBservice_bundle\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5),
574 578 \fBrbac\fR(5), \fBsmf\fR(5), \fBsmf_bootstrap\fR(5), \fBzones\fR(5),
575 579 \fBsecurity-flags\fR(5)
576 580 .SH NOTES
577 581 .LP
578 582 The present version of \fBsmf\fR(5) does not support multiple repositories.
579 583 .sp
580 584 .LP
581 585 When a service is configured to be started as root but with privileges
582 586 different from \fBlimit_privileges\fR, the resulting process is privilege
583 587 aware. This can be surprising to developers who expect \fBseteuid(<non-zero
584 588 UID>)\fR to reduce privileges to basic or less.
↓ open down ↓ |
297 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX