SMF_METHOD(7) | Standards, Environments, and Macros | SMF_METHOD(7) |
/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(8) 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.
SMF_FMRI
SMF_METHOD
SMF_RESTARTER
SMF_ZONENAME
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 can cause other environment variables to be set as described below.
These properties are:
exec (astring)
timeout_seconds (count)
type (astring)
A Method Context can be defined to further refine the execution environment of the method. See the Method Context section for more information.
%%
%r
%m
%s
%i
%f
%{prop[:,]}
; & ( ) | ^ < > newline space tab " '
An invalid expansion constitutes method failure.
Two explicit tokens can be used in the place of method commands.
:kill [-signal]
:true
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_NODAEMON | 94 | Method exited successfully but purposefully leaves no processes remaining in the contract; it should be treated as if it had a transient service model. |
SMF_EXIT_ERR_FATAL | 95 | Method failed fatally and is unrecoverable without administrative 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(7) facility. Services that depend on smf(7) capabilities should exit with this status value. |
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. |
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. |
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.
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.
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(7) 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.
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:
use_profile
environment
profile
user
group
supp_groups
privileges
limit_privileges
working_directory
security_flags
The "default" keyword specifies those flags specified in svc:/system/process-security. The "all" keyword enables all flags, the "none" keyword enables no flags. The "current" keyword specifies the current flags. Flags may be added by specifying their name (optionally preceded by '+'), and removed by preceding their name with '-').
Use of "all" has associated risks, as future versions of the system may include further flags which may harm poorly implemented software.
corefile_pattern
project
resource_pool
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 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
File descriptors
/usr/include/libscf.h
When a service is configured to be started as root but with privileges different from limit_privileges, the resulting process is privilege aware. This can be surprising to developers who expect seteuid(<non-zero UID>) to reduce privileges to basic or less.
February 25, 2019 | OmniOS |