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