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_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.
 188 
 189 
 190 
 191        Use of a precise exit code allows the responsible restarter to
 192        categorize an error response as likely to be intermittent and worth
 193        pursuing restart or permanent and request administrative intervention.
 194 
 195    Timeouts
 196        Each method can have an independent timeout, given in seconds. The
 197        choice of a particular timeout should be based on site expectations for
 198        detecting a method failure due to non-responsiveness. Sites with
 199        replicated filesystems or other failover resources can elect to
 200        lengthen method timeouts from the default.  Sites with no remote
 201        resources can elect to shorten the timeouts. Method timeout is
 202        specified by the timeout_seconds property.
 203 
 204 
 205        If you specify 0 timeout_seconds for a method, it declares to the
 206        restarter that there is no timeout for the service. This setting is not
 207        preferred, but is available for services that absolutely require it.
 208 
 209 
 210        -1 timeout_seconds is also accepted, but is a deprecated specification.
 211 
 212    Shell Programming Support
 213        A set of environment variables that define the above exit status values
 214        is provided with convenience shell functions in the file
 215        /lib/svc/share/smf_include.sh. This file is a Bourne shell script
 216        suitable for inclusion via the source operator in any Bourne-compatible
 217        shell.
 218 
 219 
 220        To assist in the composition of scripts that can serve as SMF methods
 221        as well as /etc/init.d scripts, the smf_present() shell function is
 222        provided. If the smf(5) facility is not available, smf_present()
 223        returns a non-zero exit status.
 224 
 225 
 226        One possible structure for such a script follows:
 227 
 228          if smf_present; then
 229                # Shell code to run application as managed service
 230                ....
 231 
 232                smf_clear_env
 233          else
 234                # Shell code to run application as /etc/init.d script
 235                ....
 236          fi
 237 
 238 
 239 
 240        This example shows the use of both convenience functions that are
 241        provided.
 242 
 243    Method Context
 244        The service management facility offers a common mechanism set the
 245        context in which the fork(2)-exec(2) model services execute.
 246 
 247 
 248        The desired method context should be provided by the service developer.
 249        All service instances should run with the lowest level of privileges
 250        possible to limit potential security compromises.
 251 
 252 
 253        A method context can contain the following properties:
 254 
 255        use_profile
 256 
 257            A boolean that specifies whether the profile should be used instead
 258            of the user, group, privileges, and limit_privileges properties.
 259 
 260 
 261        environment
 262 
 263            Environment variables to insert into the environment of the method,
 264            in the form of a number of NAME=value strings.
 265 
 266 
 267        profile
 268 
 269            The name of an RBAC (role-based access control) profile which,
 270            along with the method executable, identifies an entry in
 271            exec_attr(4).
 272 
 273 
 274        user
 275 
 276            The user ID in numeric or text form.
 277 
 278 
 279        group
 280 
 281            The group ID in numeric or text form.
 282 
 283 
 284        supp_groups
 285 
 286            An optional string that specifies the supplemental group
 287            memberships by ID, in numeric or text form.
 288 
 289 
 290        privileges
 291 
 292            An optional string specifying the privilege set as defined in
 293            privileges(5).
 294 
 295 
 296        limit_privileges
 297 
 298            An optional string specifying the limit privilege set as defined in
 299            privileges(5).
 300 
 301 
 302        working_directory
 303 
 304            The home directory from which to launch the method. :home can be
 305            used as a token to indicate the home directory of the user whose
 306            uid is used to launch the method. If the property is unset, :home
 307            is used.
 308 
 309 
 310        security_flags
 311 
 312            The security flags to apply when launching the method.  See
 313            security-flags(5).
 314 
 315 
 316            The "default" keyword specifies those flags specified in
 317            svc:/system/process-security.  The "all" keyword enables all flags,
 318            the "none" keyword enables no flags.  Further flags may be added by
 319            specifying their name, or removed by specifying their name prefixed
 320            by '-' or '!'.
 321 
 322 
 323            Use of "all" has associated risks, as future versions of the system
 324            may include further flags which may harm poorly implemented
 325            software.
 326 
 327 
 328        corefile_pattern
 329 
 330            An optional string that specifies the corefile pattern to use for
 331            the service, as per coreadm(1M). Most restarters supply a default.
 332            Setting this property overrides local customizations to the global
 333            core pattern.
 334 
 335 
 336        project
 337 
 338            The project ID in numeric or text form. :default can be used as a
 339            token to indicate a project identified by getdefaultproj(3PROJECT)
 340            for the user whose uid is used to launch the method.
 341 
 342 
 343        resource_pool
 344 
 345            The resource pool name on which to launch the method. :default can
 346            be used as a token to indicate the pool specified in the project(4)
 347            entry given in the project attribute above.
 348 
 349 
 350 
 351        The method context can be set for the entire service instance by
 352        specifying a method_context property group for the service or instance.
 353        A method might override the instance method context by providing the
 354        method context properties on the method property group.
 355 
 356 
 357        Invalid method context settings always lead to failure of the method,
 358        with the exception of invalid environment variables that issue
 359        warnings.
 360 
 361 
 362        In addition to the context defined above, many fork(2)-exec(2) model
 363        restarters also use the following conventions when invoking executables
 364        as methods:
 365 
 366        Argument array
 367 
 368            The arguments in argv[] are set consistently with the result
 369            /bin/sh -c of the exec string.
 370 
 371 
 372        File descriptors
 373 
 374            File descriptor 0 is /dev/null. File descriptors 1 and 2 are
 375            recommended to be a per-service log file.
 376 
 377 
 378 FILES
 379        /lib/svc/share/smf_include.sh
 380 
 381            Definitions of exit status values.
 382 
 383 
 384        /usr/include/libscf.h
 385 
 386            Definitions of exit status codes.
 387 
 388 
 389 SEE ALSO
 390        zonename(1), coreadm(1M), inetd(1M), svccfg(1M), svc.startd(1M),
 391        exec(2), fork(2), getdefaultproj(3PROJECT), exec_attr(4), project(4),
 392        service_bundle(4), attributes(5), privileges(5), rbac(5), smf(5),
 393        smf_bootstrap(5), zones(5), security-flags(5)
 394 
 395 NOTES
 396        The present version of smf(5) does not support multiple repositories.
 397 
 398 
 399        When a service is configured to be started as root but with privileges
 400        different from limit_privileges, the resulting process is privilege
 401        aware.  This can be surprising to developers who expect seteuid(<non-
 402        zero UID>) to reduce privileges to basic      or less.
 403 
 404 
 405 
 406                                  June 6, 2016                    SMF_METHOD(5)