7928 Add support for SMF_EXIT_TEMP_TRANSIENT

   1 SMF_METHOD(5)         Standards, Environments, and Macros        SMF_METHOD(5)
   2 
   3 
   4 
   5 NAME
   6        smf_method - service management framework conventions for methods
   7 
   8 DESCRIPTION
   9        The class of services managed by svc.startd(1M) in the service
  10        management framework, smf(5), consists of applications that fit a
  11        simple fork(2)-exec(2) model. The svc.startd(1M) master daemon and
  12        other restarters support the fork(2)-exec(2) model, potentially with
  13        additional capabilities. The svc.startd(1M) daemon and other restarters
  14        require that the methods which activate, manipulate, or examine a
  15        service instance follow the conventions described in this manual page.
  16 
  17    Invocation form
  18        The form of a method invocation is not dictated by convention. In some
  19        cases, a method invocation might consist of the direct invocation of
  20        the daemon or other binary executable that provides the service. For
  21        cases in which an executable script or other mediating executable is
  22        used, the convention recommends the form:
  23 
  24          /path/to/method_executable abbr_method_name
  25 
  26 
  27 
  28        The abbr_method_name used for the recommended form is a supported
  29        method such as start or stop. The set of methods supported by a
  30        restarter is given on the related restarter page. The svc.startd(1M)
  31        daemon supports start, stop, and refresh methods.
  32 
  33 
  34        A restarter might define other kinds of methods beyond those referenced
  35        in this page. The conventions surrounding such extensions are defined
  36        by the restarter and might not be identical to those given here.
  37 
  38    Environment Variables
  39        The restarter provides four environment variables to the method that
  40        determine the context in which the method is invoked.
  41 
  42        SMF_FMRI
  43 
  44            The service fault management resource identifier (FMRI) of the
  45            instance for which the method is invoked.
  46 
  47 
  48        SMF_METHOD
  49 
  50            The full name of the method being invoked, such as start or stop.
  51 
  52 
  53        SMF_RESTARTER
  54 
  55            The service FMRI of the restarter that invokes the method
  56 
  57 
  58        SMF_ZONENAME
  59 
  60            The name of the zone in which the method is running. This can also
  61            be obtained by using the zonename(1) command.
  62 
  63 
  64 
  65        These variables should be removed from the environment prior to the
  66        invocation of any persistent process by the method. A convenience shell
  67        function, smf_clear_env, is given for service authors who use Bourne-
  68        compatible shell scripting to compose service methods in the include
  69        file described below.
  70 
  71 
  72        The method context can cause other environment variables to be set as
  73        described below.
  74 
  75    Method Definition
  76        A method is defined minimally by three properties in a propertygroup of
  77        type method.
  78 
  79 
  80        These properties are:
  81 
  82        exec (astring)
  83                                   Method executable string.
  84 
  85 
  86        timeout_seconds (count)
  87                                   Number of seconds before method times out.
  88                                   See the Timeouts section for more detail.
  89 
  90 
  91        type (astring)
  92                                   Method type. Currently always set to method.
  93 
  94 
  95 
  96        A Method Context can be defined to further refine the execution
  97        environment of the method. See the Method Context section for more
  98        information.
  99 
 100    Method Tokens
 101        When defined in the exec string of the method by the restarter
 102        svc.startd, a set of tokens are parsed and expanded with appropriate
 103        value. Other restarters might not support method tokens. The delegated
 104        restarter for inet services, inetd(1M), does not support the following
 105        method expansions.
 106 
 107        %%
 108 
 109            %
 110 
 111 
 112        %r
 113 
 114            Name of the restarter, such as svc.startd
 115 
 116 
 117        %m
 118 
 119            The full name of the method being invoked, such as start or stop.
 120 
 121 
 122        %s
 123 
 124            Name of the service
 125 
 126 
 127        %i
 128 
 129            Name of the instance
 130 
 131 
 132        %f
 133 
 134            FMRI of the instance
 135 
 136 
 137        %{prop[:,]}
 138 
 139            Value(s) of a property. The prop might be a property FMRI, a
 140            property group name and a property name separated by a /, or a
 141            property name in the application property group. These values can
 142            be followed by a , (comma) or : (colon). If present, the separators
 143            are used to separate multiple values. If absent, a space is used.
 144            The following shell metacharacters encountered in string values are
 145            quoted with a  (backslash):
 146 
 147              ; & ( ) | ^ < > newline space tab          " '
 148 
 149            An invalid expansion constitutes method failure.
 150 
 151 
 152 
 153        Two explicit tokens can be used in the place of method commands.
 154 
 155        :kill [-signal]
 156 
 157            Sends the specified signal, which is SIGTERM by default, to all
 158            processes in the primary instance contract. Always returns
 159            SMF_EXIT_OK. This token should be used to replace common pkill
 160            invocations.
 161 
 162 
 163        :true
 164 
 165            Always returns SMF_EXIT_OK. This token should be used for methods
 166            that are required by the restarter but which are unnecessary for
 167            the particular service implementation.
 168 
 169 
 170    Exiting and Exit Status
 171        The required behavior of a start method is to delay exiting until the
 172        service instance is ready to answer requests or is otherwise
 173        functional.
 174 
 175 
 176        The following exit status codes are defined in <libscf.h> and in   the
 177        shell support file.
 178 
 179 
 180 
 181 
 182        SMF_EXIT_OK               0          Method exited, performing its operation successfully.
 183        SMF_EXIT_ERR_FATAL        95         Method failed fatally and is unrecoverable without administrative intervention.
 184        SMF_EXIT_ERR_CONFIG       96         Unrecoverable configuration error. A common condition that returns this exit status is the absence of required configuration files for an enabled service instance.
 185        SMF_EXIT_ERR_NOSMF        99         Method has been mistakenly invoked outside the smf(5) facility. Services that depend on smf(5) capabilities should exit with this status value.
 186        SMF_EXIT_ERR_PERM         100        Method requires a form of permission such as file access, privilege, authorization, or other credential that is not available when invoked.
 187        SMF_EXIT_TEMP_TRANSIENT   101        Method that is normally non-transient is temporarily transient.  This is not an error condition and a service returning this value will not be restarted.
 188        SMF_EXIT_ERR_OTHER        non-zero   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.
 189 
 190 
 191 
 192        Use of a precise exit code allows the responsible restarter to
 193        categorize an error response as likely to be intermittent and worth
 194        pursuing restart or permanent and request administrative intervention.
 195 
 196    Timeouts
 197        Each method can have an independent timeout, given in seconds. The
 198        choice of a particular timeout should be based on site expectations for
 199        detecting a method failure due to non-responsiveness. Sites with
 200        replicated filesystems or other failover resources can elect to
 201        lengthen method timeouts from the default.  Sites with no remote
 202        resources can elect to shorten the timeouts. Method timeout is
 203        specified by the timeout_seconds property.
 204 
 205 
 206        If you specify 0 timeout_seconds for a method, it declares to the
 207        restarter that there is no timeout for the service. This setting is not
 208        preferred, but is available for services that absolutely require it.
 209 
 210 
 211        -1 timeout_seconds is also accepted, but is a deprecated specification.
 212 
 213    Shell Programming Support
 214        A set of environment variables that define the above exit status values
 215        is provided with convenience shell functions in the file
 216        /lib/svc/share/smf_include.sh. This file is a Bourne shell script
 217        suitable for inclusion via the source operator in any Bourne-compatible
 218        shell.
 219 
 220 
 221        To assist in the composition of scripts that can serve as SMF methods
 222        as well as /etc/init.d scripts, the smf_present() shell function is
 223        provided. If the smf(5) facility is not available, smf_present()
 224        returns a non-zero exit status.
 225 
 226 
 227        One possible structure for such a script follows:
 228 
 229          if smf_present; then
 230                # Shell code to run application as managed service
 231                ....
 232 
 233                smf_clear_env
 234          else
 235                # Shell code to run application as /etc/init.d script
 236                ....
 237          fi
 238 
 239 
 240 
 241        This example shows the use of both convenience functions that are
 242        provided.
 243 
 244    Method Context
 245        The service management facility offers a common mechanism set the
 246        context in which the fork(2)-exec(2) model services execute.
 247 
 248 
 249        The desired method context should be provided by the service developer.
 250        All service instances should run with the lowest level of privileges
 251        possible to limit potential security compromises.
 252 
 253 
 254        A method context can contain the following properties:
 255 
 256        use_profile
 257 
 258            A boolean that specifies whether the profile should be used instead
 259            of the user, group, privileges, and limit_privileges properties.
 260 
 261 
 262        environment
 263 
 264            Environment variables to insert into the environment of the method,
 265            in the form of a number of NAME=value strings.
 266 
 267 
 268        profile
 269 
 270            The name of an RBAC (role-based access control) profile which,
 271            along with the method executable, identifies an entry in
 272            exec_attr(4).
 273 
 274 
 275        user
 276 
 277            The user ID in numeric or text form.
 278 
 279 
 280        group
 281 
 282            The group ID in numeric or text form.
 283 
 284 
 285        supp_groups
 286 
 287            An optional string that specifies the supplemental group
 288            memberships by ID, in numeric or text form.
 289 
 290 
 291        privileges
 292 
 293            An optional string specifying the privilege set as defined in
 294            privileges(5).
 295 
 296 
 297        limit_privileges
 298 
 299            An optional string specifying the limit privilege set as defined in
 300            privileges(5).
 301 
 302 
 303        working_directory
 304 
 305            The home directory from which to launch the method. :home can be
 306            used as a token to indicate the home directory of the user whose
 307            uid is used to launch the method. If the property is unset, :home
 308            is used.
 309 
 310 
 311        security_flags
 312 
 313            The security flags to apply when launching the method.  See
 314            security-flags(5).
 315 
 316 
 317            The "default" keyword specifies those flags specified in
 318            svc:/system/process-security.  The "all" keyword enables all flags,
 319            the "none" keyword enables no flags.  The "current" keyword
 320            specifies the current flags.  Flags may be added by specifying
 321            their name (optionally preceded by '+'), and removed by preceding
 322            their name with '-').
 323 
 324 
 325            Use of "all" has associated risks, as future versions of the system
 326            may include further flags which may harm poorly implemented
 327            software.
 328 
 329 
 330        corefile_pattern
 331 
 332            An optional string that specifies the corefile pattern to use for
 333            the service, as per coreadm(1M). Most restarters supply a default.
 334            Setting this property overrides local customizations to the global
 335            core pattern.
 336 
 337 
 338        project
 339 
 340            The project ID in numeric or text form. :default can be used as a
 341            token to indicate a project identified by getdefaultproj(3PROJECT)
 342            for the user whose uid is used to launch the method.
 343 
 344 
 345        resource_pool
 346 
 347            The resource pool name on which to launch the method. :default can
 348            be used as a token to indicate the pool specified in the project(4)
 349            entry given in the project attribute above.
 350 
 351 
 352 
 353        The method context can be set for the entire service instance by
 354        specifying a method_context property group for the service or instance.
 355        A method might override the instance method context by providing the
 356        method context properties on the method property group.
 357 
 358 
 359        Invalid method context settings always lead to failure of the method,
 360        with the exception of invalid environment variables that issue
 361        warnings.
 362 
 363 
 364        In addition to the context defined above, many fork(2)-exec(2) model
 365        restarters also use the following conventions when invoking executables
 366        as methods:
 367 
 368        Argument array
 369 
 370            The arguments in argv[] are set consistently with the result
 371            /bin/sh -c of the exec string.
 372 
 373 
 374        File descriptors
 375 
 376            File descriptor 0 is /dev/null. File descriptors 1 and 2 are
 377            recommended to be a per-service log file.
 378 
 379 
 380 FILES
 381        /lib/svc/share/smf_include.sh
 382 
 383            Definitions of exit status values.
 384 
 385 
 386        /usr/include/libscf.h
 387 
 388            Definitions of exit status codes.
 389 
 390 
 391 SEE ALSO
 392        zonename(1), coreadm(1M), inetd(1M), svccfg(1M), svc.startd(1M),
 393        exec(2), fork(2), getdefaultproj(3PROJECT), exec_attr(4), project(4),
 394        service_bundle(4), attributes(5), privileges(5), rbac(5), smf(5),
 395        smf_bootstrap(5), zones(5), security-flags(5)
 396 
 397 NOTES
 398        The present version of smf(5) does not support multiple repositories.
 399 
 400 
 401        When a service is configured to be started as root but with privileges
 402        different from limit_privileges, the resulting process is privilege
 403        aware.  This can be surprising to developers who expect seteuid(<non-
 404        zero UID>) to reduce privileges to basic      or less.
 405 
 406 
 407 
 408                                  March 2, 2017                   SMF_METHOD(5)
--- EOF ---