Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for smf_method (opensolaris section 5)

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 exe-
       cutable 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 four 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 name of the method being invoked, such as start or stop.

       SMF_RESTARTER

	   The service FMRI of the restarter that invokes the method

       SMF_ZONENAME

	   The	name  of  the  zone  in which the method is running. This can also be obtained by
	   using the zonename(1) command.

       These variables should be removed from the environment prior to the invocation of any per-
       sistent	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 can cause other environment variables to be set as described below.

   Method Definition
       A method is defined minimally by three properties in a propertygroup of type method.

       These properties are:

       exec (astring)		  Method executable string.

       timeout_seconds (count)	  Number  of  seconds  before  method times out. See the Timeouts
				  section for more detail.

       type (astring)		  Method type. Currently always set to method.

       A Method Context can be defined to further refine the execution environment of the method.
       See the Method Context section for more information.

   Method Tokens
       When defined in the exec string of the method by the restarter svc.startd, a set of tokens
       are parsed and expanded with appropriate value. Other restarters might not support  method
       tokens. The delegated restarter for inet services, inetd(1M), does not support the follow-
       ing method expansions.

       %%

	   %

       %r

	   Name of the restarter, such as svc.startd

       %m

	   The full name of the method being invoked, 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 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  pri-
	   mary  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 unnecessary 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 functional.

       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_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.

       If you specify 0 timeout_seconds for a method, it declares to the restarter that there  is
       no  timeout  for the service. This setting is not preferred, but is available for services
       that absolutely require it.

       -1 timeout_seconds is also accepted, but is a deprecated specification.

   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-compati-
       ble 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 privileges possible to limit potential secu-
       rity compromises.

       A method context can 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 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 is 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  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 specifying a  method_con-
       text  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 warnings.

       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 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
       zonename(1), coreadm(1M), inetd(1M), svccfg(1M), svc.startd(1M), exec(2), fork(2),  getde-
       faultproj(3PROJECT),  exec_attr(4),  project(4),  service_bundle(4), attributes(5), privi-
       leges(5), rbac(5), smf(5), smf_bootstrap(5), zones(5)

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

SunOS 5.11				    3 May 2008				    smf_method(5)


All times are GMT -4. The time now is 11:26 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password