Print this page
10451 smf_method(5) man page needs updates after 7928
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 +.\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association.
2 3 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
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 "February 25, 2019"
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
↓ open down ↓ |
245 lines elided |
↑ open up ↑ |
262 263 shell support file.
263 264 .sp
264 265
265 266 .sp
266 267 .TS
267 268 l l l
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}
273 +\fBSMF_EXIT_NODAEMON\fR \fB94\fR T{
274 +Method exited successfully but purposefully leaves no processes remaining in
275 +the contract; it should be treated as if it had a transient service model.
276 +T}
272 277 \fBSMF_EXIT_ERR_FATAL\fR \fB95\fR T{
273 278 Method failed fatally and is unrecoverable without administrative intervention.
274 279 T}
275 280 \fBSMF_EXIT_ERR_CONFIG\fR \fB96\fR T{
276 281 Unrecoverable configuration error. A common condition that returns this exit status is the absence of required configuration files for an enabled service instance.
277 282 T}
278 283 \fBSMF_EXIT_ERR_NOSMF\fR \fB99\fR T{
279 284 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 285 T}
281 286 \fBSMF_EXIT_ERR_PERM\fR \fB100\fR T{
282 287 Method requires a form of permission such as file access, privilege, authorization, or other credential that is not available when invoked.
283 288 T}
284 289 \fBSMF_EXIT_ERR_OTHER\fR \fBnon-zero\fR T{
285 290 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 291 T}
287 292 .TE
288 293
289 294 .sp
290 295 .LP
291 296 Use of a precise exit code allows the responsible restarter to categorize an
292 297 error response as likely to be intermittent and worth pursuing restart or
293 298 permanent and request administrative intervention.
294 299 .SS "Timeouts"
295 300 .LP
296 301 Each method can have an independent timeout, given in seconds. The choice of a
297 302 particular timeout should be based on site expectations for detecting a method
298 303 failure due to non-responsiveness. Sites with replicated filesystems or other
299 304 failover resources can elect to lengthen method timeouts from the default.
300 305 Sites with no remote resources can elect to shorten the timeouts. Method
301 306 timeout is specified by the \fBtimeout_seconds\fR property.
302 307 .sp
303 308 .LP
304 309 If you specify \fB0 timeout_seconds\fR for a method, it declares to the
305 310 restarter that there is no timeout for the service. This setting is not
306 311 preferred, but is available for services that absolutely require it.
307 312 .sp
308 313 .LP
309 314 \fB-1 timeout_seconds\fR is also accepted, but is a deprecated specification.
310 315 .SS "Shell Programming Support"
311 316 .LP
312 317 A set of environment variables that define the above exit status values is
313 318 provided with convenience shell functions in the file
314 319 \fB/lib/svc/share/smf_include.sh\fR. This file is a Bourne shell script
315 320 suitable for inclusion via the source operator in any Bourne-compatible shell.
316 321 .sp
317 322 .LP
318 323 To assist in the composition of scripts that can serve as SMF methods as well
319 324 as \fB/etc/init.d\fR scripts, the \fBsmf_present()\fR shell function is
320 325 provided. If the \fBsmf\fR(5) facility is not available, \fBsmf_present()\fR
321 326 returns a non-zero exit status.
322 327 .sp
323 328 .LP
324 329 One possible structure for such a script follows:
325 330 .sp
326 331 .in +2
327 332 .nf
328 333 if smf_present; then
329 334 # Shell code to run application as managed service
330 335 ....
331 336
332 337 smf_clear_env
333 338 else
334 339 # Shell code to run application as /etc/init.d script
335 340 ....
336 341 fi
337 342 .fi
338 343 .in -2
339 344
340 345 .sp
341 346 .LP
342 347 This example shows the use of both convenience functions that are provided.
343 348 .SS "Method Context"
344 349 .LP
345 350 The service management facility offers a common mechanism set the context in
346 351 which the \fBfork\fR(2)-\fBexec\fR(2) model services execute.
347 352 .sp
348 353 .LP
349 354 The desired method context should be provided by the service developer. All
350 355 service instances should run with the lowest level of privileges possible to
351 356 limit potential security compromises.
352 357 .sp
353 358 .LP
354 359 A method context can contain the following properties:
355 360 .sp
356 361 .ne 2
357 362 .na
358 363 \fB\fBuse_profile\fR\fR
359 364 .ad
360 365 .sp .6
361 366 .RS 4n
362 367 A boolean that specifies whether the profile should be used instead of the
363 368 \fBuser\fR, \fBgroup\fR, \fBprivileges\fR, and \fBlimit_privileges\fR
364 369 properties.
365 370 .RE
366 371
367 372 .sp
368 373 .ne 2
369 374 .na
370 375 \fBenvironment\fR
371 376 .ad
372 377 .sp .6
373 378 .RS 4n
374 379 Environment variables to insert into the environment of the method, in the form
375 380 of a number of \fBNAME=value\fR strings.
376 381 .RE
377 382
378 383 .sp
379 384 .ne 2
380 385 .na
381 386 \fB\fBprofile\fR\fR
382 387 .ad
383 388 .sp .6
384 389 .RS 4n
385 390 The name of an RBAC (role-based access control) profile which, along with the
386 391 method executable, identifies an entry in \fBexec_attr\fR(4).
387 392 .RE
388 393
389 394 .sp
390 395 .ne 2
391 396 .na
392 397 \fB\fBuser\fR\fR
393 398 .ad
394 399 .sp .6
395 400 .RS 4n
396 401 The user ID in numeric or text form.
397 402 .RE
398 403
399 404 .sp
400 405 .ne 2
401 406 .na
402 407 \fB\fBgroup\fR\fR
403 408 .ad
404 409 .sp .6
405 410 .RS 4n
406 411 The group ID in numeric or text form.
407 412 .RE
408 413
409 414 .sp
410 415 .ne 2
411 416 .na
412 417 \fB\fBsupp_groups\fR\fR
413 418 .ad
414 419 .sp .6
415 420 .RS 4n
416 421 An optional string that specifies the supplemental group memberships by ID, in
417 422 numeric or text form.
418 423 .RE
419 424
420 425 .sp
421 426 .ne 2
422 427 .na
423 428 \fB\fBprivileges\fR\fR
424 429 .ad
425 430 .sp .6
426 431 .RS 4n
427 432 An optional string specifying the privilege set as defined in
428 433 \fBprivileges\fR(5).
429 434 .RE
430 435
431 436 .sp
432 437 .ne 2
433 438 .na
434 439 \fB\fBlimit_privileges\fR\fR
435 440 .ad
436 441 .sp .6
437 442 .RS 4n
438 443 An optional string specifying the limit privilege set as defined in
439 444 \fBprivileges\fR(5).
440 445 .RE
441 446
442 447 .sp
443 448 .ne 2
444 449 .na
445 450 \fB\fBworking_directory\fR\fR
446 451 .ad
447 452 .sp .6
448 453 .RS 4n
449 454 The home directory from which to launch the method. \fB:home\fR can be used as
450 455 a token to indicate the home directory of the user whose \fBuid\fR is used to
451 456 launch the method. If the property is unset, \fB:home\fR is used.
452 457 .RE
453 458
454 459 .sp
455 460 .ne 2
456 461 .na
457 462 \fB\fBsecurity_flags\fR\fR
458 463 .ad
459 464 .sp .6
460 465 .RS 4n
461 466 The security flags to apply when launching the method. See \fBsecurity-flags\fR(5).
462 467 .sp
463 468 .LP
464 469 The "default" keyword specifies those flags specified in
465 470 \fBsvc:/system/process-security\fR. The "all" keyword enables all flags, the
466 471 "none" keyword enables no flags. The "current" keyword specifies the current
467 472 flags. Flags may be added by specifying their name (optionally preceded
468 473 by '+'), and removed by preceding their name with '-').
469 474 .sp
470 475 .LP
471 476 Use of "all" has associated risks, as future versions of the system may
472 477 include further flags which may harm poorly implemented software.
473 478 .RE
474 479
475 480 .sp
476 481 .ne 2
477 482 .na
478 483 \fB\fBcorefile_pattern\fR\fR
479 484 .ad
480 485 .sp .6
481 486 .RS 4n
482 487 An optional string that specifies the corefile pattern to use for the service,
483 488 as per \fBcoreadm\fR(1M). Most restarters supply a default. Setting this
484 489 property overrides local customizations to the global core pattern.
485 490 .RE
486 491
487 492 .sp
488 493 .ne 2
489 494 .na
490 495 \fB\fBproject\fR\fR
491 496 .ad
492 497 .sp .6
493 498 .RS 4n
494 499 The project ID in numeric or text form. \fB:default\fR can be used as a token
495 500 to indicate a project identified by \fBgetdefaultproj\fR(3PROJECT) for the user
496 501 whose \fBuid\fR is used to launch the method.
497 502 .RE
498 503
499 504 .sp
500 505 .ne 2
501 506 .na
502 507 \fB\fBresource_pool\fR\fR
503 508 .ad
504 509 .sp .6
505 510 .RS 4n
506 511 The resource pool name on which to launch the method. \fB:default\fR can be
507 512 used as a token to indicate the pool specified in the \fBproject\fR(4) entry
508 513 given in the \fBproject\fR attribute above.
509 514 .RE
510 515
511 516 .sp
512 517 .LP
513 518 The method context can be set for the entire service instance by specifying a
514 519 \fBmethod_context\fR property group for the service or instance. A method might
515 520 override the instance method context by providing the method context properties
516 521 on the method property group.
517 522 .sp
518 523 .LP
519 524 Invalid method context settings always lead to failure of the method, with the
520 525 exception of invalid environment variables that issue warnings.
521 526 .sp
522 527 .LP
523 528 In addition to the context defined above, many \fBfork\fR(2)-\fBexec\fR(2)
524 529 model restarters also use the following conventions when invoking executables
525 530 as methods:
526 531 .sp
527 532 .ne 2
528 533 .na
529 534 \fBArgument array\fR
530 535 .ad
531 536 .sp .6
532 537 .RS 4n
533 538 The arguments in \fBargv[]\fR are set consistently with the result \fB/bin/sh
534 539 -c\fR of the \fBexec\fR string.
535 540 .RE
536 541
537 542 .sp
538 543 .ne 2
539 544 .na
540 545 \fBFile descriptors\fR
541 546 .ad
542 547 .sp .6
543 548 .RS 4n
544 549 File descriptor \fB0\fR is \fB/dev/null\fR. File descriptors \fB1\fR and
545 550 \fB2\fR are recommended to be a per-service log file.
546 551 .RE
547 552
548 553 .SH FILES
549 554 .ne 2
550 555 .na
551 556 \fB\fB/lib/svc/share/smf_include.sh\fR\fR
552 557 .ad
553 558 .sp .6
554 559 .RS 4n
555 560 Definitions of exit status values.
556 561 .RE
557 562
558 563 .sp
559 564 .ne 2
560 565 .na
561 566 \fB\fB/usr/include/libscf.h\fR\fR
562 567 .ad
563 568 .sp .6
564 569 .RS 4n
565 570 Definitions of exit status codes.
566 571 .RE
567 572
568 573 .SH SEE ALSO
569 574 .LP
570 575 \fBzonename\fR(1), \fBcoreadm\fR(1M), \fBinetd\fR(1M), \fBsvccfg\fR(1M),
571 576 \fBsvc.startd\fR(1M), \fBexec\fR(2), \fBfork\fR(2),
572 577 \fBgetdefaultproj\fR(3PROJECT), \fBexec_attr\fR(4), \fBproject\fR(4),
573 578 \fBservice_bundle\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5),
574 579 \fBrbac\fR(5), \fBsmf\fR(5), \fBsmf_bootstrap\fR(5), \fBzones\fR(5),
575 580 \fBsecurity-flags\fR(5)
576 581 .SH NOTES
577 582 .LP
578 583 The present version of \fBsmf\fR(5) does not support multiple repositories.
579 584 .sp
580 585 .LP
581 586 When a service is configured to be started as root but with privileges
582 587 different from \fBlimit_privileges\fR, the resulting process is privilege
583 588 aware. This can be surprising to developers who expect \fBseteuid(<non-zero
584 589 UID>)\fR to reduce privileges to basic or less.
↓ open down ↓ |
303 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX