SMF_METHOD(5) Standards, Environments, and Macros SMF_METHOD(5) NNAAMMEE smf_method - service management framework conventions for methods DDEESSCCRRIIPPTTIIOONN The class of services managed by ssvvcc..ssttaarrttdd(1M) in the service management framework, ssmmff(5), consists of applications that fit a simple ffoorrkk(2)-eexxeecc(2) model. The ssvvcc..ssttaarrttdd(1M) master daemon and other restarters support the ffoorrkk(2)-eexxeecc(2) model, potentially with additional capabilities. The ssvvcc..ssttaarrttdd(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. IInnvvooccaattiioonn ffoorrmm 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 _a_b_b_r___m_e_t_h_o_d___n_a_m_e used for the recommended form is a supported method such as ssttaarrtt or ssttoopp. The set of methods supported by a restarter is given on the related restarter page. The ssvvcc..ssttaarrttdd(1M) daemon supports ssttaarrtt, ssttoopp, and rreeffrreesshh 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. EEnnvviirroonnmmeenntt VVaarriiaabblleess The restarter provides four environment variables to the method that determine the context in which the method is invoked. SSMMFF__FFMMRRII The service fault management resource identifier (FMRI) of the instance for which the method is invoked. SSMMFF__MMEETTHHOODD The full name of the method being invoked, such as ssttaarrtt or ssttoopp. SSMMFF__RREESSTTAARRTTEERR The service FMRI of the restarter that invokes the method SSMMFF__ZZOONNEENNAAMMEE The name of the zone in which the method is running. This can also be obtained by using the zzoonneennaammee(1) command. These variables should be removed from the environment prior to the invocation of any persistent process by the method. A convenience shell function, ssmmff__cclleeaarr__eennvv, 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. MMeetthhoodd DDeeffiinniittiioonn A method is defined minimally by three properties in a propertygroup of type mmeetthhoodd. These properties are: eexxeecc ((_a_s_t_r_i_n_g) Method executable string. ttiimmeeoouutt__sseeccoonnddss ((_c_o_u_n_t) Number of seconds before method times out. See the TTiimmeeoouuttss section for more detail. ttyyppee ((_a_s_t_r_i_n_g) Method type. Currently always set to mmeetthhoodd. A Method Context can be defined to further refine the execution environment of the method. See the MMeetthhoodd CCoonntteexxtt section for more information. MMeetthhoodd TTookkeennss When defined in the eexxeecc string of the method by the restarter ssvvcc..ssttaarrttdd, a set of tokens are parsed and expanded with appropriate value. Other restarters might not support method tokens. The delegated restarter for inet services, iinneettdd(1M), does not support the following method expansions. %%%% % %%rr Name of the restarter, such as ssvvcc..ssttaarrttdd %%mm The full name of the method being invoked, such as ssttaarrtt or ssttoopp. %%ss Name of the service %%ii Name of the instance %%ff FMRI of the instance %%{{pprroopp[[::,,]]}} Value(s) of a property. The pprroopp might be a property FMRI, a property group name and a property name separated by a //, or a property name in the aapppplliiccaattiioonn 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. ::kkiillll [[--ssiiggnnaall]] Sends the specified signal, which is SSIIGGTTEERRMM by default, to all processes in the primary instance contract. Always returns SSMMFF__EEXXIITT__OOKK. This token should be used to replace common ppkkiillll invocations. ::ttrruuee Always returns SSMMFF__EEXXIITT__OOKK. This token should be used for methods that are required by the restarter but which are unnecessary for the particular service implementation. EExxiittiinngg aanndd EExxiitt SSttaattuuss 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 <> and in the shell support file. SSMMFF__EEXXIITT__OOKK 00 Method exited, performing its operation successfully. SSMMFF__EEXXIITT__EERRRR__FFAATTAALL 9955 Method failed fatally and is unrecoverable without administrative intervention. SSMMFF__EEXXIITT__EERRRR__CCOONNFFIIGG 9966 Unrecoverable configuration error. A common condition that returns this exit status is the absence of required configuration files for an enabled service instance. SSMMFF__EEXXIITT__EERRRR__NNOOSSMMFF 9999 Method has been mistakenly invoked outside the ssmmff(5) facility. Services that depend on ssmmff(5) capabilities should exit with this status value. SSMMFF__EEXXIITT__EERRRR__PPEERRMM 110000 Method requires a form of permission such as file access, privilege, authorization, or other credential that is not available when invoked. SSMMFF__EEXXIITT__EERRRR__OOTTHHEERR nnoonn--zzeerroo 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. 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. TTiimmeeoouuttss 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 ttiimmeeoouutt__sseeccoonnddss property. If you specify 00 ttiimmeeoouutt__sseeccoonnddss 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. --11 ttiimmeeoouutt__sseeccoonnddss is also accepted, but is a deprecated specification. SShheellll PPrrooggrraammmmiinngg SSuuppppoorrtt A set of environment variables that define the above exit status values is provided with convenience shell functions in the file //lliibb//ssvvcc//sshhaarree//ssmmff__iinncclluuddee..sshh. 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 //eettcc//iinniitt..dd scripts, the ssmmff__pprreesseenntt(()) shell function is provided. If the ssmmff(5) facility is not available, ssmmff__pprreesseenntt(()) 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. MMeetthhoodd CCoonntteexxtt The service management facility offers a common mechanism set the context in which the ffoorrkk(2)-eexxeecc(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 can contain the following properties: uussee__pprrooffiillee A boolean that specifies whether the profile should be used instead of the uusseerr, ggrroouupp, pprriivviilleeggeess, and lliimmiitt__pprriivviilleeggeess properties. eennvviirroonnmmeenntt Environment variables to insert into the environment of the method, in the form of a number of NNAAMMEE==vvaalluuee strings. pprrooffiillee The name of an RBAC (role-based access control) profile which, along with the method executable, identifies an entry in eexxeecc__aattttrr(4). uusseerr The user ID in numeric or text form. ggrroouupp The group ID in numeric or text form. ssuupppp__ggrroouuppss An optional string that specifies the supplemental group memberships by ID, in numeric or text form. pprriivviilleeggeess An optional string specifying the privilege set as defined in pprriivviilleeggeess(5). lliimmiitt__pprriivviilleeggeess An optional string specifying the limit privilege set as defined in pprriivviilleeggeess(5). wwoorrkkiinngg__ddiirreeccttoorryy The home directory from which to launch the method. ::hhoommee can be used as a token to indicate the home directory of the user whose uuiidd is used to launch the method. If the property is unset, ::hhoommee is used. sseeccuurriittyy__ffllaaggss The security flags to apply when launching the method. See sseeccuurriittyy--ffllaaggss(5). The "default" keyword specifies those flags specified in ssvvcc:://ssyysstteemm//pprroocceessss--sseeccuurriittyy. The "all" keyword enables all flags, the "none" keyword enables no flags. Further flags may be added by specifying their name, or removed by specifying their name prefixed by '-' or '!'. Use of "all" has associated risks, as future versions of the system may include further flags which may harm poorly implemented software. ccoorreeffiillee__ppaatttteerrnn An optional string that specifies the corefile pattern to use for the service, as per ccoorreeaaddmm(1M). Most restarters supply a default. Setting this property overrides local customizations to the global core pattern. pprroojjeecctt The project ID in numeric or text form. ::ddeeffaauulltt can be used as a token to indicate a project identified by ggeettddeeffaauullttpprroojj(3PROJECT) for the user whose uuiidd is used to launch the method. rreessoouurrccee__ppooooll The resource pool name on which to launch the method. ::ddeeffaauulltt can be used as a token to indicate the pool specified in the pprroojjeecctt(4) entry given in the pprroojjeecctt attribute above. The method context can be set for the entire service instance by specifying a mmeetthhoodd__ccoonntteexxtt 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 ffoorrkk(2)-eexxeecc(2) model restarters also use the following conventions when invoking executables as methods: AArrgguummeenntt aarrrraayy The arguments in aarrggvv[[]] are set consistently with the result //bbiinn//sshh --cc of the eexxeecc string. FFiillee ddeessccrriippttoorrss File descriptor 00 is //ddeevv//nnuullll. File descriptors 11 and 22 are recommended to be a per-service log file. FFIILLEESS //lliibb//ssvvcc//sshhaarree//ssmmff__iinncclluuddee..sshh Definitions of exit status values. //uussrr//iinncclluuddee//lliibbssccff..hh Definitions of exit status codes. SSEEEE AALLSSOO zzoonneennaammee(1), ccoorreeaaddmm(1M), iinneettdd(1M), ssvvccccffgg(1M), ssvvcc..ssttaarrttdd(1M), eexxeecc(2), ffoorrkk(2), ggeettddeeffaauullttpprroojj(3PROJECT), eexxeecc__aattttrr(4), pprroojjeecctt(4), sseerrvviiccee__bbuunnddllee(4), aattttrriibbuutteess(5), pprriivviilleeggeess(5), rrbbaacc(5), ssmmff(5), ssmmff__bboooottssttrraapp(5), zzoonneess(5), sseeccuurriittyy--ffllaaggss(5) NNOOTTEESS The present version of ssmmff(5) does not support multiple repositories. When a service is configured to be started as root but with privileges different from lliimmiitt__pprriivviilleeggeess, the resulting process is privilege aware. This can be surprising to developers who expect sseetteeuuiidd((<>)) to reduce privileges to basic or less. June 6, 2016 SMF_METHOD(5)