unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

smf_method(5)         Standards, Environments, and Macros        smf_method(5)



NAME
       smf_method - service management framework conventions for methods

DESCRIPTION
       The  class of services managed by svc.startd(1M) in the service manage-
       ment framework, smf(5), consists of  applications  that  fit  a  simple
       fork(2)-exec(2)  model.  The  svc.startd(1M)  master  daemon  and other
       restarters support the fork(2)-exec(2) model,  potentially  with  addi-
       tional  capabilities.  The  svc.startd(1M)  daemon and other restarters
       require that the methods which activate, manipulate, or examine a  ser-
       vice instance follow the conventions described in this manual page.

   Invocation form
       The  form of a method invocation is not dictated by convention. In some
       cases, a method invocation might consist of the  direct  invocation  of
       the  daemon  or  other binary executable that provides the service. For
       cases in which an executable script or other  mediating  executable  is
       used, the convention recommends the form:

       /path/to/method_executable abbr_method_name


       The  abbr_method_name  used  for  the  recommended  form is a supported
       method such as start or  stop.  The  set  of  methods  supported  by  a
       restarter  is  given  on the related restarter page. The svc.startd(1M)
       daemon supports start, stop, and refresh methods.

       A restarter might define other kinds of methods beyond those referenced
       in  this  page. The conventions surrounding such extensions are defined
       by the restarter and might not be identical to those given here.

   Environment Variables
       The restarter provides three environment variables to the  method  that
       determine the context in which the method is invoked.

       SMF_FMRI        The service fault management resource identifier (FMRI)
                       of the instance for which the method is invoked.



       SMF_METHOD      The full method name of the method that is invoked



       SMF_RESTARTER   The service FMRI of  the  restarter  that  invokes  the
                       method



       These  variables  should  be  removed from the environment prior to the
       invocation of any persistent process by the method. A convenience shell
       function,  smf_clear_env,  is given for service authors who use Bourne-
       compatible shell scripting to compose service methods  in  the  include
       file described below.

       The  method  context may cause other environment variables to be set as
       described below.

   Method Tokens
       A set of tokens are parsed and expanded with  appropriate  values  from
       the  method  invocation  by  the restarter svc.startd. Other restarters
       might not support method tokens. The delegated restarter for inet  ser-
       vices, inetd(1M), does not support the following method expansions.

       %%              %



       %r              Name of the restarter, such as svc.startd



       %m              Name of the method, such as start or stop



       %s              Name of the service



       %i              Name of the instance



       %f              FMRI of the instance



       %{prop[:,]}     Value(s)  of  a  property. The prop might be a property
                       FMRI, a property group name and a property  name  sepa-
                       rated  by  a  /,  or a property name in the application
                       property group. These values can be  followed  by  a  ,
                       (comma)  or  :  (colon). If present, the separators are
                       used to separate multiple values.  If absent,  a  space
                       is used. The following shell metacharacters encountered
                       in string values are quoted with a  \  (backslash):

                       ; & ( ) | ^ < > newline space tab  \  " '


                       An invalid expansion constitutes method failure.



       Two explicit tokens can be used in the place of method commands.

       :kill [-signal] Sends  the  specified  signal,  which  is  SIGTERM   by
                       default,  to all processes in the primary instance con-
                       tract. Always returns SMF_EXIT_OK. This token should be
                       used to replace common pkill invocations.



       :true           Always  returns  SMF_EXIT_OK. This token should be used
                       for methods that are  required  by  the  restarter  but
                       which are unnecessary for the particular service imple-
                       mentation.



   Exiting and Exit Status
       The required behavior of a start method is to delay exiting  until  the
       service  instance  is  ready  to  answer requests or is otherwise func-
       tional.

       The following exit status codes are defined in <&lt;libscf.h>&gt;  and  in  the
       shell support file.


       tab();   lw(1.731636i)   lw(0.907497i)  lw(2.860867i).   SMF_EXIT_OK0T{
       Method   exited,   performing   its   operation    successfully.     T}
       SMF_EXIT_ERR_FATAL95T{ Method failed fatally and is unrecoverable with-
       out administrative intervention.  T} SMF_EXIT_ERR_CONFIG96T{ Unrecover-
       able  configuration  error.  A  common condition that returns this exit
       status is the absence of required configuration files  for  an  enabled
       service instance.  T} SMF_EXIT_MON_DEGRADE97T{ Monitor assesses service
       instance as operating in a degraded mode.  T}  SMF_EXIT_MON_OFFLINE98T{
       Monitor  assesses  service  instance  as non-responsive and effectively
       offline.  T} SMF_EXIT_ERR_NOSMF99T{ Method has been mistakenly  invoked
       outside  the  smf(5) facility. Services that depend on smf(5) capabili-
       ties should exit with this  status  value.   T}  SMF_EXIT_ERR_PERM100T{
       Method  requires  a  form of permission such as file access, privilege,
       authorization, or other credential that is not available when  invoked.
       T}  SMF_EXIT_ERR_OTHERnon-zeroT{ Any non-zero exit status from a method
       is treated as an unknown error. A series of unknown errors can be diag-
       nosed as a fault by the restarter or on behalf of the restarter.  T}


       Use  of a precise exit code allows the responsible restarter to catego-
       rize an error response as likely to be intermittent and worth  pursuing
       restart or permanent and request administrative intervention.

   Timeouts
       Each  method  can  have  an  independent timeout, given in seconds. The
       choice of a particular timeout should be based on site expectations for
       detecting a method failure due to non-responsiveness. Sites with repli-
       cated filesystems or other failover resources  can  elect  to  lengthen
       method  timeouts  from  the default. Sites with no remote resources can
       elect to shorten the timeouts.  Method  timeout  is  specified  by  the
       timeout_seconds property.

   Shell Programming Support
       A set of environment variables that define the above exit status values
       is  provided   with   convenience   shell   functions   in   the   file
       /lib/svc/share/smf_include.sh. This file is a Bourne shell script suit-
       able for inclusion via the source  operator  in  any  Bourne-compatible
       shell.

       To  assist  in the composition of scripts that can serve as SMF methods
       as well as /etc/init.d scripts, the  smf_present()  shell  function  is
       provided.  If  the  smf(5)  facility  is  not  available, smf_present()
       returns a non-zero exit status.

       One possible structure for such a script follows:

       if smf_present; then
             # Shell code to run application as managed service
             ....

             smf_clear_env
       else
             # Shell code to run application as /etc/init.d script
             ....
       fi


       This example shows the use of both convenience functions that are  pro-
       vided.

   Method Context
       The  service management facility offers a common mechanism set the con-
       text in which the fork(2)-exec(2) model services execute.

       The desired method context should be provided by the service developer.
       All  service  instances  should run with the lowest level of privileges
       possible to limit potential security compromises.

       A method context may contain the following properties:

       use_profile             A boolean that specifies  whether  the  profile
                               should  be  used  instead  of  the user, group,
                               privileges, and limit_privileges properties.



       environment             Environment variables to insert into the  envi-
                               ronment  of the method, in the form of a number
                               of NAME=value strings.



       profile                 The name of an RBAC (role-based access control)
                               profile  which,  along  with  the  method  exe-
                               cutable, identifies an entry in exec_attr(4).



       user                    The user ID in numeric or text form.



       group                   The group ID in numeric or text form.



       supp_groups             An optional string that specifies  the  supple-
                               mental  group  memberships by ID, in numeric or
                               text form.



       privileges              An optional string specifying the privilege set
                               as defined in privileges(5).



       limit_privileges        An  optional string specifying the limit privi-
                               lege set as defined in privileges(5).



       working_directory       The home directory from  which  to  launch  the
                               method.  :home  can be used as a token to indi-
                               cate the home directory of the user  whose  uid
                               will be used to launch the method. If the prop-
                               erty is unset, :home is used.



       corefile_pattern        An optional string that specifies the  corefile
                               pattern  to  use  for the service, as per core-
                               adm(1M).  Most  restarters  supply  a  default.
                               Setting  this  property  overrides  local  cus-
                               tomizations to the global core pattern.



       project                 The  project  ID  in  numeric  or  text   form.
                               :default  can  be used as a token to indicate a
                               project identified by  getdefaultproj(3PROJECT)
                               for  the  user  whose uid is used to launch the
                               method.



       resource_pool           The resource pool name on which to  launch  the
                               method.  :default  can  be  used  as a token to
                               indicate the pool specified in  the  project(4)
                               entry given in the project attribute above.



       The method context can be set for the entire service instance by speci-
       fying a method_context property group for the service  or  instance.  A
       method  might  override  the  instance  method context by providing the
       method context properties on the method property group.

       Invalid method context settings always lead to failure of  the  method,
       with  the  exception  of invalid environment variables that issue warn-
       ings.

       In addition to the context defined above,  many  fork(2)-exec(2)  model
       restarters also use the following conventions when invoking executables
       as methods:

       Argument array          The arguments in argv[]  are  set  consistently
                               with the result /bin/sh -c of the exec string.



       File descriptors        File  descriptor  0 is /dev/null. File descrip-
                               tors 1 and 2 are recommended to be  a  per-ser-
                               vice log file.



FILES
       /lib/svc/share/smf_include.sh

           Definitions of exit status values.



       /usr/include/libscf.h

           Definitions of exit status codes.



SEE ALSO
       coreadm(1M),  inetd(1M),  svccfg(1M), svc.startd(1M), exec(2), fork(2),
       getdefaultproj(3PROJECT), exec_attr(4), project(4),  service_bundle(4),
       attributes(5), privileges(5), rbac(5), smf(5), smf_bootstrap(5)

NOTES
       The present version of smf(5) does not support multiple repositories.



SunOS 5.10                        2 Dec 2004                     smf_method(5)