Windows PowerShell command on Get-command smf

Manual Pages for UNIX Operating System command usage for man smf_method

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 ser-

vice 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 conven-

tion. In some cases, a method invocation might consist of

the direct invocation of the daemon or other binary execut-

able that provides the service. For cases in which an exe-

cutable 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 sup-

ported method such as start or stop. The set of methods sup-

ported 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

SunOS 5.11 Last change: 20 May 2009 1

Standards, Environments, and Macros smf_method(5)

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) com-

mand. 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 ser-

vice 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 pro-

pertygroup of type method. These properties are: exec (astring) Method executable string.

timeout_seconds (count) Number of seconds before method

times out. See the Timeouts sec-

tion for more detail. type (astring) Method type. Currently always set to method.

A Method Context can be defined to further refine the execu-

tion environment of the method. See the Method Context sec-

tion for more information.

SunOS 5.11 Last change: 20 May 2009 2

Standards, Environments, and Macros smf_method(5)

Method Tokens

When defined in the exec string of the method by the restar-

ter 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 following method expansions.

Name of the restarter, such as svc.startd

The full name of the method being invoked, such as start or stop.

Name of the service

Name of the instance

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.

SunOS 5.11 Last change: 20 May 2009 3

Standards, Environments, and Macros smf_method(5)

Two explicit tokens can be used in the place of method com-

mands.

: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 unnecessary for the particular service implementa-

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

SunOS 5.11 Last change: 20 May 2009 4

Standards, Environments, and Macros smf_method(5)

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 res-

tarter 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 adminis-

trative 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 speci-

fied 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-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)

SunOS 5.11 Last change: 20 May 2009 5

Standards, Environments, and Macros smf_method(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 security 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

SunOS 5.11 Last change: 20 May 2009 6

Standards, Environments, and Macros smf_method(5)

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 direc-

tory 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 restar-

ters 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

SunOS 5.11 Last change: 20 May 2009 7

Standards, Environments, and Macros smf_method(5)

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_context property group for

the service or instance. A method might override the

instance method context by providing the method context pro-

perties on the method property group. Invalid method context settings always lead to failure of

the method, with the exception of invalid environment vari-

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

SunOS 5.11 Last change: 20 May 2009 8

Manual Pages for UNIX Operating System command usage for man smf_method

Standards, Environments, and Macros smf_method(5)

NAME

smf_method - service management framework conventions for

DESCRIPTION

Standards, Environments, and Macros smf_method(5)

SMF_ZONENAME

Standards, Environments, and Macros smf_method(5)

Standards, Environments, and Macros smf_method(5)

Standards, Environments, and Macros smf_method(5)

Standards, Environments, and Macros smf_method(5)

the method, in the form of a number of NAME=value

Standards, Environments, and Macros smf_method(5)

Standards, Environments, and Macros smf_method(5)

Standards, Environments, and Macros smf_method(5)

SEE ALSO