Print this page
Code review comments from jeffpc
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      -.TH SMF_METHOD 5 "May 20, 2009"
        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      -.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
↓ 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
↓ 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
↓ 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
↓ 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
↓ 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
↓ 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
↓ 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
↓ 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