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