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