Print this page
7928 Add support for SMF_EXIT_TEMP_TRANSIENT
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/smf_method.5.man.txt
+++ new/usr/src/man/man5/smf_method.5.man.txt
1 1 SMF_METHOD(5) Standards, Environments, and Macros SMF_METHOD(5)
2 2
3 3
4 4
5 5 NAME
6 6 smf_method - service management framework conventions for methods
7 7
8 8 DESCRIPTION
9 9 The class of services managed by svc.startd(1M) in the service
10 10 management framework, smf(5), consists of applications that fit a
11 11 simple fork(2)-exec(2) model. The svc.startd(1M) master daemon and
12 12 other restarters support the fork(2)-exec(2) model, potentially with
13 13 additional capabilities. The svc.startd(1M) daemon and other restarters
14 14 require that the methods which activate, manipulate, or examine a
15 15 service instance follow the conventions described in this manual page.
16 16
17 17 Invocation form
18 18 The form of a method invocation is not dictated by convention. In some
19 19 cases, a method invocation might consist of the direct invocation of
20 20 the daemon or other binary executable that provides the service. For
21 21 cases in which an executable script or other mediating executable is
22 22 used, the convention recommends the form:
23 23
24 24 /path/to/method_executable abbr_method_name
25 25
26 26
27 27
28 28 The abbr_method_name used for the recommended form is a supported
29 29 method such as start or stop. The set of methods supported by a
30 30 restarter is given on the related restarter page. The svc.startd(1M)
31 31 daemon supports start, stop, and refresh methods.
32 32
33 33
34 34 A restarter might define other kinds of methods beyond those referenced
35 35 in this page. The conventions surrounding such extensions are defined
36 36 by the restarter and might not be identical to those given here.
37 37
38 38 Environment Variables
39 39 The restarter provides four environment variables to the method that
40 40 determine the context in which the method is invoked.
41 41
42 42 SMF_FMRI
43 43
44 44 The service fault management resource identifier (FMRI) of the
45 45 instance for which the method is invoked.
46 46
47 47
48 48 SMF_METHOD
49 49
50 50 The full name of the method being invoked, such as start or stop.
51 51
52 52
53 53 SMF_RESTARTER
54 54
55 55 The service FMRI of the restarter that invokes the method
56 56
57 57
58 58 SMF_ZONENAME
59 59
60 60 The name of the zone in which the method is running. This can also
61 61 be obtained by using the zonename(1) command.
62 62
63 63
64 64
65 65 These variables should be removed from the environment prior to the
66 66 invocation of any persistent process by the method. A convenience shell
67 67 function, smf_clear_env, is given for service authors who use Bourne-
68 68 compatible shell scripting to compose service methods in the include
69 69 file described below.
70 70
71 71
72 72 The method context can cause other environment variables to be set as
73 73 described below.
74 74
75 75 Method Definition
76 76 A method is defined minimally by three properties in a propertygroup of
77 77 type method.
78 78
79 79
80 80 These properties are:
81 81
82 82 exec (astring)
83 83 Method executable string.
84 84
85 85
86 86 timeout_seconds (count)
87 87 Number of seconds before method times out.
88 88 See the Timeouts section for more detail.
89 89
90 90
91 91 type (astring)
92 92 Method type. Currently always set to method.
93 93
94 94
95 95
96 96 A Method Context can be defined to further refine the execution
97 97 environment of the method. See the Method Context section for more
98 98 information.
99 99
100 100 Method Tokens
101 101 When defined in the exec string of the method by the restarter
102 102 svc.startd, a set of tokens are parsed and expanded with appropriate
103 103 value. Other restarters might not support method tokens. The delegated
104 104 restarter for inet services, inetd(1M), does not support the following
105 105 method expansions.
106 106
107 107 %%
108 108
109 109 %
110 110
111 111
112 112 %r
113 113
114 114 Name of the restarter, such as svc.startd
115 115
116 116
117 117 %m
118 118
119 119 The full name of the method being invoked, such as start or stop.
120 120
121 121
122 122 %s
123 123
124 124 Name of the service
125 125
126 126
127 127 %i
128 128
129 129 Name of the instance
130 130
131 131
132 132 %f
133 133
134 134 FMRI of the instance
135 135
136 136
137 137 %{prop[:,]}
138 138
139 139 Value(s) of a property. The prop might be a property FMRI, a
140 140 property group name and a property name separated by a /, or a
141 141 property name in the application property group. These values can
142 142 be followed by a , (comma) or : (colon). If present, the separators
143 143 are used to separate multiple values. If absent, a space is used.
144 144 The following shell metacharacters encountered in string values are
145 145 quoted with a (backslash):
146 146
147 147 ; & ( ) | ^ < > newline space tab " '
148 148
149 149 An invalid expansion constitutes method failure.
150 150
151 151
152 152
153 153 Two explicit tokens can be used in the place of method commands.
154 154
155 155 :kill [-signal]
156 156
157 157 Sends the specified signal, which is SIGTERM by default, to all
158 158 processes in the primary instance contract. Always returns
159 159 SMF_EXIT_OK. This token should be used to replace common pkill
160 160 invocations.
161 161
162 162
163 163 :true
164 164
165 165 Always returns SMF_EXIT_OK. This token should be used for methods
166 166 that are required by the restarter but which are unnecessary for
167 167 the particular service implementation.
168 168
169 169
170 170 Exiting and Exit Status
171 171 The required behavior of a start method is to delay exiting until the
|
↓ open down ↓ |
171 lines elided |
↑ open up ↑ |
172 172 service instance is ready to answer requests or is otherwise
173 173 functional.
174 174
175 175
176 176 The following exit status codes are defined in <libscf.h> and in the
177 177 shell support file.
178 178
179 179
180 180
181 181
182 - SMF_EXIT_OK 0 Method exited, performing its operation successfully.
183 - SMF_EXIT_ERR_FATAL 95 Method failed fatally and is unrecoverable without administrative intervention.
184 - 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.
185 - 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.
186 - 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.
187 - 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.
182 + SMF_EXIT_OK 0 Method exited, performing its operation successfully.
183 + SMF_EXIT_ERR_FATAL 95 Method failed fatally and is unrecoverable without administrative intervention.
184 + 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.
185 + 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.
186 + 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.
187 + SMF_EXIT_TEMP_TRANSIENT 101 Method that is normally non-transient is temporarily transient. This is not an error condition and a service returning this value will not be restarted.
188 + 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.
188 189
189 190
190 191
191 192 Use of a precise exit code allows the responsible restarter to
192 193 categorize an error response as likely to be intermittent and worth
193 194 pursuing restart or permanent and request administrative intervention.
194 195
195 196 Timeouts
196 197 Each method can have an independent timeout, given in seconds. The
197 198 choice of a particular timeout should be based on site expectations for
198 199 detecting a method failure due to non-responsiveness. Sites with
199 200 replicated filesystems or other failover resources can elect to
200 201 lengthen method timeouts from the default. Sites with no remote
201 202 resources can elect to shorten the timeouts. Method timeout is
202 203 specified by the timeout_seconds property.
203 204
204 205
205 206 If you specify 0 timeout_seconds for a method, it declares to the
206 207 restarter that there is no timeout for the service. This setting is not
207 208 preferred, but is available for services that absolutely require it.
208 209
209 210
210 211 -1 timeout_seconds is also accepted, but is a deprecated specification.
211 212
212 213 Shell Programming Support
213 214 A set of environment variables that define the above exit status values
214 215 is provided with convenience shell functions in the file
215 216 /lib/svc/share/smf_include.sh. This file is a Bourne shell script
216 217 suitable for inclusion via the source operator in any Bourne-compatible
217 218 shell.
218 219
219 220
220 221 To assist in the composition of scripts that can serve as SMF methods
221 222 as well as /etc/init.d scripts, the smf_present() shell function is
222 223 provided. If the smf(5) facility is not available, smf_present()
223 224 returns a non-zero exit status.
224 225
225 226
226 227 One possible structure for such a script follows:
227 228
228 229 if smf_present; then
229 230 # Shell code to run application as managed service
230 231 ....
231 232
232 233 smf_clear_env
233 234 else
234 235 # Shell code to run application as /etc/init.d script
235 236 ....
236 237 fi
237 238
238 239
239 240
240 241 This example shows the use of both convenience functions that are
241 242 provided.
242 243
243 244 Method Context
244 245 The service management facility offers a common mechanism set the
245 246 context in which the fork(2)-exec(2) model services execute.
246 247
247 248
248 249 The desired method context should be provided by the service developer.
249 250 All service instances should run with the lowest level of privileges
250 251 possible to limit potential security compromises.
251 252
252 253
253 254 A method context can contain the following properties:
254 255
255 256 use_profile
256 257
257 258 A boolean that specifies whether the profile should be used instead
258 259 of the user, group, privileges, and limit_privileges properties.
259 260
260 261
261 262 environment
262 263
263 264 Environment variables to insert into the environment of the method,
264 265 in the form of a number of NAME=value strings.
265 266
266 267
267 268 profile
268 269
269 270 The name of an RBAC (role-based access control) profile which,
270 271 along with the method executable, identifies an entry in
271 272 exec_attr(4).
272 273
273 274
274 275 user
275 276
276 277 The user ID in numeric or text form.
277 278
278 279
279 280 group
280 281
281 282 The group ID in numeric or text form.
282 283
283 284
284 285 supp_groups
285 286
286 287 An optional string that specifies the supplemental group
287 288 memberships by ID, in numeric or text form.
288 289
289 290
290 291 privileges
291 292
292 293 An optional string specifying the privilege set as defined in
293 294 privileges(5).
294 295
295 296
296 297 limit_privileges
297 298
298 299 An optional string specifying the limit privilege set as defined in
299 300 privileges(5).
300 301
301 302
302 303 working_directory
303 304
304 305 The home directory from which to launch the method. :home can be
305 306 used as a token to indicate the home directory of the user whose
306 307 uid is used to launch the method. If the property is unset, :home
307 308 is used.
308 309
309 310
310 311 security_flags
311 312
312 313 The security flags to apply when launching the method. See
313 314 security-flags(5).
314 315
315 316
316 317 The "default" keyword specifies those flags specified in
317 318 svc:/system/process-security. The "all" keyword enables all flags,
318 319 the "none" keyword enables no flags. The "current" keyword
319 320 specifies the current flags. Flags may be added by specifying
320 321 their name (optionally preceded by '+'), and removed by preceding
321 322 their name with '-').
322 323
323 324
324 325 Use of "all" has associated risks, as future versions of the system
325 326 may include further flags which may harm poorly implemented
326 327 software.
327 328
328 329
329 330 corefile_pattern
330 331
331 332 An optional string that specifies the corefile pattern to use for
332 333 the service, as per coreadm(1M). Most restarters supply a default.
333 334 Setting this property overrides local customizations to the global
334 335 core pattern.
335 336
336 337
337 338 project
338 339
339 340 The project ID in numeric or text form. :default can be used as a
340 341 token to indicate a project identified by getdefaultproj(3PROJECT)
341 342 for the user whose uid is used to launch the method.
342 343
343 344
344 345 resource_pool
345 346
346 347 The resource pool name on which to launch the method. :default can
347 348 be used as a token to indicate the pool specified in the project(4)
348 349 entry given in the project attribute above.
349 350
350 351
351 352
352 353 The method context can be set for the entire service instance by
353 354 specifying a method_context property group for the service or instance.
354 355 A method might override the instance method context by providing the
355 356 method context properties on the method property group.
356 357
357 358
358 359 Invalid method context settings always lead to failure of the method,
359 360 with the exception of invalid environment variables that issue
360 361 warnings.
361 362
362 363
363 364 In addition to the context defined above, many fork(2)-exec(2) model
364 365 restarters also use the following conventions when invoking executables
365 366 as methods:
366 367
367 368 Argument array
368 369
369 370 The arguments in argv[] are set consistently with the result
370 371 /bin/sh -c of the exec string.
371 372
372 373
373 374 File descriptors
374 375
375 376 File descriptor 0 is /dev/null. File descriptors 1 and 2 are
376 377 recommended to be a per-service log file.
377 378
378 379
379 380 FILES
380 381 /lib/svc/share/smf_include.sh
381 382
382 383 Definitions of exit status values.
383 384
384 385
385 386 /usr/include/libscf.h
386 387
387 388 Definitions of exit status codes.
388 389
389 390
390 391 SEE ALSO
391 392 zonename(1), coreadm(1M), inetd(1M), svccfg(1M), svc.startd(1M),
392 393 exec(2), fork(2), getdefaultproj(3PROJECT), exec_attr(4), project(4),
393 394 service_bundle(4), attributes(5), privileges(5), rbac(5), smf(5),
394 395 smf_bootstrap(5), zones(5), security-flags(5)
395 396
396 397 NOTES
|
↓ open down ↓ |
199 lines elided |
↑ open up ↑ |
397 398 The present version of smf(5) does not support multiple repositories.
398 399
399 400
400 401 When a service is configured to be started as root but with privileges
401 402 different from limit_privileges, the resulting process is privilege
402 403 aware. This can be surprising to developers who expect seteuid(<non-
403 404 zero UID>) to reduce privileges to basic or less.
404 405
405 406
406 407
407 - June 6, 2016 SMF_METHOD(5)
408 + March 2, 2017 SMF_METHOD(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX