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 management 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 additional
       capabilities.  The  svc.startd(1M)  daemon  and	other restarters require that the methods which activate, manipulate, or examine a service
       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 services, 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 separated 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 encoun-
		       tered 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 contract. 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 unneces-
		       sary for the particular service implementation.

   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 <libscf.h> and in the shell support file.

       SMF_EXIT_OK	      0 	  Method exited, performing its
					  operation successfully.
       SMF_EXIT_ERR_FATAL     95	  Method failed fatally and  is
					  unrecoverable  without admin-
					  istrative intervention.
       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.
       SMF_EXIT_MON_DEGRADE   97	  Monitor    assesses	service
					  instance as  operating  in  a
					  degraded mode.
       SMF_EXIT_MON_OFFLINE   98	  Monitor    assesses	service
					  instance  as	 non-responsive
					  and effectively offline.
       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.

       SMF_EXIT_ERR_PERM      100	  Method  requires  a  form  of
					  permission   such   as   file
					  access, privilege, authoriza-
					  tion,   or  other  credential
					  that is  not	available  when
					  invoked.
       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  diag-
					  nosed   as  a  fault	by  the
					  restarter or on behalf of the
					  restarter.

       Use of a precise exit code allows the responsible restarter to categorize 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 replicated 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 suitable 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 provided.

   Method Context
       The service management facility offers a common mechanism set the context 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  privi-
       leges 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_priv-
			       ileges properties.

       environment	       Environment variables to insert into the environment 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  executable,  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 supplemental 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 privilege 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 indicate the home directory of
			       the user whose uid will be used to launch the method. If the property is unset, :home is used.

       corefile_pattern        An optional string that specifies the corefile pattern to use for the service, as per coreadm(1M).  Most restarters
			       supply a default. Setting this property overrides local customizations 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 getde-
			       faultproj(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  speci-
			       fied in the project(4) entry given in the project attribute above.

       The  method context can be set for the entire service instance by specifying 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 executa-
       bles 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 descriptors 1 and 2 are recommended to be a per-service 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_bun-
       dle(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)