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